1 Configuration of Properties for ORB
   2 
   3 attributes of propery:
   4 
   5 name        String (* in front means OMG std, otherwise Sun internal)
   6 type        int, String, boolean, float, class (or any class with a public XXX( String ) constructor) 
   7 default
   8 
   9 DEBUG_PROPERTY                      String              setDebugFlags( arg ) ( , list)
  10 *INITIAL_HOST_PROPERTY              String              set var
  11 *INITIAL_PORT_PROPERTY              int                 set var, setInitialServicesPort
  12 SERVER_HOST_PROPERTY                String              set var
  13 SERVER_PORT_PROPERRT                int                 set var
  14 *ORB_ID_PROPERTY                    String              set var
  15 *INITIAL_SERVICES_PROPERTY          URL                 setServicesURL
  16 *ORB_INIT_REF_PROPERTY              String              addORBInitRef
  17 *DEFAULT_INIT_REF_PROPERTY          String              setORBDefaultInitRef
  18 NUMBER_TO_RECLAIM_PROPERTY          int                 set var
  19 ALLOW_LOCAL_OPTIMIZATION            boolean             set var
  20 SOCKET_FACTORY_CLASS_PROPERTY       Class               set var
  21 LISTEN_SOCKET_PROPERTY              String              add mapped to list ( , list of (S:I) )
  22 
  23 *PI_ORB_INITIALIZER_CLASS_PREFIX.*   String             map to class, instantiate, add to list
  24 
  25 PERSISTENT_SERVER_PORT_PROPERTY     int                 setPersistentServerPort
  26 SERVER_ID_PROPERTY                  int                 setPersistentServerId
  27 BAD_SERVER_ID_HANDLER_CLASS_PROPERTY Class              set var (as string)
  28 ACTIVATED_PROPERTY                  boolean             set var
  29 
  30 GIOP transport specific properties:
  31 
  32 HIGH_WATER_MARK_PROPERTY            int                 set var
  33 LOW_WATER_MARK_PROPERTY             int                 set var
  34 GIOP_VERSION                        GIOPVersion         set var (from int.int)
  35 GIOP_FRAGMENT_SIZE                  int                 set var (special checks)
  36 GIOP_BUFFER_SIZE                    int                 set var
  37 GIOP_11_BUFFMGR                     int                 set var (really enum or else 0-2) 
  38 GIOP_12_BUFFMGR                     int                 set var (really enum or else 0-2) 
  39 GIOP_TARGET_ADDRESSING              int                 set mapped var (really enum or else 0-3)
  40 ALWAYS_SEND_CODESET_CTX_PROPERTY    boolean             set var
  41 USE_BOMS                            boolean             set var
  42 USE_BOMS_IN_ENCAPS                  boolean             set var
  43 CHAR_CODESETS                       CodeSetComponent    set var
  44 WCHAR_CODESETS                      CodeSetComponent    set var
  45 
  46 
  47 Parsers
  48 
  49 class IntParserFactory {
  50     static IntParser makeRangeIntParser( int min, int max )  ;
  51 
  52 }
  53    
  54 Parsing process;
  55 
  56 
  57 - construct 
  58 - unify all args, properties into a single properties object props
  59 - for each key k in props
  60     - find matching ParseAction p
  61     - p.parse( k, props.getProperty( k ) ) 
  62 
  63 Design principles:
  64 
  65 1. Get config data out of ORB
  66     Discussion: beans framework does not work this way: instead, it creates the beans,
  67     which are themselves both configuration data and configured component.
  68 
  69     Two models:
  70         a. parse props -> create config data
  71         b. parse props -> create config data -> create components
  72 
  73     However, long-term bean persistence can be used in either model.  Separation of
  74     concerns (and the large size of the ORB class) argues for separating data from
  75     components.
  76 
  77 2. get configuration out of ORB (except for finding config class)
  78     ORB responsibility:
  79         - gather all property, arg data together and make it available
  80         - load the ORB configurator and let it process the data, generate a config object
  81         - ORB is central registry, so ORB configurator store config data in ORB
  82 
  83 3. Extensibility is required
  84 
  85     The ORB will have large subsystems that are pluggable components (examples: aobject adaptors,
  86     transport plugins).  Individual instances of these frameworks will have their own configuration
  87     data.  To solve this, the ORB class will provide (read-only perhaps?) access to the collected
  88     properties.
  89 
  90     While the component config data is not needed in the ORB, it is needed in the ORB config data 
  91     so that bean persistence can be used to create an XML version of the data.
  92 
  93     problem: properties vs. config data: same or not?
  94 
  95     properties: easier to use, also necessary to indicate where to get config data if not default
  96     config data: more powerful
  97 
  98 4. Basic principle: A parser performs an action A based on a value V when it matches a property P. 
  99    Actions can be:
 100     
 101     configObject.setP( V )
 102     configObject.setP( A(V) )
 103     A(V)
 104 
 105 5. ParserActions are composable
 106 
 107     Basic action: Object parse( String arg, String value )
 108     which nicely handles prefix parsing and sharing of actions across multiple keys
 109 
 110     interface Operation {
 111         Object operate( String arg, String value )
 112     }
 113     
 114     interface OperationFactory {
 115         Operation booleanAction() ;
 116 
 117         Operation integerAction() ;
 118 
 119         Operation stringAction() ;
 120         
 121         Operation integerRangeAction( int min, int max ) ;
 122 
 123         Operation listAction( char sep, Operation act ) ;
 124     }
 125 
 126     interface ParserAction {
 127         void parse( String arg, String value ) ;
 128     }
 129 
 130     interface ParserActionFactory {
 131         ParserAction setFieldAction( String fieldName ) ;
 132 
 133         ParserAction setFieldAction( String fieldName, Operation op ) ;
 134 
 135         ParserAction operationAction( Operation op ) ;
 136     }
 137 
 138 6. Parsers are created incrementally:
 139 
 140     Constructor:
 141     new Parser( Class configurationDataClass )
 142         - has the parser class available for useful defaults
 143 
 144     interface PropertyParser {
 145         /** Option must look like a standard property name, which we require here to 
 146         * be ( JavaIdent "." ) * JavaIdent.  The last java ident we will call the tail.
 147         * If tail starts with "ORB", this option will be used in augmentWithArguments.
 148         * This match operates as follows:
 149         * Let name = tail stripped of its ORB prefix.
 150         * (e.g. if tail = ORBLowWaterMark, name = LowWaterMark).
 151         * Then if option is matched, a conversion to the result type of the method named
 152         * get<name> is performed, and set<name> is called on the data object to set the
 153         * result.  
 154         */
 155         void addMatch( String option ) ;
 156 
 157         void addMatch( String option, ParserAction pa )
 158 
 159         void addPrefixMatch( String prefix, ParserAction pa ) 
 160 
 161         /** First constructs a new property object that has props as its default, 
 162         * then enters args into new property object that correspond to property
 163         * names registered in match() calls.
 164         */
 165         Properties augmentWithArguments( Properties props, String[] args ) ;
 166 
 167         /** Parse all matched properties in props, updating data as required 
 168         * by the actions.
 169         */
 170         void parse( Properties props, ORBConfigurationData data ) ;
 171     }
 172 
 173 7. A useful model:
 174 
 175     Provide 
 176 
 177     abstract class ConfigDataBase {
 178         ConfigDataBase( Properties props )
 179         {
 180             ...
 181         }
 182     }
 183 
 184     and then a specific class
 185 
 186     public class ORBConfigData extends ConfigDataBase {
 187         ORBConfigData( Properties props ) 
 188         {
 189             super( props ) ;
 190         }
 191 
 192         private int foo1 = fooDefault ;
 193         private String foo2 = fooDefault2 ;
 194         private boolean foo3 = fooDefault3 ;
 195         private SomeObject foo4 = fooDefault4 ;
 196 
 197         public int getFoo1() { return foo1 ; }
 198         // and similarly
 199     }
 200 
 201     The constructor then uses reflection to automatically handle all of these variables with a number of
 202     assumptions:
 203     a. Standard names:
 204         private <type> foo { = <default> } 
 205         public <type> getFoo() { return foo ; }
 206         as argument: -ORBfoo
 207         as property: com.sun.CORBA.foo  (problems here)
 208     b. type specific parsing
 209         int: from Integer
 210         String: no-op
 211         boolean: true/false (from Boolean)
 212         Class: must be able to load class
 213         class XXX: XXX must have a public XXX( String ) constructor
 214 
 215     Custom parsing?
 216 
 217     What are valid prefixes?
 218     1. provide com.sun.corba.prefix.XXX where XXX defines a prefix to look for
 219        (some security implications)
 220     2. Extend security model to ORB implementation (I like this approach best so far)
 221 
 222 8. ORB config
 223 
 224     public interface ORBConfigurator {
 225         /** This method is called from ORB.init after all ORB properties have been
 226         * collected.  The corba.ORB constructor will make sure that all required
 227         * registries are initialized and empty.  This constructor will also initialize
 228         * some data used in the corba ORB public API, such as support for deferred
 229         * asynchronous invocation.  However, all regisitration including things like
 230         * the dyanmic any factory should take place in the configurator.  This method
 231         * is resonsible for making PI ORBInitializer calls, if PI is configured.
 232         */
 233         void configure( com.sun.corba.se.impl.core.ORB orb ) ;
 234     }
 235 
 236    The ORB will have a default configurator named
 237 
 238     com.sun.corba.se.impl.core.ORBConfiguratorImpl
 239 
 240    and also a property
 241 
 242     com.sun.CORBA.ORBConfiguratorClass
 243 
 244    than can be set to the name of the ORB configurator class to use.  Note that this
 245    implementation can either be a straight Java implementation, or something more
 246    interpretive, such as an XML-based config description.
 247 
 248 9. We need to construct a list of all properties, and then make sure that security is respected. 
 249    The basic security check is just:
 250 
 251     SecurityManager sman = System.getSecurityManager() ;
 252     if (sman != null)
 253         sman.checkPropertyAccess( key )
 254 
 255     and also
 256 
 257     sman.checkPropertiesAccess()
 258 
 259    We can construct a list of all properties as we do now, which allows the ORB
 260    to call System.getProperties() inside a doPrivileged() block.  Then we create
 261    a subclass of java.util.Properties that overrides getProperty to
 262    do the checkPropertyAccess( key ) call.  We also need to overload the
 263    enumerate method, either to make it illegal, call sman.checkPropertiesAccess,
 264    or just filter it to include only the accessible properties.
 265    And we also need to overload store, because it does not call enumerate internally.
 266 
 267    This allows us to provide all properties to an ORBConfigurator, while still preserving
 268    the security model.  Then anyone that needs security can set up property permissions
 269    like com.foo.corba.* to allow access to only the properties they care about.
 270 
 271 10. ORB APIs
 272 
 273     The ORB needs registry support including:
 274         getSubcontractRegistry
 275         getServiceContextRegistry
 276 
 277     The ORB needs to provide access to a basic (and extensible) ORB configuration object,
 278     which supports at a minimum all of the standard CORBA defined properties.
 279 
 280     Also need registries for:
 281         ObjectAdapter (actually already in SubcontractRegistry, but needs extensions to
 282             ObjectAdapterFactory to work fully)
 283         TaggedComponentFactory
 284         TaggedProfileFactory
 285 
 286     What does an empty ORB provide?
 287         - Registration of all ORB components
 288         - Request dispatching to object adapters
 289         - Access to ORB properties data (as secure Properties object)
 290         - Access to ORB arguments
 291         - Access to ORB configuration data (base class, plus collections of base config
 292           data for plugins such as OAs and transports)
 293         - shutdown support (separate tracking of invocations vs. OA tracking in POA case?
 294           How should this be designed?)
 295         - INS support? (perhaps this could be pluggable too?)
 296         - How does create_output_stream get plugged in?
 297         - Can we separate the current IIOP transport into a TransportPluging?
 298         - PI support
 299         - CORBA::ORB API
 300             - NVList, DII
 301             - object <-> string (which includes INS?)
 302             - (dis)connect API for TOA (move all impl to TOAImpl?)
 303             - typecode/any
 304             - FVD 
 305             - initial services registry
 306             - value factory registry
 307             - logging, other M&M support as needed
 308 
 309 ORB classes:
 310 
 311     core.ORB:                           abstract class providing internal interface
 312     corba.ORBImpl:                      internal implementation of CORBA APIs
 313     corba.ORBSingleton:                 the singleton ORB (not much change needed)
 314     corba.ConfigurationDataCollector:   collects all source of config data and canonicalizes it
 315     Interceptor.PIHandler:              the interface for PI
 316     Interceptor.PIHandlerImpl:          standard implementation of PIHandler
 317     corba.ORBConfigurationData:         extensible bean containing all ORB config data
 318 
 319 11. RequestHandler and ORB
 320 
 321     The RH interface is currently implemented in the ORB class, but might better be a separate
 322     class.  The API is currently almost the same as a ServerSubcontract.  Should we regularize
 323     this?  Also, the API would need to be extended to handle shutdown properly.
 324 
 325     Extended API:
 326         - void run(): does not return until shutdown(boolean) is called.
 327         - shutdown(boolean) needs to be here so that requests can be 
 328           synchhronized with shutdown.  This is also a point where OAs
 329           need to be included (currently in shutdownServants)
 330