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;

  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>    

  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 getObjectInstance(Object obj, Name name, Context nameCtx,

  155. 				    Hashtable<?,?> environment)

  156. 	throws Exception;

  157. }