Interface COM.ibm.jaws.mofw.BaseCollection
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface COM.ibm.jaws.mofw.BaseCollection

public interface BaseCollection
extends Object
extends KeyedCollection, Manageable, IdentityDelegator, Dependent, Lifecycle
A BaseCollection serves as the home for Managed objects just like a database serves as the home for data, providing for their creation, persistence, activation, caching, recoverability, etc. It is essentially an OODB, except that it is more open wrt what implementation is used to provide these services.

Select a BaseCollection in your object's methods only when you want to explicitly create the associated Managed objects as part of the business logic captured by that object. Otherwise, choose a QueryableCollection, KeyedCollection, NamedCollection or ReferenceCollection.

For example, a Trip may create Reservations directly in an associated BC for an "addReservation()" method. The other extreme is that it delegates creation through to an associated "TravelService" and uses only a QueryableCollection instead.

When creating or activating one of its Managed object, a BaseCollection does the following:

 1) Create a new instance of the correct class.  This is 
    typically done via managedClass.newInstance() and, if
    the BaseCollection uses delegation, manageable.newInstance()
    which calls the simple (unparameterized) default constructors. 
    This implies that this constructor be defined.  Java
    automatically provides this if no parameterized constructor
    is defined.  However, if a parameterized constructor is
    defined, then the simple constructor must be explicitly
    defined.  
 2) If the Manageable is Dependent, set its dependent context
    to be the same as the BaseCollection's dependent context:
       if ( instanceof Dependent) 
          .setDependentContext();
 3) If the BaseCollection uses delegation (eg, filepobc), then it
    must ensure that the setSelf() method is called on its 
    Manageable object:   
       if ( instanceof IdentityDelegator) 
           .setSelf(); 
 4) Internalize the new object:
    manageable.internalizeFromStream();
    This method is the time when the manageable should do 
    any initialization.  

Method Index

 o createFromCopy(String, Manageable, String)
Use this method to add a new Managed object to this BaseCollection initialized with data from the object passed in.
 o createFromData(String, InputEDStream, String)
Use this method to add a new Managed object to this BaseCollection and initialize it with data provided in an InputEDStream.
 o createFromDefault(String, Object, String)
Use this method to add a new Managed object to this BaseCollection and initialize it with data and identifier key provided by the creator and the identifierKey parameters.

Methods

 o createFromCopy
  public abstract Managed createFromCopy(String identifierKey,
                                         Manageable copy,
                                         String interfaceKey) throws InvalidKeyError, MOFWException
Use this method to add a new Managed object to this BaseCollection initialized with data from the object passed in. In effect, this method transforms a Manageable object into a Managed object by creating a new identity for it.

This method associates an Identifier key with the Managed object that is unique within the target BaseCollection. The BaseCollection determines this key by some algorthim. It could create its own key, or it could derive the key from the essential data (ED) of the object.

The key parameter is the key within the target BaseCollection. Because of the KeyedCollection.resolve() rules, this name cannot contain a "/", so the BaseCollection should return an InvalidKeyError. For example, if "abc/xyz" were used as the createFromXXX() identifierKey parameter, then a subsequent resolve() with "abc/xyz" would look for "abc" in the target BaseCollection. If found, then it would forward the resolve("xyz",...) to the found object. If not found, it would return null. Neither of these is the desired result.

Parameters:
object - is an Manageable object containing the data used to initialize the created Managed object. After this call the BaseCollection "owns" the passed in object, and the caller should forget its reference to the object passed in (use the return value instead).

The BaseCollection either may use the object as the internally cached version of the Managed object, or may just get the data out of the object and throw the object away. In either case, the object needs to support the externalizeToStream() and interalizeFromStream() methods.

identifierKey - is an optional String that the client wants to be the identifier key for the newly created Managed object. If the identifierKey is null, then the BaseCollection determines the key. For identifierKey of null, there are two cases, usually implemented by different BaseCollections:
  • The BaseCollection generates the key based on a counter, clock, etc.
  • The BaseCollection gets the key out of the initial data using a key data schema (KDS) which designates some subset of the Managed object's EDS.
copy - is the object that contains the initial data for the object being created.
interfaceKey - is an optional String that can be used as a key to lookup the class name in the dependent context.
Returns:
a Managed object that should be used in place of the object passed in.
Throws: InvalidKeyError
is raised when the identifierKey is already taken by another Managed object.
Throws: RequestedInterfaceError
is raised when the BC cannot create the object for any other reason.
 o createFromData
  public abstract Managed createFromData(String key,
                                         InputEDStream initialData,
                                         String interfaceKey) throws InvalidKeyError, EDStreamFormatError, MOFWException
Use this method to add a new Managed object to this BaseCollection and initialize it with data provided in an InputEDStream.

The identifierKey parameter is the key within the target BaseCollection. Because of the KeyedCollection.resolve() rules, this name cannot contain a "/", so the BaseCollection should return an InvalidKeyError. For example, if "abc/xyz" were used as the createFromXXX() identifierKey parameter, then a subsequent resolve() with "abc/xyz" would look for "abc" in the target BaseCollection. If found, then it would forward the resolve("xyz",...) to the found object. If not found, it would return null. Neither of these is the desired result.

Parameters:
identifierKey - is an optional String that the client wants to be the identifier key for the newly created Managed object. If the identifierKey is null, then the BaseCollection determines the key. For a null identifierKey, there are two cases, usually implemented by different BaseCollections:
  • The BaseCollection generates the key based on a persistent counter, a clock, etc.
  • The BaseCollection gets the key out of the initial data using a key data schema (KDS) which designates some subset of the Managed object's EDS.
initialData - the InputEDStream containing the initial data for the newly created Managed object.
interfaceKey - is an optional String that can be used as a key to lookup the class name in the dependent context.
Returns:
a Managed object that should be used in place of the object passed in.
Throws: InvalidKeyError
is raised when the identifierKey is already taken by another Managed object.
Throws: EDStreamFormatError
is raised when the Input Stream does not contain the essential data needed to initialize an object in this BaseCollection of the interface requested.
Throws: RequestedInterfaceError
is raised when the BC cannot create the object for any other reason.
 o createFromDefault
  public abstract Managed createFromDefault(String key,
                                            Object creator,
                                            String interfaceKey) throws InvalidKeyError, MOFWException
Use this method to add a new Managed object to this BaseCollection and initialize it with data and identifier key provided by the creator and the identifierKey parameters.

The key parameter is the key within the target BaseCollection. Because of the KeyedCollection.resolve() rules, this name cannot contain a "/", so the BaseCollection should return an InvalidKeyError. For example, if "abc/xyz" were used as the createFromXXX() identifierKey parameter, then a subsequent resolve() with "abc/xyz" would look for "abc" in the target BaseCollection. If found, then it would forward the resolve("xyz",...) to the found object. If not found, it would return null. Neither of these is the desired result.

Parameters:
identifierKey - is an optional String that the client wants to be the identifier key for the newly created Managed object. If the identifierKey is null, then the BaseCollection determines the key from the creator.
creator - the Object that created this Managed object.
interfaceKey - is an optional String that can be used as a key to lookup the class name in the dependent context.
Returns:
a Managed object that should be used in place of the object passed in.
Throws: InvalidKeyError
is raised when the identifierKey is already taken by another Managed object.
Throws: EDStreamFormatError
is raised when the Input Stream does not contain the essential data needed to initialize an object in this BaseCollection of the interface requested.
Throws: MOFWException
is raised when the BC cannot create the object for any other reason.

All Packages  Class Hierarchy  This Package  Previous  Next  Index