KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > omg > PortableInterceptor > ORBInitializerOperations


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