old-autovect-branch/libjava/classpath/org/omg/PortableServer/package.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <!-- package.html - describes classes in org.omg.PortableServer package
   3    Copyright (C) 2005 Free Software Foundation, Inc.
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20 02110-1301 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. -->
  38
  39 <html>
  40 <head><title>GNU Classpath - The Portable Object Adapter package</title></head>
  41 <body>
  42 <p>
  43 The Portable Object Adapter (POA) provides more control on the request
  44 processing than it is possible when connecting objects directly to the
  45 ORB. The POA model defines a tree structure of POAs, the root POA being
  46 connected directly to the ORB. Any branch of this tree can be temporary or
  47 permanently inactivated using {@link org.omg.PortableServer.POAManager}.
  48 The same manager can control several branches in the POA tree. Also,
  49 any branch in this tree can have different processing options (policies).
  50 </p><p>
  51 The newly created POA is in holding state, just queuing requests. To start
  52 processing requests, it must be turned into the active state by its
  53 {@link org.omg.PortableServer.POAManagerOperations#activate}.
  54 </p><p>
  55 The previously monolite object implementation is now divided into object
  56 (that implements {@link org.omg.CORBA.Object})
  57 and servant (that implements either {@link org.omg.CORBA.portable.InvokeHandler}
  58 or {@link org.omg.PortableServer.DynamicImplementation}).
  59 Frequently each object has its own servant, but it can also be a single servant
  60 per multiple objects and also default servant for POA
  61 (see {@link org.omg.PortableServer.POAOperations#set_servant}). Each object
  62 has its own Object Id, unique in the scope of the POA, where the object is
  63 connected. These Ids need not be different for objects belonging
  64 to different POAs, even if these POAs are connected to the same ORB.
  65 Under the USER_ID is assignment policy this Id can be a specified by user in
  66 {@link org.omg.PortableServer.POAOperations#activate_object_with_id},
  67 encapsulating some meaningful information about the object. The Id of the
  68 object being currently served can be identified with
  69 {@link org.omg.PortableServer.Servant#_object_id}. This approach is used in cases
  70 when it is possible to encapsulate all object-related data into the
  71 Object Id. Such system only needs one servant, one server socket and one
  72 socket port per POA that can handle thounsands of objects.
  73 </p><p>
  74 Instead of being connected directly to the ORB, objects are now connected
  75 to one of the ORBs POAs. Since JDK 1.4 the application specific implementation
  76 base is derived from the {@link org.omg.PortableServer.Servant}, having a
  77 different name pattern (<code>*POA.java</code> instead of the previous
  78 <code>_*ImplBase.java</code>). This <code>*POA</code> suffix does <i>not</i>
  79 mean that these servants implement or are derived from POA. They are different
  80 classes that can be connected to one of the POAs, by instance, using
  81 {@link org.omg.PortableServer.POAOperations#servant_to_reference}.
  82 The implementation base also inherits an *Operations interface, containing
  83 definitions of the application specific methods. The application programmer
  84 writes a descendent of the implementation base, implementing these methods
  85 for the application - specific functionality.
  86 </p><p>
  87 The POA objects support the method invocation by name, using
  88 {@link org.omg.CORBA.Request}. This alternative method works without the
  89 service-specific classes that may not be available at run time.
  90 </p><p>
  91 The objects in POA can also be activated and inactivated independently. It
  92 is possible to set a listener ({@link org.omg.PortableServer.ServantActivator})
  93 that would register the object activations ("incarnations") and deactivations
  94 ("etherializations"). The servant need not be specifyed when creating an
  95 object. Under the IMPLICIT_ACTIVATION
  96 {@link org.omg.PortableServer.ImplicitActivationPolicy}
  97 the {@link org.omg.PortableServer.ServantActivator} can provide the servant
  98 in response to the first (local or remote) call of any method on the
  99 previously incative object.
 100 </p><p>
 101 The root POA is obtained by resolving the initial reference "RootPOA"
 102 for the orb. In the simpliest case the objects can be connected directly
 103 to that root POA without creating the POA tree. The policies, used by
 104 the root POA, are defined by OMG as following:
 105 <table border="1">
 106 <tr><th>Policy type</th><th>Accepted policy</th></tr>
 107 <tr><td>{@link org.omg.PortableServer.IdAssignmentPolicy} </td><td>SYSTEM_ID
 108 (Ids are created by POA)</td></tr>
 109 <tr><td>{@link org.omg.PortableServer.IdUniquenessPolicy}</td><td>UNIQUE_ID
 110  (single object (and Id) per servant)
 111 </td></tr>
 112 <tr><td>{@link org.omg.PortableServer.ImplicitActivationPolicy} </td><td>
 113 IMPLICIT_ACTIVATION (if inactive, activate)</td></tr>
 114 <tr><td>{@link org.omg.PortableServer.LifespanPolicy} </td><td>TRANSIENT
 115 (the POA objects cannot outlive POA)</td></tr>
 116 <tr><td>{@link org.omg.PortableServer.RequestProcessingPolicy} </td><td>
 117 USE_ACTIVE_OBJECT_MAP_ONLY (the servant is provided during activation)</td></tr>
 118 <tr><td>{@link org.omg.PortableServer.ServantRetentionPolicy} </td><td>
 119 RETAIN (retain servants for subsequent invocations)</td></tr>
 120 <tr><td>{@link org.omg.PortableServer.ThreadPolicy} </td><td>ORB_CTRL_MODEL
 121 (single thread per request and single server socket per object)</td></tr>
 122 </table>
 123 These values are also default for the child POAs The policies are
 124 <i>never</i> inherited from the parent POA.
 125 </p><p>
 126 This set of policies means that each object will have a separate serving
 127 thread, separate network socket port and usually a separate servant. It
 128 is appropriate when the expected number of objects is not too large.
 129 If the expected number of objects is larger than the supportable number
 130 of threads and socket ports, the SINGLE_THREAD_MODEL
 131 {@link org.omg.PortableServer.ThreadPolicy} is
 132 used. Then all objects in POA with this policy are served in a single
 133 thread, using the same server socket, connected to a single port. If the
 134 request processing policy is additionally set to USE_DEFAULT_SERVANT,
 135 all objects of this POA share the same (default) servant.
 136 </p><p>
 137 The operations, supported by POA are defined
 138 separately in {@link org.omg.PortableServer.POAOperations}.
 139 </p><p>
 140 <h3>The typical POA usage scenarios</h3>
 141 <h4>POA converts servant to the object reference</h4>
 142 In the simpliest case, the servant implementation is connected to POA by
 143 {@link org.omg.PortableServer.POAOperations#servant_to_reference}, the
 144 returned object being a target of remote and local invocations.
 145 It may be converted into the stringified reference, registered with
 146 the naming service, used locally or, when serving or invoking local or remote
 147 method, passed as a parameter or return value having the CORBA Object type.
 148 The object obtains Id from POA and is activated due default implicit
 149 activation policy. This scenario is supported by the default policy set
 150 and is used in the most of the "hello world" examples.
 151 <h4>Servant provides to the object reference</h4>
 152 The servant can be connected to an ORB by
 153 {@link org.omg.PortableServer.Servant#_this_object(org.omg.CORBA.ORB)},
 154 obtaining the object reference. The overridable
 155 {@link org.omg.PortableServer.Servant#_default_POA()}
 156 specifies POA to that the servant will be connected. The default method
 157 connects to the root poa. IDL compilers frequently generate the
 158 <code>_this(ORB)</code> metod for servants for getting the object reference
 159 that is already narrowed to the exact object type.
 160 <h4>Explicit activation with POA assigned ids</h4>
 161 The objects are activated by calling the
 162 {@link org.omg.PortableServer.POAOperations#activate_object} on the
 163 POA with the object in question. The POA allocates, assigns, and
 164 returns a unique identity value for the object. This scenario requires the
 165 SYSTEM_ID {@link org.omg.PortableServer.IdAssignmentPolicy}.
 166 <h4>Explicit Activation with User-assigned Ids</h4>
 167 The POA supports an explicit activation operation,
 168 {@link org.omg.PortableServer.POAOperations#activate_object_with_id},
 169 that associates a servant with the user-defined Object Id.
 170 This scenario requires the USER_ID
 171 {@link org.omg.PortableServer.IdAssignmentPolicy}. The servant manager
 172 may be or may not be used.
 173 <h4>References before activation</h4>
 174 It may be useful to create references for objects before activating them.
 175 Such reference can be created using
 176 {@link org.omg.PortableServer.POAOperations#create_reference} or
 177 {@link org.omg.PortableServer.POAOperations#create_reference_with_id}, both
 178 methods also requiring to give the object repository id. Such object may
 179 be later activated either by
 180 {@link org.omg.PortableServer.POAOperations#activate_object_with_id} or
 181 automatically, if the IMPLICIT_ACTIVATION policy applies.
 182 <h4>Multiple Ids per servant</h4>
 183 If the MULTIPLE_ID policy applies, the servant may be activated many times.
 184 Under this policy,
 185 {@link org.omg.PortableServer.POAOperations#servant_to_reference}
 186 and {@link org.omg.PortableServer.POAOperations#servant_to_id}
 187 during each call create a new object and object reference for the
 188 used servant.
 189 <h4>One servant for all objects</h4>
 190 If the USE_DEFAULT_SERVANT policy applies, that default servant serves all
 191 objects, belonging this POA. This approach is used when there is
 192 very little data associated with each object, so little that the data can be
 193 encoded in the Object Id. Also, it may be needed when a very large
 194 number of objects is expected. If the RETAIN applies, it is possible to
 195 activate an object explicitly setting the servant other than default.
 196 If NO_RETAIN applies, the default servant will serve all known an
 197 unknown objects for that POA.
 198 <h4>Single Servant, Many Objects and Types</h4>
 199 Combining USER_ID, USE_DEFAULT_SERVANT and RETAIN, it is possible to
 200 create and serve objects "on the fly". The servant must determine the
 201 object type (for instance, from the value of the agreed attribute,
 202 shared by all supported types, or from the Object Id) and be able to
 203 handle the method, named in request. If the names and parameter lists
 204 of the object methods are also created "on the fly", the requests
 205 to such object can still be submitted using {@link org.omg.CORBA.Request}.
 206 This method is used when the created object represents some
 207 entity in the complex database.
 208 <h4>The ServantLocator finds a servant for each call</h4>
 209 The {@link org.omg.PortableServer.ServantLocator} is used by POAs that
 210 combinine NON_RETAIN and USE_SERVANT_MANAGER policies. It provides
 211 a new or reused servant every time the invocation is made. The servant
 212 locator must provide a servant in response of calling
 213 {@link org.omg.PortableServer.ServantLocatorOperations#preinvoke}.
 214 This method has access the the Id of the object being served and
 215 the name of the method being called. It must return the appropriate
 216 instance of the servant or throw an exception, forwarding the request
 217 to another object (usually in another server). After the invocation,
 218 a {@link org.omg.PortableServer.ServantLocatorOperations#postinvoke}
 219 is called. It should be not assumed that the call of <code>preinvoke</code>
 220 will be followed by the call of the <code>postinvoke</code>; in
 221 multithreaded environment these calls are not serialized in this way. If
 222 the <code>preinvoke</code> has to tell something this-call-specific to
 223 the <code>postinvoke</code>, it must use the provided cookie holder.
 224 The <code>preinvoke/postinoke</code> are also called to provide a servant
 225 during each local invocation on the objects, belonging to the described POA.
 226 </p><p>
 227 All these scenarios must work with the current GNU Classpath release.
 228
 229 @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
 230 </body>
 231 </html>