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 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 Attributes argument, which contains the attributes to be bound with obj.

StateFactory Versus DirStateFactory

A StateFactory should be used with a context that implements the Context interface. A DirStateFactory, on the other hand, should be used 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, to the state factory, the service provider will only make use of the getStateToBind() method defined in the StateFactory interface. An LDAP service provider, on the other hand, typically implements the DirContext interface, and will use the getStateToBind() method defined in the DirStateFactory interface.

Accessibility

In addition to implementing the StateFactory/DirStateFactory interface and providing an implementation for the getStateToBind() methods, the state factory class must be public and it 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 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, there is a close relationship between the representation of the object as 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 in the types of transformations that it will handle. For example, one factory might accept only CORBA objects, while another might accept only objects that implement a specific interface. In fact, in many cases, as explained in the Providers 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 make use of multiple state factories. Therefore, if a state factory finds that it does not support the type of input supplied, 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