State Factories

Writing a State Factory

A state factory implements either the StateFactory or DirStateFactory interface. StateFactory has one method: getStateToBind() .

public Object getStateToBind(
	Object obj, 
	Name name, 
	Context nameCtx,
	Hashtable environment) 
	throws NamingException;

DirStateFactory is a subinterface of StateFactory and declares an additional method: getStateToBind() .

public DirStateFactory.Result getStateToBind(
	Object obj, 
	Name name, 
	Context nameCtx,
	Hashtable environment,
	Attributes inAttrs) 
	throws NamingException;

This method accepts as an argument the object to be bound (obj). The name and nameCtx arguments are provided to the state factory in case the factory requires additional information from the directory. The env argument is the environment properties of the context that is using the state factory. See the Beyond the Basics trail for details about environment properties. The DirStateFactory version of the method accepts an additional inAttrs ( Attributes ) argument, which contains the attributes to be bound with obj.

StateFactory versus DirStateFactory

You should use a StateFactory with a context that implements the Context interface. Use a DirStateFactory with a context that implements the DirContext interface. For example, a COS naming service provider implements only the Context interface. Because no Attributes parameter can be passed to the service provider, and consequently, not to the state factory, the service provider will use only getStateToBind() as defined in the StateFactory interface. By contrast, an LDAP service provider typically implements the DirContext interface and will use getStateToBind() as defined in the DirStateFactory interface.

Accessibility

The state factory class must not only implement the StateFactory/DirStateFactory interface and provide an implementation for the getStateToBind() methods. It also must be public and must have a public constructor that accepts no arguments.

Job Description

Typically, a state factory is quite simple and small. Its main role is to perform some transformation on the input and produce an object (and/or attributes) suitable for storing by the service provider. For example, a state factory for an LDAP service provider might accept an object and some attributes and return a set of attributes that is the union of the input attributes and the attributes that represent the object. A state factory for a COS naming service provider might, for example, accept a java.rmi.Remote object and return its CORBA tie object.

In general, a close relationship exists between the representation of the object as it is stored in the underlying naming service or directory and the state factory that does the transformation. For example, if an object is represented as a set of attributes in the directory, then the corresponding state factory must return attributes for representing the object.

If All Else Fails

A state factory is usually very specific regarding the types of transformations that it will handle. For example, one factory might accept only CORBA objects, whereas another might accept only objects that implement a specific interface. In fact, in many cases, as explained in the next section, the JNDI will ask a state factory to attempt the transformation by using input that was intended for another state factory. It is common for a single service provider to use multiple state factories. Therefore, if a state factory finds that it does not support the type of input supplied, then it should return null. The factory should throw an exception only when it encounters an error while processing the input that it should otherwise accept. Throwing an exception precludes other state factories from being tried.

State Factories