State Factories

Role of Service Providers

The service providers act 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 these rules for storing and reading objects from 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 interest some 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 one of the following:

• Are 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 three 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 performed the Serializable check first, no Reference objects would ever be stored in the reference format (that is, 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 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 provider resource file.)

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

// First use state factories to do 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 and attributes. If no state factories return a non-null answer, getStateToBind() returns the original pair of object and attributes. In either case, the provider proceeds to store the results into the underlying directory in a formats acceptable to the directory.

State Factories