1. /*

  2.  * @(#)ObjectFactory.java	1.5 00/02/02

  3.  *

  4.  * Copyright 1999, 2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package javax.naming.spi;

  12. 

  13. import java.util.Hashtable;

  14. 

  15. import javax.naming.*;

  16. 

  17. /**

  18.   * This interface represents a factory for creating an object.

  19.   *<p>

  20.   * The JNDI framework allows for object implementations to

  21.   * be loaded in dynamically via <em>object factories</em>.

  22.   * For example, when looking up a printer bound in the name space,

  23.   * if the print service binds printer names to References, the printer

  24.   * Reference could be used to create a printer object, so that

  25.   * the caller of lookup can directly operate on the printer object

  26.   * after the lookup.  

  27.   * <p>An <tt>ObjectFactory</tt> is responsible

  28.   * for creating objects of a specific type.  In the above example,

  29.   * you may have a PrinterObjectFactory for creating Printer objects.

  30.   *<p>

  31.   * An object factory must implement the <tt>ObjectFactory</tt> interface.

  32.   * In addition, the factory class must be public and must have a 

  33.   * public constructor that accepts no parameters.

  34.   *<p>

  35.   * The <tt>getObjectInstance()</tt> method of an object factory may

  36.   * be invoked multiple times, possibly using different parameters.

  37.   * The implementation is thread-safe.

  38.   *<p>

  39.   * The mention of URL in the documentation for this class refers to

  40.   * a URL string as defined by RFC 1738 and its related RFCs. It is

  41.   * any string that conforms to the syntax described therein, and

  42.   * may not always have corresponding support in the java.net.URL

  43.   * class or Web browsers.

  44.   *

  45.   * @author Rosanna Lee

  46.   * @author Scott Seligman

  47.   * @version 1.5 00/02/02

  48.   *

  49.   * @see NamingManager#getObjectInstance

  50.   * @see NamingManager#getURLContext

  51.   * @see ObjectFactoryBuilder

  52.   * @see StateFactory

  53.   * @since 1.3

  54.   */

  55. 

  56. public interface ObjectFactory {

  57. /**

  58.  * Creates an object using the location or reference information

  59.  * specified.  

  60.  * <p>

  61.  * Special requirements of this object are supplied

  62.  * using <code>environment</code>.

  63.  * An example of such an environment property is user identity

  64.  * information. 

  65.  *<p>

  66.  * <tt>NamingManager.getObjectInstance()</tt>

  67.  * successively loads in object factories and invokes this method

  68.  * on them until one produces a non-null answer.  When an exception

  69.  * is thrown by an object factory, the exception is passed on to the caller

  70.  * of <tt>NamingManager.getObjectInstance()</tt>

  71.  * (and no search is made for other factories

  72.  * that may produce a non-null answer).

  73.  * An object factory should only throw an exception if it is sure that

  74.  * it is the only intended factory and that no other object factories

  75.  * should be tried.

  76.  * If this factory cannot create an object using the arguments supplied,

  77.  * it should return null. 

  78.  *<p>

  79.  * A <em>URL context factory</em> is a special ObjectFactory that

  80.  * creates contexts for resolving URLs or objects whose locations

  81.  * are specified by URLs.  The <tt>getObjectInstance()</tt> method

  82.  * of a URL context factory will obey the following rules.

  83.  * <ol>

  84.  * <li>If <code>obj</code> is null, create a context for resolving URLs of the

  85.  * scheme associated with this factory. The resulting context is not tied

  86.  * to a specific URL:  it is able to handle arbitrary URLs with this factory's

  87.  * scheme id.  For example, invoking <tt>getObjectInstance()</tt> with

  88.  * <code>obj</code> set to null on an LDAP URL context factory would return a

  89.  * context that can resolve LDAP URLs

  90.  * such as "ldap://ldap.wiz.com/o=wiz,c=us" and

  91.  * "ldap://ldap.umich.edu/o=umich,c=us".

  92.  * <li>

  93.  * If <code>obj</code> is a URL string, create an object (typically a context)

  94.  * identified by the URL.  For example, suppose this is an LDAP URL context

  95.  * factory.  If <code>obj</code> is "ldap://ldap.wiz.com/o=wiz,c=us",

  96.  * getObjectInstance() would return the context named by the distinguished

  97.  * name "o=wiz, c=us" at the LDAP server ldap.wiz.com.  This context can

  98.  * then be used to resolve LDAP names (such as "cn=George")

  99.  * relative to that context.

  100.  * <li>

  101.  * If <code>obj</code> is an array of URL strings, the assumption is that the

  102.  * URLs are equivalent in terms of the context to which they refer.

  103.  * Verification of whether the URLs are, or need to be, equivalent is up

  104.  * to the context factory. The order of the URLs in the array is

  105.  * not significant.

  106.  * The object returned by getObjectInstance() is like that of the single

  107.  * URL case.  It is the object named by the URLs.

  108.  * <li>

  109.  * If <code>obj</code> is of any other type, the behavior of

  110.  * <tt>getObjectInstance()</tt> is determined by the context factory

  111.  * implementation.

  112.  * </ol>

  113.  *

  114.  * <p>

  115.  * The <tt>name</tt> and <tt>environment</tt> parameters

  116.  * are owned by the caller.

  117.  * The implementation will not modify these objects or keep references

  118.  * to them, although it may keep references to clones or copies.

  119.  *

  120.  * <p>

  121.  * <b>Name and Context Parameters.</b>    

  122.  * <a name=NAMECTX></a>

  123.  *

  124.  * The <code>name</code> and <code>nameCtx</code> parameters may

  125.  * optionally be used to specify the name of the object being created.

  126.  * <code>name</code> is the name of the object, relative to context

  127.  * <code>nameCtx</code>.

  128.  * If there are several possible contexts from which the object

  129.  * could be named -- as will often be the case -- it is up to

  130.  * the caller to select one.  A good rule of thumb is to select the

  131.  * "deepest" context available.

  132.  * If <code>nameCtx</code> is null, <code>name</code> is relative

  133.  * to the default initial context.  If no name is being specified, the

  134.  * <code>name</code> parameter should be null.

  135.  * If a factory uses <code>nameCtx</code> it should synchronize its use

  136.  * against concurrent access, since context implementations are not

  137.  * guaranteed to be thread-safe.

  138.  * <p>

  139.  *

  140.  * @param obj The possibly null object containing location or reference 

  141.  * 		information that can be used in creating an object.

  142.  * @param name The name of this object relative to <code>nameCtx</code>,

  143.  *		or null if no name is specified.

  144.  * @param nameCtx The context relative to which the <code>name</code>

  145.  *		parameter is specified, or null if <code>name</code> is

  146.  *		relative to the default initial context.

  147.  * @param environment The possibly null environment that is used in

  148.  * 		creating the object.

  149.  * @return The object created; null if an object cannot be created.

  150.  * @exception Exception if this object factory encountered an exception

  151.  * while attempting to create an object, and no other object factories are

  152.  * to be tried.

  153.  *

  154.  * @see NamingManager#getObjectInstance

  155.  * @see NamingManager#getURLContext

  156.  */

  157.     public Object getObjectInstance(Object obj, Name name, Context nameCtx,

  158. 				    Hashtable environment) throws Exception;

  159. }