* The JNDI framework allows for object implementations to * be loaded in dynamically via object factories. *
* A DirStateFactory extends StateFactory * by allowing an Attributes instance * to be supplied to and be returned by the getStateToBind() method. * DirStateFactory implementations are intended to be used by * DirContext service providers. * When a caller binds an object using DirContext.bind(), * he might also specify a set of attributes to be bound with the object. * The object and attributes to be bound are passed to * the getStateToBind() method of a factory. * If the factory processes the object and attributes, it returns * a corresponding pair of object and attributes to be bound. * If the factory does not process the object, it must return null. *
* For example, a caller might bind a printer object with some printer-related * attributes. *
* ctx.rebind("inky", printer, printerAttrs);
*Since DirStateFactory extends StateFactory, it * has two getStateToBind() methods, where one * differs from the other by the attributes * argument. DirectoryManager.getStateToBind() will only use * the form that accepts the attributes argument, while * NamingManager.getStateToBind() will only use the form that * does not accept the attributes argument. * *
Either form of the getStateToBind() method of a * DirStateFactory may be invoked multiple times, possibly using different * parameters. The implementation is thread-safe. * * @author Rosanna Lee * @author Scott Seligman * * @see DirectoryManager#getStateToBind * @see DirObjectFactory * @since 1.3 */ public interface DirStateFactory extends StateFactory { /** * Retrieves the state of an object for binding given the object and attributes * to be transformed. *
* DirectoryManager.getStateToBind() * successively loads in state factories. If a factory implements * DirStateFactory, DirectoryManager invokes this method; * otherwise, it invokes StateFactory.getStateToBind(). * It does this until a factory produces a non-null answer. *
* When an exception is thrown by a factory, * the exception is passed on to the caller * of DirectoryManager.getStateToBind(). The search for other factories * that may produce a non-null answer is halted. * A factory should only throw an exception if it is sure that * it is the only intended factory and that no other factories * should be tried. * If this factory cannot create an object using the arguments supplied, * it should return null. *
* The name and nameCtx parameters may
* optionally be used to specify the name of the object being created.
* See the description of "Name and Context Parameters" in
* {@link ObjectFactory#getObjectInstance ObjectFactory.getObjectInstance()}
* for details.
* If a factory uses nameCtx it should synchronize its use
* against concurrent access, since context implementations are not
* guaranteed to be thread-safe.
*
* The name, inAttrs, and environment parameters
* are owned by the caller.
* The implementation will not modify these objects or keep references
* to them, although it may keep references to clones or copies.
* The object returned by this method is owned by the caller.
* The implementation will not subsequently modify it.
* It will contain either a new Attributes object that is
* likewise owned by the caller, or a reference to the original
* inAttrs parameter.
*
* @param obj A possibly null object whose state is to be retrieved.
* @param name The name of this object relative to nameCtx,
* or null if no name is specified.
* @param nameCtx The context relative to which the name
* parameter is specified, or null if name is
* relative to the default initial context.
* @param environment The possibly null environment to
* be used in the creation of the object's state.
* @param inAttrs The possibly null attributes to be bound with the object.
* The factory must not modify inAttrs.
* @return A Result containing the object's state for binding
* and the corresponding
* attributes to be bound; null if the object don't use this factory.
* @exception NamingException If this factory encountered an exception
* while attempting to get the object's state, and no other factories are
* to be tried.
*
* @see DirectoryManager#getStateToBind
*/
public Result getStateToBind(Object obj, Name name, Context nameCtx,
Hashtable environment,
Attributes inAttrs)
throws NamingException;
/**
* An object/attributes pair for returning the result of
* DirStateFactory.getStateToBind().
*/
public static class Result {
/**
* The possibly null object to be bound.
*/
private Object obj;
/**
* The possibly null attributes to be bound.
*/
private Attributes attrs;
/**
* Constructs an instance of Result.
*
* @param obj The possibly null object to be bound.
* @param outAttrs The possibly null attributes to be bound.
*/
public Result(Object obj, Attributes outAttrs) {
this.obj = obj;
this.attrs = outAttrs;
}
/**
* Retrieves the object to be bound.
* @return The possibly null object to be bound.
*/
public Object getObject() { return obj; };
/**
* Retrieves the attributes to be bound.
* @return The possibly null attributes to be bound.
*/
public Attributes getAttributes() { return attrs; };
}
}