1. package org.omg.PortableInterceptor;
  2. /**
  3. * org/omg/PortableInterceptor/ORBInitializerOperations.java .
  4. * Generated by the IDL-to-Java compiler (portable), version "3.2"
  5. * from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl
  6. * Wednesday, September 15, 2004 10:28:46 AM GMT
  7. */
  8. /**
  9. * Facilitates interceptor registration and ORB initialization.
  10. * <p>
  11. * Interceptors are intended to be a means by which ORB services gain
  12. * access to ORB processing, effectively becoming part of the ORB.
  13. * Since Interceptors are part of the ORB, when <code>ORB.init</code>
  14. * returns an ORB, the Interceptors shall have been registered.
  15. * Interceptors cannot be registered on an ORB after it has been
  16. * returned by a call to <code>ORB.init</code>.
  17. * <p>
  18. * An Interceptor is registered by registering an associated
  19. * <code>ORBInitializer</code> object which implements the
  20. * <code>ORBInitializer</code> interface. When an ORB is initializing,
  21. * it shall call each registered <code>ORBInitializer</code>, passing it
  22. * an <code>ORBInitInfo</code> object which is used to register its
  23. * Interceptor.
  24. * <p>
  25. * <b>Registering ORB Initializers in Java</b>
  26. * <p>
  27. * ORBInitializers are registered via Java ORB properties.
  28. * <p>
  29. * The property names are of the form:
  30. * <blockquote><code>
  31. * org.omg.PortableInterceptor.ORBInitializerClass.<Service>
  32. * </code></blockquote>
  33. * where <code><Service></code> is the string name of a class
  34. * which implements
  35. * <blockquote><code>
  36. * org.omg.PortableInterceptor.ORBInitializer
  37. * </code></blockquote>
  38. * To avoid name collisions, the reverse DNS name convention should be
  39. * used. For example, if company X has three initializers, it could define
  40. * the following properties:
  41. * <ul>
  42. * <li><code>
  43. * org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init1
  44. * </code></li>
  45. * <li><code>
  46. * org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init2
  47. * </code></li>
  48. * <li><code>
  49. * org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init3
  50. * </code></li>
  51. * </ul>
  52. * During ORB.init, these ORB properties which begin with
  53. * <code>org.omg.PortableInterceptor.ORBInitializerClass</code> shall be
  54. * collected, the <code><Service></code> portion of each property
  55. * shall be extracted, an object shall be instantiated with the
  56. * <code><Service></code> string as its class name, and the
  57. * <code>pre_init</code> and <code>post_init</code> methods shall be
  58. * called on that object. If there are any exceptions, the ORB shall
  59. * ignore them and proceed.
  60. * <p>
  61. * <b><i>Example</i></b>
  62. * <p>
  63. * A client-side logging service written by company X, for example, may
  64. * have the following ORBInitializer implementation:
  65. * <code><pre>
  66. * package com.x.logging;
  67. *
  68. * import org.omg.PortableInterceptor.Interceptor;
  69. * import org.omg.PortableInterceptor.ORBInitializer;
  70. * import org.omg.PortableInterceptor.ORBInitInfo;
  71. *
  72. * public class LoggingService implements ORBInitializer {
  73. * void pre_init( ORBInitInfo info ) {
  74. * // Instantiate the Logging Service s Interceptor.
  75. * Interceptor interceptor = new LoggingInterceptor();
  76. *
  77. * // Register the Logging Service s Interceptor.
  78. * info.add_client_request_interceptor( interceptor );
  79. * }
  80. *
  81. * void post_init( ORBInitInfo info ) {
  82. * // This service does not need two init points.
  83. * }
  84. * }
  85. * </pre></code>
  86. * To run a program called <code>MyApp</code> using this logging
  87. * service, the user could type:
  88. * <blockquote><code>
  89. * java
  90. *-Dorg.omg.PortableInterceptor.ORBInitializerClass.com.x.Logging.LoggingService
  91. * MyApp
  92. * </code></blockquote>
  93. * <p>
  94. * <b>Notes about Registering Interceptors</b>
  95. * <p>
  96. * Request Interceptors are registered on a per-ORB basis.
  97. * <p>
  98. * To achieve virtual per-object Interceptors, query the policies on the
  99. * target from within the interception points to determine whether they
  100. * should do any work.
  101. * <p>
  102. * To achieve virtual per-POA Interceptors, instantiate each POA with a
  103. * different ORB. While Interceptors may be ordered administratively,
  104. * there is no concept of order with respect to the registration of
  105. * Interceptors. Request Interceptors are concerned with service contexts.
  106. * Service contexts have no order, so there is no purpose for request
  107. * Interceptors to have an order. IOR Interceptors are concerned with
  108. * tagged components. Tagged components also have no order, so there
  109. * is no purpose for IOR Interceptors to have an order.
  110. * <p>
  111. * Registration code should avoid using the ORB (i.e., calling
  112. * <code>ORB.init</code> with the provided <code>orb_id</code>). Since
  113. * registration occurs during ORB initialization, results of invocations
  114. * on this ORB while it is in this state are undefined.
  115. *
  116. * @see ORBInitInfo
  117. */
  118. public interface ORBInitializerOperations
  119. {
  120. /**
  121. * Called during ORB initialization. If it is expected that initial
  122. * services registered by an interceptor will be used by other
  123. * interceptors, then those initial services shall be registered at
  124. * this point via calls to
  125. * <code>ORBInitInfo.register_initial_reference</code>.
  126. *
  127. * @param info provides initialization attributes and operations by
  128. * which Interceptors can be registered.
  129. */
  130. void pre_init (org.omg.PortableInterceptor.ORBInitInfo info);
  131. /**
  132. * Called during ORB initialization. If a service must resolve initial
  133. * references as part of its initialization, it can assume that all
  134. * initial references will be available at this point.
  135. * <p>
  136. * Calling the <code>post_init</code> operations is not the final
  137. * task of ORB initialization. The final task, following the
  138. * <code>post_init</code> calls, is attaching the lists of registered
  139. * interceptors to the ORB. Therefore, the ORB does not contain the
  140. * interceptors during calls to <code>post_init</code>. If an
  141. * ORB-mediated call is made from within <code>post_init</code>, no
  142. * request interceptors will be invoked on that call.
  143. * Likewise, if an operation is performed which causes an IOR to be
  144. * created, no IOR interceptors will be invoked.
  145. *
  146. * @param info provides initialization attributes and
  147. * operations by which Interceptors can be registered.
  148. */
  149. void post_init (org.omg.PortableInterceptor.ORBInitInfo info);
  150. } // interface ORBInitializerOperations