KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > spi > 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 JavaDoc;
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 JavaDoc getObjectInstance(Object JavaDoc obj, Name name, Context nameCtx,
155                     Hashtable JavaDoc<?,?> environment)
156     throws Exception JavaDoc;
157 }
158
Popular Tags