1 Notes on IOR implementation
   2 
   3 1. Writeable is an interface that can write itself to an OutputStream.
   4 
   5 2. IdEncapsulation is  a particular kind of Writeable that has an Id and
   6    an Encapsulation (a sequence of bytes) representing some other structure
   7    in a CDR encapsulation.
   8 
   9 3. ContainerBase is a base class for containers of IdEncapsulations.
  10 
  11 4. An IOR is a ContainerBase.
  12 
  13 5. A TaggedComponent is not a ContainerBase.
  14 
  15 6. Some (not all) Profiles are ContainerBases.
  16 
  17 7. IIOPAddress contains (host, port)
  18     IIOPServerLocation contains:
  19         - A primary IIOPAddress
  20         - 0 or more secondary IIOPAddresses (these get placed in 
  21           TAG_ALTERNATE_IIOP_ADDRESS components)
  22 
  23 8. IIOPProfileTemplate:
  24     - major, minor version
  25     - 0 or more TaggedComponents
  26     - ObjectKeyTemplate
  27 
  28 9. ObjectKeyTemplate:
  29     - contains only wire data, not internal structures
  30 
  31     write( object id, output stream ): write the object key out 
  32         to the output stream with the given object id
  33         
  34 10. Significant problem: must of the dispatch path code is written in terms of
  35     IORs when it should be based on profiles.  Only a single profile is used in 
  36     a request, and that is what should be passed around.  This needs fixing soon
  37     to accommodate the eventual implementation of CORBA FT, and also to work
  38     properly with the new IOR.
  39 
  40 11. Another question: since profile contains key which contains scid, what if 
  41     we have multiple profiles with different scids?
  42     One answer: create a cluster subcontract that invokes the individual 
  43     profiles for FT.  This may not mesh well with the FT spec.
  44 
  45 12. Uses of IORs in the ORB:
  46 
  47 Activation/ServerManagerImpl.java
  48     - Construct IOR for bad ID handler location forward
  49 corba/ClientDelegate.java
  50     - marshal, getIOR, unmarshal are all questionable and make
  51       poor use of IOR.
  52     - gets forwarded IOR from response
  53     - IORs handled in some service contexts
  54     - createRequest needs to parse IOR
  55         - gets the (one) IIOP profile that we care about
  56         - gets the object key
  57 corba/InitialNamingClient.java
  58     - constructs IOR from address info, object key
  59     - current implementation should use AlternateIIOPAddress components
  60     - constructs IOR with key "INIT" for old bootstrap
  61 corba/ORB.java
  62     - stringify and destringify IOR
  63 corba/ServerDelegate.java
  64     - access IOR from sending context service context
  65     - destroyObjref directly access transient key from a known offset.
  66     - creation sets up key inline with known offsets
  67 core/IOR.java
  68     - IOR sometimes stores a servant
  69     - IOR contains the following
  70         - Object servant
  71         - Endpoint ep
  72         - String codebase
  73         - boolean cachedCodebase
  74         - TaggedComponent localCodeBaseTC
  75         - InternetIOPTag
  76     - The two constructors that take full args also
  77       construct tagged components
  78     - will need alternate address components for INS
  79 core/SendingContextServiceContext.java
  80     - reads IOR from input stream
  81 iiop/CDRInputStream.java
  82     - needs type id, code base from IOR
  83 iiop/IIOPOutputStream.java
  84     - needs to access objkey as a sequence of bytes to realing requests.
  85 POA/GenericPOAClientSC.java
  86     - needs to pull POA ID out of object key
  87     - needs to created a new IOR that has an updated scid
  88 POA/GenericPOAServerSC.java
  89     - creates IORs
  90 TransactionalPOA/TransactionalServerSC.java
  91     - inline access to known offset in object key to
  92       determine whether transactional
  93 
  94 Guide to the files:
  95 
  96 Basic Interfaces:
  97     Identifiable.java (Object has an Id)
  98     Writeable.java (Object can write to OutputStream)
  99     IdEncapsulation.java (Writeable, Identifiable interface)
 100     IdEncapsulationFactory.java (Factory interface for IdEncapsulation)
 101     IdEncapsulationFactoryFinder.java (Finder interface for IdEncapsulationFactoryFinder)
 102 
 103     IIOPAddress.java (class containing host and port for IIOP)
 104 
 105 Basic support for IdEncapsulations (shared for components and profiles):
 106     GenericIdEncapsulation.java (Has id, octet sequence: used for generic
 107         TaggedComponent and TaggedProfile objects)
 108     FreezableList.java (Delegated implementation of List that can be made 
 109         immutable after construction)
 110     IdentifiableContainerBase.java (extends FreezableList: container of Identifiable: 
 111         supports iteratorById.)
 112     IdEncapsulationContainerBase.java (extends IdenitifableContainerBase:
 113         container of IdEncapsulation: supports read/write IdEncapsulationSequence)
 114 
 115 Object Keys:
 116     ObjectKeyFactory.java
 117     ObjectKeyTemplate.java (interface for the following:)
 118         JIDLObjectKeyTemplate.java (object key used in *Delegate)
 119         POAObjectKeyTemplate.java (object key used in GenericPOA*SC)
 120         WireObjectKeyTemplate.java (used for non-Sun ORB IORs)
 121     ObjectId.java (a simple wrapper for byte[])
 122     ObjectKey.java (contains ObjectId and ObjectKeyTemplate)
 123 
 124 Components:
 125     TaggedComponentFactories.java (contains method for registering factories)
 126     TaggedComponentFactoryFinder.java (contains registered factories)
 127     TaggedComponent.java (interface of all tagged components)
 128         AlternateIIOPAddressComponent.java
 129         CodeSetsComponent.java
 130         JavaCodebaseComponent.java
 131         ORBTypeComponent.java
 132         PoliciesComponent.java
 133 
 134 Profiles:
 135     IIOPProfile.java (IIOPProfileTemplate and ObjectId)
 136     IIOPProfileTemplate.java (contains version, address, ObjectKeyTemplate, 
 137         list of TaggedComponent)
 138     TaggedProfile.java (interface for all TaggedProfiles)
 139     TaggedProfileFactoryFinder.java
 140     TaggedProfileTemplate.java
 141 
 142 IOR:
 143     IOR.java
 144     IORTemplate.java (List of IIOPProfileTemplate
 145     ObjectIds.java (List of ObjectId: needed for an IOR constructor)
 146 
 147 Notes from integration code review:
 148 
 149 General:
 150     - Look at making IOR API public, or
 151       move everything into com.sun.corba.se.impl.ior
 152       (don't hold up putback for this)
 153     Making public:
 154         - Writeable needs getBytes() as well as write()
 155           methods.
 156         - codec can be used with an Any to convert between
 157           IDL data type and sequence of bytes.
 158         - write() needs to use getBytes, then write id, length,
 159           octets to output stream.
 160         - getBytes() method needs to get typecode from IDL
 161           then create Any.
 162         - IdEncapsulations need to have constructor that takes
 163           byte[] (encapsulation of value).
 164     Why not?
 165         - Unencapsulated object keys can't be made portable
 166         - Lots of dependencies on ORB code in ObjectKey support
 167     Conclusion: 
 168         - move to internal (DONE)
 169     - JAVA_MAGIC should move to ObjectKeyTemplates (DONE)
 170     - check for intToBytes/bytesToInt related to object key
 171         corba/ServerDelegate (DONE)
 172         POA/GenericPOAServerSC (DONE)
 173         POA/SubcontractResponseHandler (DONE)
 174         TransactionalPOA/TransactionalClientSC.java (DONE)
 175         TransactionalPOA/TransactionalServerSC.java (DONE)
 176 
 177 ./com/sun/corba/se/impl/cosnaming/BootstrapServer.java
 178     - remove sc_init_key_* (DONE)
 179 
 180 ./com/sun/corba/se/impl/poa/POAImpl.java
 181     - remove line 130: comment on other endpoints, e.g. SSL (DONE)
 182     - add revisit comment on line 133: use multiple server port API (DONE)
 183 
 184 ./com/sun/corba/se/impl/corba/ORB.java
 185     - object_to_string: add comment that connect only takes place in
 186       non-POA cases. (DONE)
 187 
 188 ./com/sun/corba/se/impl/corba/ServerDelegate.java
 189     - chase down the object key offsets  (DONE)
 190       (search for bytesToInt and intToBytes)
 191 
 192 ./com/sun/corba/se/impl/core/SubcontractRegistry.java
 193     - getServerSubcontract: add b-e l-e comment and history on INIT, TINI (DONE)
 194     - getServerSubcontract: reference to constants (May not do this?)
 195     - getServerSubcontract: return null at end IS reachable, in the
 196       case where we have essentially a name in the key that isn't
 197       one of the ones we support.  Throw an exception? (DONE)
 198     - add minor code for INTERNAL (and string) (DONE)
 199     - remove setId calls in callers to getClientSubcontract (DONE)
 200     - throw INTERNAL exception for temp.size() != 1 case (DONE)
 201       Think about INST corbaloc problems (multi-profile IORs)
 202       both return nulls should throw exceptions (DONE)
 203 
 204 ./com/sun/corba/se/impl/core/IOR.java
 205     - Add some comments to getIORfromString about 4/2 constants (DONE)
 206     - fix name: should be getIORFromString (DONE)
 207     - IOR( InputStream ) has a problem with cachedCodeBase:
 208       is should not call getCodeBase: must refactor to 
 209       an internal implementation method. (DONE)
 210     - isEquivalent and isLocal should assert failure 
 211       if multiple profiles (through exception in getProfile) (DONE)
 212       (add comments about multi case)
 213 
 214 ./com/sun/corba/se/impl/iiop/CDRInputStream_1_0.java
 215     - read_Object: add assert in case servant is not Tie or objref (DONE)
 216 
 217 ./com/sun/corba/se/internal/TransactionalPOA/TransactionalPOAImpl.java
 218     - add comment about transactionalIortemplate: goes away after
 219       we get to OTS 1.2 transactional policy. (DONE)
 220     - change transactionalClone( ObjectKeyTemplate ) so that
 221       we get an error (INTERNAL) if NOT POAObjectKeyTemplate (DONE)
 222     - line 138: get string constant from 
 223       org.omg.CosTransactions.TransactionalObject (DONE)
 224     - remove Delegate d decl. (DONE)
 225 
 226 We need to assign minor codes for all exceptions!
 227 
 228 We need to clean up the minor code base usage! (DONE)
 229 
 230 Add equals/toString to:
 231     Do not try to develop a reflective universal equals: too slow!
 232     Do we really want equals on lists?  
 233         If we do, define collectionEqual on FreezableList
 234 
 235 CodeSetsComponent: toString
 236 FreezableList: basic toString, equals methods
 237 IIOPProfile: toString
 238 IIOPProfileTemplate: toString
 239 IOR: toString
 240 IORTemplate.java: toString, equals (inherit?)
 241 IdEncapsulationContainerBase.java: make abstract, but provide base toString/equals
 242 IdentifiableContainerBase.java: make abstract (no other changes)
 243     (ContainerBase classes need some explanation)
 244 ObjectIds.java needs toString, equals (use FreezableList?)
 245 ObjectKey: toString
 246 ObjectKeyFactory.java: singleton: don't add toString or equals
 247 PoliciesComponent.java: should finish this sometime (after we figure out
 248     exactly what to do with it)
 249 TaggedComponentBase.java: should be abstract
 250 TaggedComponentFactories.java: a singelton
 251 TaggedComponentFactoryFinder.java: a singleton
 252 TaggedProfileFactoryFinder.java: a singleton
 253 JIDLObjectKeyTemplate: toString
 254 POAObjectKeyTemplate: toString
 255 WireObjectKeyTemplate: toString uninteresting: no data, equals not useful
 256 
 257 use util/Utility.objectToString to implement toString methods.
 258 
 259 Other changes:
 260 
 261     IIOPAddress.toString should include class name (DONE)
 262 
 263     New tests needed:
 264         IIOPProfile.getIOPComponents 
 265         IIOPProfile.getIOPProfile
 266         GenericTaggedProfile.getIOPComponents
 267         GenericTaggedProfile.getIOPProfile
 268         GenericTaggedComponent.getIOPComponent
 269         ObjectKeyTemplate.getAdapterId
 270 
 271     Plus, do a read/write test for IOP stuff:
 272         construct profile
 273         convert to IOP.TaggedProfile
 274         write to stream
 275         get input stream
 276         construct profile
 277         check for equal
 278 
 279     do some tests on IOR.toString() just to see what gets printed.
 280 
 281     Add getAdapterId to *ObjectKeyTemplate.java (DONE)
 282     Add some tests for this:
 283         - WireObjectKeyTemplate throws an exception
 284         - Identically constructed ObjectKeyTemplates produce identical Adapter Ids.
 285         - Different OKTs produce different adapter IDs.
 286 
 287 New tests for versioning support:
 288 
 289 ORBVersionFactory:
 290     - for create array methods (DONE)
 291         - returns expected values for version encodings
 292         - throws INTERNAL for negative version
 293     - test one case for create stream method (DONE)
 294     - getORBVersion returns correct version (DONE)
 295 ORBVersionImpl:
 296     - check equals on some ORBVersions (DONE)
 297     - check that each ORBVersion returns correct orbtype (DONE)
 298 JIDLObjectKeyTemplate:
 299     - non-key constructor gives NEWER version (DONE)
 300 POAObjectKeyTemplate:
 301     - non-key constructor gives NEWER version (DONE)
 302 OldJIDLObjectKeyTemplate: (DONE)
 303     - non-key constructor with OLD, NEW MAGIC and check version
 304     - other values throw exception
 305 OldPOAObjectKeyTemplate: (DONE)
 306     - non-key constructor with OLD, NEW MAGIC and check version (DONE)
 307     - other values throw exception (DONE)
 308 WireObjectKeyTemplate (DONE)
 309     - version is FOREIGN
 310 ObjectKeyFactory (DONE)
 311     create the following keys and check results:
 312         JIDL OLD        OldJIDL with correct magic, version
 313         JIDL NEW        OldJIDL
 314         JIDL NEWER      JIDL
 315         POA OLD         OldPOA
 316         POA NEW         OldPOA
 317         POA NEWER       POA