1. /*
  2. * @(#)ObjectFactory.java 1.7 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.naming.spi;
  8. import java.util.Hashtable;
  9. import javax.naming.*;
  10. /**
  11. * This interface represents a factory for creating an object.
  12. *<p>
  13. * The JNDI framework allows for object implementations to
  14. * be loaded in dynamically via <em>object factories</em>.
  15. * For example, when looking up a printer bound in the name space,
  16. * if the print service binds printer names to References, the printer
  17. * Reference could be used to create a printer object, so that
  18. * the caller of lookup can directly operate on the printer object
  19. * after the lookup.
  20. * <p>An <tt>ObjectFactory</tt> is responsible
  21. * for creating objects of a specific type. In the above example,
  22. * you may have a PrinterObjectFactory for creating Printer objects.
  23. *<p>
  24. * An object factory must implement the <tt>ObjectFactory</tt> interface.
  25. * In addition, the factory class must be public and must have a
  26. * public constructor that accepts no parameters.
  27. *<p>
  28. * The <tt>getObjectInstance()</tt> method of an object factory may
  29. * be invoked multiple times, possibly using different parameters.
  30. * The implementation is thread-safe.
  31. *<p>
  32. * The mention of URL in the documentation for this class refers to
  33. * a URL string as defined by RFC 1738 and its related RFCs. It is
  34. * any string that conforms to the syntax described therein, and
  35. * may not always have corresponding support in the java.net.URL
  36. * class or Web browsers.
  37. *
  38. * @author Rosanna Lee
  39. * @author Scott Seligman
  40. * @version 1.7 03/01/23
  41. *
  42. * @see NamingManager#getObjectInstance
  43. * @see NamingManager#getURLContext
  44. * @see ObjectFactoryBuilder
  45. * @see StateFactory
  46. * @since 1.3
  47. */
  48. public interface ObjectFactory {
  49. /**
  50. * Creates an object using the location or reference information
  51. * specified.
  52. * <p>
  53. * Special requirements of this object are supplied
  54. * using <code>environment</code>.
  55. * An example of such an environment property is user identity
  56. * information.
  57. *<p>
  58. * <tt>NamingManager.getObjectInstance()</tt>
  59. * successively loads in object factories and invokes this method
  60. * on them until one produces a non-null answer. When an exception
  61. * is thrown by an object factory, the exception is passed on to the caller
  62. * of <tt>NamingManager.getObjectInstance()</tt>
  63. * (and no search is made for other factories
  64. * that may produce a non-null answer).
  65. * An object factory should only throw an exception if it is sure that
  66. * it is the only intended factory and that no other object factories
  67. * should be tried.
  68. * If this factory cannot create an object using the arguments supplied,
  69. * it should return null.
  70. *<p>
  71. * A <em>URL context factory</em> is a special ObjectFactory that
  72. * creates contexts for resolving URLs or objects whose locations
  73. * are specified by URLs. The <tt>getObjectInstance()</tt> method
  74. * of a URL context factory will obey the following rules.
  75. * <ol>
  76. * <li>If <code>obj</code> is null, create a context for resolving URLs of the
  77. * scheme associated with this factory. The resulting context is not tied
  78. * to a specific URL: it is able to handle arbitrary URLs with this factory's
  79. * scheme id. For example, invoking <tt>getObjectInstance()</tt> with
  80. * <code>obj</code> set to null on an LDAP URL context factory would return a
  81. * context that can resolve LDAP URLs
  82. * such as "ldap://ldap.wiz.com/o=wiz,c=us" and
  83. * "ldap://ldap.umich.edu/o=umich,c=us".
  84. * <li>
  85. * If <code>obj</code> is a URL string, create an object (typically a context)
  86. * identified by the URL. For example, suppose this is an LDAP URL context
  87. * factory. If <code>obj</code> is "ldap://ldap.wiz.com/o=wiz,c=us",
  88. * getObjectInstance() would return the context named by the distinguished
  89. * name "o=wiz, c=us" at the LDAP server ldap.wiz.com. This context can
  90. * then be used to resolve LDAP names (such as "cn=George")
  91. * relative to that context.
  92. * <li>
  93. * If <code>obj</code> is an array of URL strings, the assumption is that the
  94. * URLs are equivalent in terms of the context to which they refer.
  95. * Verification of whether the URLs are, or need to be, equivalent is up
  96. * to the context factory. The order of the URLs in the array is
  97. * not significant.
  98. * The object returned by getObjectInstance() is like that of the single
  99. * URL case. It is the object named by the URLs.
  100. * <li>
  101. * If <code>obj</code> is of any other type, the behavior of
  102. * <tt>getObjectInstance()</tt> is determined by the context factory
  103. * implementation.
  104. * </ol>
  105. *
  106. * <p>
  107. * The <tt>name</tt> and <tt>environment</tt> parameters
  108. * are owned by the caller.
  109. * The implementation will not modify these objects or keep references
  110. * to them, although it may keep references to clones or copies.
  111. *
  112. * <p>
  113. * <b>Name and Context Parameters.</b>    
  114. * <a name=NAMECTX></a>
  115. *
  116. * The <code>name</code> and <code>nameCtx</code> parameters may
  117. * optionally be used to specify the name of the object being created.
  118. * <code>name</code> is the name of the object, relative to context
  119. * <code>nameCtx</code>.
  120. * If there are several possible contexts from which the object
  121. * could be named -- as will often be the case -- it is up to
  122. * the caller to select one. A good rule of thumb is to select the
  123. * "deepest" context available.
  124. * If <code>nameCtx</code> is null, <code>name</code> is relative
  125. * to the default initial context. If no name is being specified, the
  126. * <code>name</code> parameter should be null.
  127. * If a factory uses <code>nameCtx</code> it should synchronize its use
  128. * against concurrent access, since context implementations are not
  129. * guaranteed to be thread-safe.
  130. * <p>
  131. *
  132. * @param obj The possibly null object containing location or reference
  133. * information that can be used in creating an object.
  134. * @param name The name of this object relative to <code>nameCtx</code>,
  135. * or null if no name is specified.
  136. * @param nameCtx The context relative to which the <code>name</code>
  137. * parameter is specified, or null if <code>name</code> is
  138. * relative to the default initial context.
  139. * @param environment The possibly null environment that is used in
  140. * creating the object.
  141. * @return The object created; null if an object cannot be created.
  142. * @exception Exception if this object factory encountered an exception
  143. * while attempting to create an object, and no other object factories are
  144. * to be tried.
  145. *
  146. * @see NamingManager#getObjectInstance
  147. * @see NamingManager#getURLContext
  148. */
  149. public Object getObjectInstance(Object obj, Name name, Context nameCtx,
  150. Hashtable environment) throws Exception;
  151. }