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 Attributes (in the API reference documentation) argument, which contains (some or all of) the attributes associated with obj.

ObjectFactory Versus DirObjectFactory

An ObjectFactory should be used with a context that implements only the Context (in the API reference documentation) interface. A DirObjectFactory, on the other hand, should be used 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 the getObjectInstance() method defined in the ObjectFactory interface is relevant for that service provider. An LDAP service provider, on the other hand, typically implements the DirContext interface and will use the getObjectInstance() method 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 any attributes that it has read from the server about the object being looked up to getObjectInstance().

Accessibility

In addition to implementing the ObjectFactory/DirObjectFactory interface and providing an implementation for the getObjectInstance() method, the object factory class must be public and it 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 and the objects they create are also trivial. An LDAP object factory, on the other hand, 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, there is a close relationship between the representation of the objects as stored in the directory and the object factory that creates the objects using that data. 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 to create the object.

If All Else Fails

An object factory usually cannot expect that it can create an object for any arguments supplied to it. In fact, in many cases, as explained in the 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. It is common for a single service provider to make use of multiple object factories. Therefore, if an object factory finds that it cannot create an object based on the arguments supplied, 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