1/*
2 * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25package javax.naming.spi;
26
27import javax.naming.*;
28import java.util.Hashtable;
29
30/**
31  * This interface represents a factory for obtaining the state of an
32  * object for binding.
33  *<p>
34  * The JNDI framework allows for object implementations to
35  * be loaded in dynamically via <em>object factories</em>.
36  * For example, when looking up a printer bound in the name space,
37  * if the print service binds printer names to {@code Reference}s, the printer
38  * {@code Reference} could be used to create a printer object, so that
39  * the caller of lookup can directly operate on the printer object
40  * after the lookup.
41  * <p>An {@code ObjectFactory} is responsible
42  * for creating objects of a specific type.  In the above example,
43  * you may have a {@code PrinterObjectFactory} for creating
44  * {@code Printer} objects.
45  * <p>
46  * For the reverse process, when an object is bound into the namespace,
47  * JNDI provides <em>state factories</em>.
48  * Continuing with the printer example, suppose the printer object is
49  * updated and rebound:
50  * <blockquote><pre>
51  * ctx.rebind("inky", printer);
52  * </pre></blockquote>
53  * The service provider for {@code ctx} uses a state factory
54  * to obtain the state of {@code printer} for binding into its namespace.
55  * A state factory for the {@code Printer} type object might return
56  * a more compact object for storage in the naming system.
57  *<p>
58  * A state factory must implement the {@code StateFactory} interface.
59  * In addition, the factory class must be public and must have a
60  * public constructor that accepts no parameters.
61  * Note that in cases where the factory is in a named module then it must be
62  * in a package which is exported by that module to the {@code java.naming}
63  * module.
64  *<p>
65  * The {@code getStateToBind()} method of a state factory may
66  * be invoked multiple times, possibly using different parameters.
67  * The implementation is thread-safe.
68  *<p>
69  * {@code StateFactory} is intended for use with service providers
70  * that implement only the {@code Context} interface.
71  * {@code DirStateFactory} is intended for use with service providers
72  * that implement the {@code DirContext} interface.
73  *
74  * @author Rosanna Lee
75  * @author Scott Seligman
76  *
77  * @see NamingManager#getStateToBind
78  * @see DirectoryManager#getStateToBind
79  * @see ObjectFactory
80  * @see DirStateFactory
81  * @since 1.3
82  */
83public interface StateFactory {
84/**
85 * Retrieves the state of an object for binding.
86 *<p>
87 * {@code NamingManager.getStateToBind()}
88 * successively loads in state factories and invokes this method
89 * on them until one produces a non-null answer.
90 * {@code DirectoryManager.getStateToBind()}
91 * successively loads in state factories.  If a factory implements
92 * {@code DirStateFactory}, then {@code DirectoryManager}
93 * invokes {@code DirStateFactory.getStateToBind()}; otherwise
94 * it invokes {@code StateFactory.getStateToBind()}.
95 *<p> When an exception
96 * is thrown by a factory, the exception is passed on to the caller
97 * of {@code NamingManager.getStateToBind()} and
98 * {@code DirectoryManager.getStateToBind()}.
99 * The search for other factories
100 * that may produce a non-null answer is halted.
101 * A factory should only throw an exception if it is sure that
102 * it is the only intended factory and that no other factories
103 * should be tried.
104 * If this factory cannot create an object using the arguments supplied,
105 * it should return null.
106 * <p>
107 * The <code>name</code> and <code>nameCtx</code> parameters may
108 * optionally be used to specify the name of the object being created.
109 * See the description of "Name and Context Parameters" in
110 * {@link ObjectFactory#getObjectInstance ObjectFactory.getObjectInstance()}
111 * for details.
112 * If a factory uses <code>nameCtx</code> it should synchronize its use
113 * against concurrent access, since context implementations are not
114 * guaranteed to be thread-safe.
115 * <p>
116 * The {@code name} and {@code environment} parameters
117 * are owned by the caller.
118 * The implementation will not modify these objects or keep references
119 * to them, although it may keep references to clones or copies.
120 *
121 * @param obj A non-null object whose state is to be retrieved.
122 * @param name The name of this object relative to <code>nameCtx</code>,
123 *              or null if no name is specified.
124 * @param nameCtx The context relative to which the <code>name</code>
125 *              parameter is specified, or null if <code>name</code> is
126 *              relative to the default initial context.
127 * @param environment The possibly null environment to
128 *              be used in the creation of the object's state.
129 * @return The object's state for binding;
130 *              null if the factory is not returning any changes.
131 * @exception NamingException if this factory encountered an exception
132 * while attempting to get the object's state, and no other factories are
133 * to be tried.
134 *
135 * @see NamingManager#getStateToBind
136 * @see DirectoryManager#getStateToBind
137 */
138    public Object getStateToBind(Object obj, Name name, Context nameCtx,
139                                 Hashtable<?,?> environment)
140        throws NamingException;
141}
142