1. /*
  2. * @(#)StateFactory.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 javax.naming.*;
  9. import java.util.Hashtable;
  10. /**
  11. * This interface represents a factory for obtaining the state of an
  12. * object for binding.
  13. *<p>
  14. * The JNDI framework allows for object implementations to
  15. * be loaded in dynamically via <em>object factories</em>.
  16. * For example, when looking up a printer bound in the name space,
  17. * if the print service binds printer names to <tt>Reference</tt>s, the printer
  18. * <tt>Reference</tt> could be used to create a printer object, so that
  19. * the caller of lookup can directly operate on the printer object
  20. * after the lookup.
  21. * <p>An <tt>ObjectFactory</tt> is responsible
  22. * for creating objects of a specific type. In the above example,
  23. * you may have a <tt>PrinterObjectFactory</tt> for creating
  24. * <tt>Printer</tt> objects.
  25. * <p>
  26. * For the reverse process, when an object is bound into the namespace,
  27. * JNDI provides <em>state factories</em>.
  28. * Continuing with the printer example, suppose the printer object is
  29. * updated and rebound:
  30. * <blockquote><pre>
  31. * ctx.rebind("inky", printer);
  32. * </pre></blockquote>
  33. * The service provider for <tt>ctx</tt> uses a state factory
  34. * to obtain the state of <tt>printer</tt> for binding into its namespace.
  35. * A state factory for the <tt>Printer</tt> type object might return
  36. * a more compact object for storage in the naming system.
  37. *<p>
  38. * A state factory must implement the <tt>StateFactory</tt> interface.
  39. * In addition, the factory class must be public and must have a
  40. * public constructor that accepts no parameters.
  41. *<p>
  42. * The <tt>getStateToBind()</tt> method of a state factory may
  43. * be invoked multiple times, possibly using different parameters.
  44. * The implementation is thread-safe.
  45. *<p>
  46. * <tt>StateFactory</tt> is intended for use with service providers
  47. * that implement only the <tt>Context</tt> interface.
  48. * <tt>DirStateFactory</tt> is intended for use with service providers
  49. * that implement the <tt>DirContext</tt> interface.
  50. *
  51. * @author Rosanna Lee
  52. * @author Scott Seligman
  53. * @version 1.7 03/01/23
  54. *
  55. * @see NamingManager#getStateToBind
  56. * @see DirectoryManager#getStateToBind
  57. * @see ObjectFactory
  58. * @see DirStateFactory
  59. * @since 1.3
  60. */
  61. public interface StateFactory {
  62. /**
  63. * Retrieves the state of an object for binding.
  64. *<p>
  65. * <tt>NamingManager.getStateToBind()</tt>
  66. * successively loads in state factories and invokes this method
  67. * on them until one produces a non-null answer.
  68. * <tt>DirectoryManager.getStateToBind()</tt>
  69. * successively loads in state factories. If a factory implements
  70. * <tt>DirStateFactory</tt>, then <tt>DirectoryManager</tt>
  71. * invokes <tt>DirStateFactory.getStateToBind()</tt> otherwise
  72. * it invokes <tt>StateFactory.getStateToBind()</tt>.
  73. *<p> When an exception
  74. * is thrown by a factory, the exception is passed on to the caller
  75. * of <tt>NamingManager.getStateToBind()</tt> and
  76. * <tt>DirectoryManager.getStateToBind()</tt>.
  77. * The search for other factories
  78. * that may produce a non-null answer is halted.
  79. * A factory should only throw an exception if it is sure that
  80. * it is the only intended factory and that no other factories
  81. * should be tried.
  82. * If this factory cannot create an object using the arguments supplied,
  83. * it should return null.
  84. * <p>
  85. * The <code>name</code> and <code>nameCtx</code> parameters may
  86. * optionally be used to specify the name of the object being created.
  87. * See the description of "Name and Context Parameters" in
  88. * {@link ObjectFactory#getObjectInstance ObjectFactory.getObjectInstance()}
  89. * for details.
  90. * If a factory uses <code>nameCtx</code> it should synchronize its use
  91. * against concurrent access, since context implementations are not
  92. * guaranteed to be thread-safe.
  93. * <p>
  94. * The <tt>name</tt> and <tt>environment</tt> parameters
  95. * are owned by the caller.
  96. * The implementation will not modify these objects or keep references
  97. * to them, although it may keep references to clones or copies.
  98. *
  99. * @param obj A non-null object whose state is to be retrieved.
  100. * @param name The name of this object relative to <code>nameCtx</code>,
  101. * or null if no name is specified.
  102. * @param nameCtx The context relative to which the <code>name</code>
  103. * parameter is specified, or null if <code>name</code> is
  104. * relative to the default initial context.
  105. * @param environment The possibly null environment to
  106. * be used in the creation of the object's state.
  107. * @return The object's state for binding;
  108. * null if the factory is not returning any changes.
  109. * @exception NamingException if this factory encountered an exception
  110. * while attempting to get the object's state, and no other factories are
  111. * to be tried.
  112. *
  113. * @see NamingManager#getStateToBind
  114. * @see DirectoryManager#getStateToBind
  115. */
  116. public Object getStateToBind(Object obj, Name name, Context nameCtx,
  117. Hashtable environment)
  118. throws NamingException;
  119. }