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

Interface COM.ibm.jaws.mofw.NamedCollection

public interface NamedCollection
extends Object
extends KeyedCollection
The NamedCollection is a KeyedCollection that manages "bindings" of object's to names. This allows a client to create a "alias" name relative to a NamedCollection, similar to a Unix file system symbolic link.

Every NamedCollection serves as a more granular name space than if there were only one "root" per address space. Since a binding must be unique within a NamedCollection, it can be used in an application when "set" like behavior is desired.

When mapping OOD models to the Managed Object Framework, choose a NamedCollection whenever a qualified relationship is needed between two objects.

After an object has been bound to a NamedContext using a key, the same object can be accessed via the KeyedCollection resolve() method. This object can be either a Java Object object or a Managed object (Managed extends Object). A Java Object's reference cannot span outside of its address space (its reference is not distributed and cannot persistent beyond the life of its address space). A Managed object's reference can do both. However long a reference lives, the NamedContext bind lives and will return the same object that was bound. In the following example, the boolean "same" is true, because the e1.setSalary(50,000) changes the value of the same object referenced from outside aNamedCollection (via e1) and with aNameCollection. Employee e1 = new Employee(); Employee e2; aNamedCollection.bind("Jim", e1); e1.setSalary(50,000); e2 = aNamedCollection.resolve("Jim"); boolean same e2.equals(e1);

Because a NamedCollection can be a Managed object, it can be bound in another NamedCollection. Because a Managed object can be bound to multiple NamedCollections, a directed graph is formed that includes all KeyedCollections, including both NamedCollections and BaseCollections. In contrast, because a Managed object can have only one BaseCollection, the subset of this directed graph that includes only BaseCollections forms a pure tree.


Method Index

 o bind(String, Object)
Use this method to bind the name to the target object only if the specified name is not already bound into the NamedCollection.
 o rebind(String, Object)
Use this method to create or update a binding of the name to the "target".
 o unbind(String)
Use this method to remove a binding, if one exists with the name passed in.

Methods

 o bind
  public abstract boolean bind(String name,
                               Object target) throws InvalidKeyError
Use this method to bind the name to the target object only if the specified name is not already bound into the NamedCollection. If you want to bind the name to the target object regardless of if it is already bound to the same or another target, then use rebind().

The name parameter is the name within the target NamedCollection. Because of the KeyedCollection.resolve() rules, this name cannot contain a "/", so the NamedCollection should return an InvalidKeyError.

For example, if "abc/xyz" were used as the bind() name parameter, then a subsequent resolve() with "abc/xyz" would look for "abc" in the target NamedCollection. 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:
name - a string to bind to the target.
target - the object to which the name is bound.
Returns:
a boolean indicating whether the bind occurred. False indicates that the name was already bound, while more catastrophic problems should raise a runtime exception or error (and be documented by the implementor).
Throws: InvalidKeyError
indicates that the name parameter was invalid.
 o unbind
  public abstract void unbind(String name) throws InvalidKeyError
Use this method to remove a binding, if one exists with the name passed in.
Parameters:
name - a string representing the name to unbind.
Throws: InvalidKeyError
indicates that the name parameter was invalid.
 o rebind
  public abstract void rebind(String name,
                              Object object) throws InvalidKeyError
Use this method to create or update a binding of the name to the "target". If you only want to create a binding if it does not already exist, use bind().
Parameters:
name - a string representing the name to which the target is bound or rebound.
target - a object to which the name is bound or rebound.
Throws: InvalidKeyError
indicates that the name parameter was invalid.

All Packages  Class Hierarchy  This Package  Previous  Next  Index