State Factories

Interaction Between State Factories and Service Providers

A service providers acts as the go-between for the application and the directory when the application stores or retrieves Java objects from the directory. When you write a service provider, you need to perform this go-between role by following the rules outlined in this section for storing objects in the directory.

The following detailed description is intended for developers writing service providers. The insight it offers into the go-between role of service providers might also interest API users.

Relevant Methods

When accepting objects to be bound into the underlying naming/directory service, the service provider should use the guidelines described in this section. An object can be bound by using one of the following methods:

• Context.bind()
• DirContext.bind()
• Context.rebind()
• DirContext.rebind()

Minimal Set of Acceptable Types

A service provider should try to support binding and rebinding objects that are or do one of the following:

• Instances of Reference
• Implement the Referenceable interface
• Implement the java.io.Serializable interface
• Implement the DirContext interface

It should check whether an object is in these four categories in the order listed because this order is most likely to capture the intent of the client. For example, a Reference is Serializable, so if you perform the Serializable check first, then no Reference objects will ever be stored in the reference format (they would all be serialized).

Framework Support

A service provider should use state factories configured with the provider and application. This allows the service provider to be customized to support arbitrary types of objects (for which a corresponding state factory is available).

The JNDI framework provides utility methods that service providers can use to access state factories. A service provider that implements only the Context interface should use NamingManager.getStateToBind() . A service provider that implements the DirContext interface should use DirectoryManager.getStateToBind() .

These methods traverse the list of state factories specified in the Context.STATE_FACTORIES environment property and the provider resource file and try to find a factory that yields a non-null answer. (See the Beyond the Basics trail for details about environment properties and the provider resource file.)

Here's an example of how a DirContext implementation might use state factories.

// First, use state factories to do a transformation
DirStateFactory.Result res = DirectoryManager.getStateToBind(
    obj, name, ctx, env, inAttrs);
obj = res.getObject();
Attributes outAttrs = res.getAttributes();

// Check for Referenceable
if (obj instanceof Referenceable) {
    obj = ((Referenceable)obj).getReference();
}

// Store different formats
if (obj instanceof Reference) {
    // Store as ref and add outAttrs
} else if (obj instanceof Serializable) {
    // Serialize and add outAttrs
} else if (obj instanceof DirContext) {
    // Grab attributes and merge with outAttrs
} else {
    ...
}

When the provider gets an object (obj) and attributes (inAttrs) from the client to bind into the directory, it invokes getStateToBind() to get a possibly updated pair of object/attributes. If no state factories return a non-null answer, then getStateToBind() returns the original pair of object and attributes. In either case, the provider stores the results in the underlying directory in a format acceptable to the directory.

State Factories