StateFactory


1   /*
2    * @(#)StateFactory.java    1.10 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 java.util.Hashtable  ;
11  
12  /**
13    * This interface represents a factory for obtaining the state of an
14    * object for binding.
15    *<p>
16    * The JNDI framework allows for object implementations to
17    * be loaded in dynamically via <em>object factories</em>.
18    * For example, when looking up a printer bound in the name space,
19    * if the print service binds printer names to <tt>Reference</tt>s, the printer
20    * <tt>Reference</tt> could be used to create a printer object, so that
21    * the caller of lookup can directly operate on the printer object
22    * after the lookup.  
23    * <p>An <tt>ObjectFactory</tt> is responsible
24    * for creating objects of a specific type.  In the above example,
25    * you may have a <tt>PrinterObjectFactory</tt> for creating 
26    * <tt>Printer</tt> objects.
27    * <p>
28    * For the reverse process, when an object is bound into the namespace,
29    * JNDI provides <em>state factories</em>.
30    * Continuing with the printer example, suppose the printer object is
31    * updated and rebound:
32    * <blockquote><pre>
33    * ctx.rebind("inky", printer);
34    * </pre></blockquote>
35    * The service provider for <tt>ctx</tt> uses a state factory
36    * to obtain the state of <tt>printer</tt> for binding into its namespace.
37    * A state factory for the <tt>Printer</tt> type object might return
38    * a more compact object for storage in the naming system.
39    *<p>
40    * A state factory must implement the <tt>StateFactory</tt> interface.
41    * In addition, the factory class must be public and must have a 
42    * public constructor that accepts no parameters.
43    *<p>
44    * The <tt>getStateToBind()</tt> method of a state factory may
45    * be invoked multiple times, possibly using different parameters.
46    * The implementation is thread-safe.
47    *<p>
48    * <tt>StateFactory</tt> is intended for use with service providers
49    * that implement only the <tt>Context</tt> interface.
50    * <tt>DirStateFactory</tt> is intended for use with service providers
51    * that implement the <tt>DirContext</tt> interface.
52    *
53    * @author Rosanna Lee
54    * @author Scott Seligman
55    * @version 1.10 04/07/16
56    *
57    * @see NamingManager#getStateToBind
58    * @see DirectoryManager#getStateToBind
59    * @see ObjectFactory
60    * @see DirStateFactory
61    * @since 1.3
62    */
63  public interface StateFactory {
64  /**
65   * Retrieves the state of an object for binding.
66   *<p>
67   * <tt>NamingManager.getStateToBind()</tt>
68   * successively loads in state factories and invokes this method
69   * on them until one produces a non-null answer.  
70   * <tt>DirectoryManager.getStateToBind()</tt>
71   * successively loads in state factories.  If a factory implements
72   * <tt>DirStateFactory</tt>, then <tt>DirectoryManager</tt>
73   * invokes <tt>DirStateFactory.getStateToBind()</tt>; otherwise
74   * it invokes <tt>StateFactory.getStateToBind()</tt>.
75   *<p> When an exception
76   * is thrown by a factory, the exception is passed on to the caller
77   * of <tt>NamingManager.getStateToBind()</tt> and
78   * <tt>DirectoryManager.getStateToBind()</tt>. 
79   * 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> 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  *
101  * @param obj A non-null object whose state is to be retrieved.
102  * @param name The name of this object relative to <code>nameCtx</code>,
103  *      or null if no name is specified.
104  * @param nameCtx The context relative to which the <code>name</code>
105  *      parameter is specified, or null if <code>name</code> is
106  *      relative to the default initial context.
107  * @param environment The possibly null environment to 
108  *      be used in the creation of the object's state.
109  * @return The object's state for binding;
110  *      null if the factory is not returning any changes.
111  * @exception NamingException if this factory encountered an exception
112  * while attempting to get the object's state, and no other factories are
113  * to be tried.
114  *
115  * @see NamingManager#getStateToBind
116  * @see DirectoryManager#getStateToBind
117  */
118     public Object   getStateToBind(Object   obj, Name name, Context nameCtx,
119                  Hashtable  <?,?> environment)
120     throws NamingException;
121 }
122
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags