001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming.spi;
019:
020: import java.util.Hashtable;
021: import javax.naming.Name;
022: import javax.naming.Context;
023:
024: /**
025: * An <code>ObjectFactory</code> creates objects of a specified type. A
026: * variety of different objects may be used by a JNDI application; these objects
027: * are meaningful to the application and can be manipulated according to the
028: * methods available to the class of the object, such as a printer object. The
029: * class implementing this interface should be public, should also provide a
030: * public constructor taking no arguments, and should be thread-safe. Where URL
031: * is mentioned below, this refers to RFC 1738 and related RFCs.
032: */
033: public interface ObjectFactory {
034:
035: /**
036: * Creates an object of the type specified by parameter <code>o</code>,
037: * including any reference or location details, customized by the specified
038: * <code>envmt</code> parameter.
039: * <p>
040: * Object factories are specified via environment properties from several
041: * sources including provider properties files (see the specification of the
042: * <code>Context</code> interface) and may comprise a list of factories.
043: * Each object factory in the list is used by
044: * <code>NamingManager.getObjectInstance()</code> which invokes this
045: * method on each of them until a non-null result is achieved or until the
046: * list is exhausted. If an <code>ObjectFactory</code> throws an
047: * exception, it should be passed back to the code that invoked
048: * <code>NamingManager.getObjectInstance()</code> and no further object
049: * factories in the list are examined. An exception should only be thrown by
050: * an object factory if it is intended that no other object factories be
051: * examined. Usually, if an <code>ObjectFactory</code> is unable to create
052: * an object, then null should be returned.
053: * </p>
054: * <p>
055: * A special case of <code>ObjectFactory</code> is a URL context factory
056: * which is used either to create an object whose location is specified by a
057: * URL passed as the object <code>o</code> or creates contexts for
058: * resolving URLs. The <code>getObjectInstance()</code> method of a URL
059: * context factory must obey these rules:
060: * </p>
061: * <p>
062: * 1. When <code>Object o</code> is null, return a new Context object
063: * suitable for resolving any URL of the scheme supported by this factory.
064: * </p>
065: * <p>
066: * 2. When <code>Object o</code> is a URL string, return a new object
067: * (usually a context) identified by the URL, so that names relatively lower
068: * than that context may be resolved.
069: * </p>
070: * <p>
071: * 3. When <code>Object o</code> is an <code>Array</code> object with
072: * more than one URL string (order is not important), return a new object
073: * (usually a context) identified by the URL as in rule 2, above. The URLs
074: * in the array are considered to be equivalent in relation to the
075: * associated context, but the object (context) factory can choose whether
076: * or not to verify that they are truly equivalent.
077: * </p>
078: * <p>
079: * 4. Otherwise, the behaviour of this method depends on the context factory
080: * implementation.
081: * </p>
082: *
083: * @param o
084: * may be null or may contain location or reference details
085: * @param n
086: * the name relative to the context <code>c</code> of the
087: * object being created and may be null; the implementation may
088: * clone or copy this object, but will not modify the original.
089: * @param c
090: * may be null when the name is relative to the default initial
091: * context, or specifies the context to which the name is
092: * relative (if a factory uses this context object,
093: * synchronization should be used as Context objects are not
094: * thread-safe).
095: * @param envmt
096: * may be null; the implementation may clone or copy this object,
097: * but will not modify the original.
098: * @return either an object of the specified type or null if no object could
099: * be created.
100: * @throws Exception
101: * causes no further object factory will be tried
102: */
103: Object getObjectInstance(Object o, Name n, Context c,
104: Hashtable<?, ?> envmt) throws Exception;
105:
106: }
|