01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * http://www.apache.org/licenses/LICENSE-2.0
10: *
11: * Unless required by applicable law or agreed to in writing, software
12: * distributed under the License is distributed on an "AS IS" BASIS,
13: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14: * See the License for the specific language governing permissions and
15: * limitations under the License.
16: */
17:
18: package javax.naming.spi;
19:
20: import java.util.Hashtable;
21: import javax.naming.Name;
22: import javax.naming.Context;
23: import javax.naming.NamingException;
24:
25: /**
26: * The <code>StateFactory</code> interface describes a factory used to get the
27: * state of an object to be bound. Using a <code>lookup()</code> on a suitable
28: * context, an class may be found representing, say, a printer; an
29: * <code>ObjectFactory</code> may be used to create an instance of the printer
30: * object class and methods defined by the printer class may be used to inspect
31: * and manipulate the printer. There is a reverse mechanism in which a
32: * <code>StateFactory</code> is used by the service provider to obtain the
33: * state of the (in this case) printer for storing in the naming system. In
34: * addition to implementing this interface, a <code>StateFactory</code> class
35: * must be public and have a public constructor taking no parameters.
36: * <p>
37: * Note that while <code>StateFactory</code> is meant to be used in
38: * <code>Context</code> service providers, whereas
39: * <code>DirStateFactory</code> is meant to be used in <code>DirContext</code>
40: * service providers.
41: * </p>
42: */
43: public interface StateFactory {
44:
45: /**
46: * Returns a new instance of the specified object <code>o</code>
47: * containing the state of the object to be bound, customized by the
48: * specified <code>envmt</code> parameter. The name and context parameters
49: * optionally specify the name of the object being created.
50: *
51: * Object and state factories are specified via environment properties from
52: * several sources including provider properties files (see the
53: * specification of the <code>Context</code> interface) and may comprise a
54: * list of factories. When the service provider looks to obtain the list of
55: * state factories, the environment and provider properties files are search
56: * for the property name specified by constant
57: * <code>Context.STATE_FACTORIES</code>. Each state factory in the
58: * resulting list is used by <code>NamingManager.getStateToBind()</code>
59: * which invokes this method on each of them until a non-null result is
60: * achieved or until the list is exhausted. If a <code>StateFactory</code>
61: * throws an exception, it should be passed back to the code that invoked
62: * <code>NamingManager.getStateToBind()</code> and no further state
63: * factories in the list are examined. An exception should only be thrown by
64: * a state factory if it is intended that no other state factories be
65: * examined. Usually, if an state factory is unable to return the state of
66: * an object, then null should be returned.
67: *
68: * @param o
69: * may be null, or specifies the returning instance
70: * @param n
71: * may be null, or specifies the name relative to the specified
72: * context <code>c</code>. The implementation may clone or
73: * copy this object, but will not modify the original.
74: * @param c
75: * the context to which the name parameter is relative, or may be
76: * null when using a name relative the the default initial
77: * context. If a factory uses this context object,
78: * synchronization should be used as context objects are not
79: * thread-safe.
80: * @param envmt
81: * may be null; the implementation may clone or copy this object,
82: * but will not modify the original.
83: * @return either a new instance of the specified object <code>o</code>
84: * containing the state of the object to be bound, customized by the
85: * specified <code>envmt</code> parameter. Or null if no object
86: * could be created.
87: * @throws NamingException
88: * if it is intended that no other state factories be examined.
89: */
90: Object getStateToBind(Object o, Name n, Context c,
91: Hashtable<?, ?> envmt) throws NamingException;
92:
93: }
|