Previous | Next | Trail Map | Java Objects and the Directory | Object Factories

Writing an Object Factory

An object factory implements either the ObjectFactory (in the API reference documentation) or DirObjectFactory (in the API reference documentation) interface. ObjectFactory has one method: getObjectInstance() (in the API reference documentation).
public Object getObjectInstance(
	Object info, 
	Name name, 
	Context nameCtx,
	Hashtable environment) 
	throws Exception;
DirObjectFactory is a subinterface of ObjectFactory and declares an additional method: getObjectInstance() (in the API reference documentation).
public Object getObjectInstance(
	Object info, 
	Name name, 
	Context nameCtx,
	Hashtable environment,
	Attributes attrs) 
	throws Exception;
This method accepts as arguments information about the object (info) and the name of the object (name) relative to the context (nameCtx) in which it is bound. The env argument is the environment properties of the context that is using the object factory. See the Beyond the Basics (in the Beyond the Basics trail) trail for details about environment properties. The DirObjectFactory version of the method accepts an additional attrs ( Attributes (in the API reference documentation)) argument, which contains (some or all of) the attributes associated with obj.

ObjectFactory versus DirObjectFactory

You should use an ObjectFactory with a context that implements only the Context (in the API reference documentation) interface. Use a DirObjectFactory with a context that implements the DirContext (in the API reference documentation) interface.

For example, a COS naming service provider implements only the Context interface. Because Attributes is not relevant in that scenario, only getObjectInstance() as defined in the ObjectFactory interface is relevant for that service provider. By contrast, an LDAP service provider typically implements the DirContext interface and will use getObjectInstance() as defined in the DirObjectFactory interface. The Attributes parameter is used by the service provider to pass along any attributes associated with info to the factory so that the factory does not have to fetch the attributes itself. For example, when a service provider does a Context.lookup()(in the API reference documentation), it can pass to getObjectInstance() any attributes that it read from the server about the object's being looked up.

Accessibility

The object factory class must not only implement the ObjectFactory/DirObjectFactory interface and provide an implementation for getObjectInstance(). It also must be public and must have a public constructor that accepts no arguments.

Job Description

Typically, an object factory is quite simple and small. Its main role is to collect the information necessary to create an instance of the intended object's class and then to invoke that class's constructor. However, the complexity of the objects that it creates can vary significantly. For example, the object factory examples given in this lesson are pretty trivial; the objects that they create are also trivial. By contrast, an LDAP object factory creates an LDAP context, which creates and manages connections to an LDAP server. In this case, a relatively simple object factory is creating a very complex object.

In general, the information that an object factory uses to create objects comes from the directory. Consequently, a close relationship exists between the representation of the objects as stored in the directory and the object factory that creates the objects by using that information. For example, if the object is represented as a set of attributes in the directory, then the corresponding object factory must know to extract information from those attributes so as to create the object.

If All Else Fails

An object factory is usually very specific regarding the types of transformations that it will handle. In fact, in many cases, as explained in the Interaction Between Object Factories and Service Providers section, the JNDI will ask an object factory to try to create an instance of an object that was intended for another object factory. A single service provider commonly uses multiple object factories. Therefore if an object factory finds that it cannot create an object based on the arguments supplied, then it should return null. Only if the object factory knows for sure that it is supposed to create the object, but it can't, should it throw an exception. Throwing an exception precludes other object factories from being tried.


Previous | Next | Trail Map | Java Objects and the Directory | Object Factories