ObjectFactory


1   /*
2    * @(#)ObjectFactory.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   
8   package javax.naming.spi;
9   
10  import java.util.Hashtable  ;
11  
12  import javax.naming.*;
13  
14  /**
15    * This interface represents a factory for creating an object.
16    *<p>
17    * The JNDI framework allows for object implementations to
18    * be loaded in dynamically via <em>object factories</em>.
19    * For example, when looking up a printer bound in the name space,
20    * if the print service binds printer names to References, the printer
21    * Reference could be used to create a printer object, so that
22    * the caller of lookup can directly operate on the printer object
23    * after the lookup.  
24    * <p>An <tt>ObjectFactory</tt> is responsible
25    * for creating objects of a specific type.  In the above example,
26    * you may have a PrinterObjectFactory for creating Printer objects.
27    *<p>
28    * An object factory must implement the <tt>ObjectFactory</tt> interface.
29    * In addition, the factory class must be public and must have a 
30    * public constructor that accepts no parameters.
31    *<p>
32    * The <tt>getObjectInstance()</tt> method of an object factory may
33    * be invoked multiple times, possibly using different parameters.
34    * The implementation is thread-safe.
35    *<p>
36    * The mention of URL in the documentation for this class refers to
37    * a URL string as defined by RFC 1738 and its related RFCs. It is
38    * any string that conforms to the syntax described therein, and
39    * may not always have corresponding support in the java.net.URL
40    * class or Web browsers.
41    *
42    * @author Rosanna Lee
43    * @author Scott Seligman
44    * @version 1.10 04/07/16
45    *
46    * @see NamingManager#getObjectInstance
47    * @see NamingManager#getURLContext
48    * @see ObjectFactoryBuilder
49    * @see StateFactory
50    * @since 1.3
51    */
52  
53  public interface ObjectFactory {
54  /**
55   * Creates an object using the location or reference information
56   * specified.  
57   * <p>
58   * Special requirements of this object are supplied
59   * using <code>environment</code>.
60   * An example of such an environment property is user identity
61   * information. 
62   *<p>
63   * <tt>NamingManager.getObjectInstance()</tt>
64   * successively loads in object factories and invokes this method
65   * on them until one produces a non-null answer.  When an exception
66   * is thrown by an object factory, the exception is passed on to the caller
67   * of <tt>NamingManager.getObjectInstance()</tt>
68   * (and no search is made for other factories
69   * that may produce a non-null answer).
70   * An object factory should only throw an exception if it is sure that
71   * it is the only intended factory and that no other object factories
72   * should be tried.
73   * If this factory cannot create an object using the arguments supplied,
74   * it should return null. 
75   *<p>
76   * A <em>URL context factory</em> is a special ObjectFactory that
77   * creates contexts for resolving URLs or objects whose locations
78   * are specified by URLs.  The <tt>getObjectInstance()</tt> method
79   * of a URL context factory will obey the following rules.
80   * <ol>
81   * <li>If <code>obj</code> is null, create a context for resolving URLs of the
82   * scheme associated with this factory. The resulting context is not tied
83   * to a specific URL:  it is able to handle arbitrary URLs with this factory's
84   * scheme id.  For example, invoking <tt>getObjectInstance()</tt> with
85   * <code>obj</code> set to null on an LDAP URL context factory would return a
86   * context that can resolve LDAP URLs
87   * such as "ldap://ldap.wiz.com/o=wiz,c=us" and
88   * "ldap://ldap.umich.edu/o=umich,c=us".
89   * <li>
90   * If <code>obj</code> is a URL string, create an object (typically a context)
91   * identified by the URL.  For example, suppose this is an LDAP URL context
92   * factory.  If <code>obj</code> is "ldap://ldap.wiz.com/o=wiz,c=us",
93   * getObjectInstance() would return the context named by the distinguished
94   * name "o=wiz, c=us" at the LDAP server ldap.wiz.com.  This context can
95   * then be used to resolve LDAP names (such as "cn=George")
96   * relative to that context.
97   * <li>
98   * If <code>obj</code> is an array of URL strings, the assumption is that the
99   * URLs are equivalent in terms of the context to which they refer.
100  * Verification of whether the URLs are, or need to be, equivalent is up
101  * to the context factory. The order of the URLs in the array is
102  * not significant.
103  * The object returned by getObjectInstance() is like that of the single
104  * URL case.  It is the object named by the URLs.
105  * <li>
106  * If <code>obj</code> is of any other type, the behavior of
107  * <tt>getObjectInstance()</tt> is determined by the context factory
108  * implementation.
109  * </ol>
110  *
111  * <p>
112  * The <tt>name</tt> and <tt>environment</tt> parameters
113  * are owned by the caller.
114  * The implementation will not modify these objects or keep references
115  * to them, although it may keep references to clones or copies.
116  *
117  * <p>
118  * <b>Name and Context Parameters.</b> &nbsp;&nbsp;&nbsp;
119  * <a name=NAMECTX></a>
120  *
121  * The <code>name</code> and <code>nameCtx</code> parameters may
122  * optionally be used to specify the name of the object being created.
123  * <code>name</code> is the name of the object, relative to context
124  * <code>nameCtx</code>.
125  * If there are several possible contexts from which the object
126  * could be named -- as will often be the case -- it is up to
127  * the caller to select one.  A good rule of thumb is to select the
128  * "deepest" context available.
129  * If <code>nameCtx</code> is null, <code>name</code> is relative
130  * to the default initial context.  If no name is being specified, the
131  * <code>name</code> parameter should be null.
132  * If a factory uses <code>nameCtx</code> it should synchronize its use
133  * against concurrent access, since context implementations are not
134  * guaranteed to be thread-safe.
135  * <p>
136  *
137  * @param obj The possibly null object containing location or reference 
138  *      information that can be used in creating an object.
139  * @param name The name of this object relative to <code>nameCtx</code>,
140  *      or null if no name is specified.
141  * @param nameCtx The context relative to which the <code>name</code>
142  *      parameter is specified, or null if <code>name</code> is
143  *      relative to the default initial context.
144  * @param environment The possibly null environment that is used in
145  *      creating the object.
146  * @return The object created; null if an object cannot be created.
147  * @exception Exception if this object factory encountered an exception
148  * while attempting to create an object, and no other object factories are
149  * to be tried.
150  *
151  * @see NamingManager#getObjectInstance
152  * @see NamingManager#getURLContext
153  */
154     public Object   getObjectInstance(Object   obj, Name name, Context nameCtx,
155                     Hashtable  <?,?> environment)
156     throws Exception  ;
157 }
158
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags