DirStateFactory


1   /*
2    * @(#)DirStateFactory.java 1.11 04/07/16
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package javax.naming.spi;
8   
9   import javax.naming.*;
10  import javax.naming.directory.Attributes  ;
11  import java.util.Hashtable  ;
12  
13  /**
14    * This interface represents a factory for obtaining the state of an
15    * object and corresponding attributes for binding.
16    *<p>
17    * The JNDI framework allows for object implementations to
18    * be loaded in dynamically via <tt>object factories</tt>.
19    * <p>
20    * A <tt>DirStateFactory</tt> extends <tt>StateFactory</tt> 
21    * by allowing an <tt>Attributes</tt> instance
22    * to be supplied to and be returned by the <tt>getStateToBind()</tt> method.
23    * <tt>DirStateFactory</tt> implementations are intended to be used by 
24    * <tt>DirContext</tt> service providers.
25    * When a caller binds an object using <tt>DirContext.bind()</tt>,
26    * he might also specify a set of attributes to be bound with the object.
27    * The object and attributes to be bound are passed to 
28    * the <tt>getStateToBind()</tt> method of a factory. 
29    * If the factory processes the object and attributes, it returns
30    * a corresponding pair of object and attributes to be bound.
31    * If the factory does not process the object, it must return null.
32    *<p>
33    * For example, a caller might bind a printer object with some printer-related
34    * attributes.
35    *<blockquote><pre>
36    * ctx.rebind("inky", printer, printerAttrs);
37    *</pre></blockquote>
38    * An LDAP service provider for <tt>ctx</tt> uses a <tt>DirStateFactory</tt>
39    * (indirectly via <tt>DirectoryManager.getStateToBind()</tt>)
40    * and gives it <tt>printer</tt> and <tt>printerAttrs</tt>. A factory for
41    * an LDAP directory might turn <tt>printer</tt> into a set of attributes
42    * and merge that with <tt>printerAttrs</tt>. The service provider then
43    * uses the resulting attributes to create an LDAP entry and updates
44    * the directory.
45    *
46    * <p> Since <tt>DirStateFactory</tt> extends <tt>StateFactory</tt>, it
47    * has two <tt>getStateToBind()</tt> methods, where one
48    * differs from the other by the attributes
49    * argument. <tt>DirectoryManager.getStateToBind()</tt> will only use
50    * the form that accepts the attributes argument, while
51    * <tt>NamingManager.getStateToBind()</tt> will only use the form that
52    * does not accept the attributes argument.
53    *
54    * <p> Either form of the <tt>getStateToBind()</tt> method of a
55    * DirStateFactory may be invoked multiple times, possibly using different
56    * parameters.  The implementation is thread-safe.
57    *
58    * @author Rosanna Lee
59    * @author Scott Seligman
60    * @version 1.11 04/07/16
61    *
62    * @see DirectoryManager#getStateToBind
63    * @see DirObjectFactory
64    * @since 1.3
65    */
66  public interface DirStateFactory extends StateFactory   {
67  /**
68   * Retrieves the state of an object for binding given the object and attributes
69   * to be transformed.
70   *<p>
71   * <tt>DirectoryManager.getStateToBind()</tt>
72   * successively loads in state factories. If a factory implements
73   * <tt>DirStateFactory</tt>, <tt>DirectoryManager</tt> invokes this method;
74   * otherwise, it invokes <tt>StateFactory.getStateToBind()</tt>.
75   * It does this until a factory produces a non-null answer.
76   *<p>
77   * When an exception is thrown by a factory, 
78   * the exception is passed on to the caller
79   * of <tt>DirectoryManager.getStateToBind()</tt>. The search for other factories
80   * that may produce a non-null answer is halted. 
81   * A factory should only throw an exception if it is sure that
82   * it is the only intended factory and that no other factories
83   * should be tried.
84   * If this factory cannot create an object using the arguments supplied,
85   * it should return null. 
86   * <p>
87   * The <code>name</code> and <code>nameCtx</code> parameters may
88   * optionally be used to specify the name of the object being created.
89   * See the description of "Name and Context Parameters" in
90   * {@link ObjectFactory#getObjectInstance ObjectFactory.getObjectInstance()}
91   * for details.
92   * If a factory uses <code>nameCtx</code> it should synchronize its use
93   * against concurrent access, since context implementations are not
94   * guaranteed to be thread-safe.
95   *<p>
96   * The <tt>name</tt>, <tt>inAttrs</tt>, and <tt>environment</tt> parameters
97   * are owned by the caller.
98   * The implementation will not modify these objects or keep references
99   * to them, although it may keep references to clones or copies.
100  * The object returned by this method is owned by the caller.
101  * The implementation will not subsequently modify it.
102  * It will contain either a new <tt>Attributes</tt> object that is
103  * likewise owned by the caller, or a reference to the original
104  * <tt>inAttrs</tt> parameter.
105  *
106  * @param obj A possibly null object whose state is to be retrieved.
107  * @param name The name of this object relative to <code>nameCtx</code>,
108  *      or null if no name is specified.
109  * @param nameCtx The context relative to which the <code>name</code>
110  *      parameter is specified, or null if <code>name</code> is
111  *      relative to the default initial context.
112  * @param environment The possibly null environment to 
113  *      be used in the creation of the object's state.
114  * @param inAttrs The possibly null attributes to be bound with the object.
115  *  The factory must not modify <tt>inAttrs</tt>.
116  * @return A <tt>Result</tt> containing the object's state for binding
117  * and the corresponding
118  * attributes to be bound; null if the object don't use this factory.
119  * @exception NamingException If this factory encountered an exception
120  * while attempting to get the object's state, and no other factories are
121  * to be tried.
122  *
123  * @see DirectoryManager#getStateToBind
124  */
125     public Result getStateToBind(Object   obj, Name name, Context nameCtx,
126                  Hashtable  <?,?> environment,
127                  Attributes   inAttrs)
128     throws NamingException;
129 
130 
131     /**
132          * An object/attributes pair for returning the result of 
133          * DirStateFactory.getStateToBind().
134          */
135     public static class Result {
136     /**
137          * The possibly null object to be bound.
138          */
139     private Object   obj;
140 
141 
142     /**
143          * The possibly null attributes to be bound.
144          */
145     private Attributes   attrs;
146 
147     /**
148           * Constructs an instance of Result.
149           *
150           * @param obj The possibly null object to be bound.
151           * @param outAttrs The possibly null attributes to be bound.
152           */
153     public Result(Object   obj, Attributes   outAttrs) {
154         this.obj = obj;
155         this.attrs = outAttrs;
156     }
157 
158     /**
159          * Retrieves the object to be bound.
160          * @return The possibly null object to be bound.
161          */
162     public Object   getObject() { return obj; };
163 
164     /**
165          * Retrieves the attributes to be bound.
166          * @return The possibly null attributes to be bound.
167          */
168     public Attributes   getAttributes() { return attrs; };
169 
170     }
171 }
172
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags