Source for org.omg.PortableServer.POAOperations

   1: /* POAOperations.java --
   2:    Copyright (C) 2005, 2006 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package org.omg.PortableServer;
  40: 
  41: import org.omg.CORBA.BAD_INV_ORDER;
  42: import org.omg.CORBA.BAD_PARAM;
  43: import org.omg.CORBA.OBJ_ADAPTER;
  44: import org.omg.CORBA.Policy;
  45: import org.omg.CORBA.TRANSIENT;
  46: import org.omg.PortableServer.POAPackage.AdapterAlreadyExists;
  47: import org.omg.PortableServer.POAPackage.AdapterNonExistent;
  48: import org.omg.PortableServer.POAPackage.InvalidPolicy;
  49: import org.omg.PortableServer.POAPackage.NoServant;
  50: import org.omg.PortableServer.POAPackage.ObjectAlreadyActive;
  51: import org.omg.PortableServer.POAPackage.ObjectNotActive;
  52: import org.omg.PortableServer.POAPackage.ServantAlreadyActive;
  53: import org.omg.PortableServer.POAPackage.ServantNotActive;
  54: import org.omg.PortableServer.POAPackage.WrongAdapter;
  55: import org.omg.PortableServer.POAPackage.WrongPolicy;
  56: 
  57: /**
  58:  * Defines the operations, applicable to the POA.
  59:  *
  60:  * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
  61:  */
  62: public interface POAOperations
  63: {
  64:   /**
  65:    * Creates a new POA as a child of the target POA.
  66:    *
  67:    * @param child_name the name of the child POA being created.
  68:    * @param manager the manager that will control the new POA. If this parameter
  69:    * is null, a new POA manager is created and associated with the new POA.
  70:    *
  71:    * @param policies the policies, applicable for the parent POA. Policies
  72:    * are <i>not</i> inherited from the parent POA. If some policy type
  73:    * is missing in the array (or the zero size array is passed), the missing
  74:    * policies obtain the default values from the table, specified
  75:    * in the {@link POA} documentation header.
  76:    *
  77:    * @return an newly created POA. The POA will be intially in the holding
  78:    * state and must be activated to start processing requests.
  79:    *
  80:    * @throws AdapterAlreadyExists if the child with the given child_name
  81:    * already exists for the current POA.
  82:    * @throws InvalidPolicy if the policies conflict with each other or are
  83:    * otherwise inappropriate.
  84:    *
  85:    * @see POA for the list of required policies.
  86:    * @see #the_children()
  87:    */
  88:   POA create_POA(String child_name, POAManager manager, Policy[] policies)
  89:           throws AdapterAlreadyExists, InvalidPolicy;
  90: 
  91:   /**
  92:   * Find and optionally activate the child POA with the given name.
  93:   *
  94:   * @param poa_name the name of the POA to find.
  95:   * @param activate_it if the child with the specified name is not found
  96:   * or inactive and this parameter is true, the target POA activator is
  97:   * invoked to activate that child. If this succeeds, that child POA
  98:   * is returned.
  99:   *
 100:   * @throws AdapterNonExistent if no active child with the given name
 101:   * is found and one of the following is true:
 102:   * a) the target POA has no associated
 103:   * {@link AdapterActivator}. b) that activator fails to activate the
 104:   * child POA. c) <code>activate_id</code> = false.
 105:   */
 106:   POA find_POA(String poa_name, boolean activate_it)
 107:         throws AdapterNonExistent;
 108: 
 109:   /**
 110:    * Generate the Object Id for the given servant and add the servant to
 111:    * the Active Object Map using this Id a a key. If the servant
 112:    * activator is set, its incarnate method will be called. In this case,
 113:    * the passed servant in this method can be null; in this case, the servant,
 114:    * returned by {@link ServantActivatorOperations#incarnate} will
 115:    * be used.
 116:    *
 117:    * @param a_servant a servant that would serve the object with the
 118:    * returned Object Id.
 119:    *
 120:    * @return the generated objert Id for the given servant.
 121:    *
 122:    * @throws ServantAlreadyActive if this servant is already in the
 123:    * Active Object Map and the UNIQUE_ID policy applies.
 124:    *
 125:    * @throws WrongPolicy if the required policies SYSTEM_ID and RETAIN
 126:    * do not apply to this POA.
 127:    */
 128:   byte[] activate_object(Servant a_servant)
 129:                   throws ServantAlreadyActive, WrongPolicy;
 130: 
 131:   /**
 132:    * Add the given servant to the Active Object Map as a servant for the
 133:    * object with the provided Object Id. If the servant activator is
 134:    * set, its incarnate method will be called. In this case,
 135:    * the passed servant in this method can be null; in this case, the servant,
 136:    * returned by {@link ServantActivatorOperations#incarnate} will
 137:    * be used.
 138:    *
 139:    * @param an_Object_Id an object id for the given object.
 140:    * @param a_servant a servant that will serve the object with the given
 141:    * Object Id.
 142:    *
 143:    * @throws ObjectAlreadyActive if the given object id is already in the
 144:    * Active Object Map.
 145:    * @throws WrongPolicy if the required RETAIN policy does not apply to
 146:    * this POA.
 147:    * @throws BAD_PARAM if the passed object id is invalid due any reason.
 148:    */
 149:   void activate_object_with_id(byte[] an_Object_Id, Servant a_servant)
 150:                         throws ServantAlreadyActive, ObjectAlreadyActive,
 151:                                WrongPolicy;
 152: 
 153:   /**
 154:    * <p>Deactivate object with the given id. Client, trying to call
 155:    * method on the deactivated object will either receive the remote
 156:    * exception ({@link org.omg.CORBA.OBJECT_NOT_EXIST}, minor 0x535503ec),
 157:    * incomplete) or the object will be reactivated and serve the request.
 158:    * The object can be reactivated only if the implicit activation
 159:    * policy applies and the servant activator is set.</p><p>
 160:    * The deactivated object will continue to process requests that arrived
 161:    * before decativation.
 162:    * If this POA has the associated servant manager, a
 163:    * {@link ServantActivatorOperations#etherealize} is <i>immediately</i>
 164:    * invoked on the passed id. The deactivated object can be reactivated
 165:    * by {@link #activate_object_with_id}.</p>
 166:    * <p>The deactivation will not release thread, port or memory resources,
 167:    * taken by that object. This is due requirement to make the
 168:    * object reactivation possible at any time. To release the resources,
 169:    * you must destroy the POA.
 170:    * </p>
 171:    *
 172:    * @throws WrongPolicy if the required RETAIN policy does not apply to
 173:    * this POA.
 174:    */
 175:   void deactivate_object(byte[] the_Object_Id)
 176:                   throws ObjectNotActive, WrongPolicy;
 177: 
 178:   /**
 179:   * Create the object reference, encapsulating the given repository Id and
 180:   * the Object Id, generated by this POA. The returned object will not be
 181:   * activated by default and may be activated on the first invocation by
 182:   * the servant manager (if it is set and if policies are applicable).
 183:   * The returned object can also be narrowed by helper and used locally.
 184:   * In this case, the servant will be activated on the first local call of
 185:   * any method. The methods on returned object can also be invoked by
 186:   * name, using {@link org.omg.CORBA.Request}.
 187:   *
 188:   * @param a_repository_id the repository id for the given object. When
 189:   * narrowing the returned object with some helper, it will be checked for
 190:   * equality with value, returned by the the helper id().
 191:   *
 192:   * @throws WrongPolicy if the required SYSTEM_ID policy does not apply to
 193:   * this POA.
 194:   */
 195:   org.omg.CORBA.Object create_reference(String a_repository_id)
 196:                                  throws WrongPolicy;
 197: 
 198:   /**
 199:   * <p> Create the object reference, encapsulating the given repository Id and
 200:   * the given Object Id. The returned object will not be
 201:   * activated by default and may be activated on the first invocation by
 202:   * the servant manager (if it is set and if policies are applicable).
 203:   * </p><p>
 204:   * The returned object can also be narrowed by helper and used locally.
 205:   * In this case, the servant will be activated on the first local call of
 206:   * any method. The methods on returned object can also be invoked by
 207:   * name, using {@link org.omg.CORBA.Request}.
 208:   * </p>
 209:   *
 210:   * @param an_object_id the object id for the object being created.
 211:   * If the POA uses the SYSTEM_ID policy, the portable application
 212:   * must only supply ids, generated by that POA.
 213:   *
 214:   * @param a_repository_id the repository id for the given object. When
 215:   * narrowing the returned object with some helper, it will be checked for
 216:   * equality with value, returned by the the helper id().
 217:   */
 218:   org.omg.CORBA.Object create_reference_with_id(byte[] an_object_id,
 219:                                                 String a_repository_id
 220:                                                );
 221: 
 222:   /**
 223:    * Returns a default servant for this POA.
 224:    *
 225:    * @return a servant that will be used for requests for
 226:    * which no servant is found in the Active Object Map.
 227:    *
 228:    * @throws NoServant if there is no default servant associated with this POA.
 229:    * @throws WrongPolicy if the USE_DEFAULT_SERVANT policy is not active.
 230:    */
 231:   Servant get_servant()
 232:                throws NoServant, WrongPolicy;
 233: 
 234:   /**
 235:    * Sets the default servant for this POA.
 236:    *
 237:    * @param a_servant a servant that will be used for requests for
 238:    * which no servant is found in the Active Object Map.
 239:    *
 240:    * @throws WrongPolicy if the USE_DEFAULT_SERVANT policy is not active.
 241:    */
 242:   void set_servant(Servant a_servant)
 243:             throws WrongPolicy;
 244: 
 245:   /**
 246:    * Set a servant manager for this POA.
 247:    *
 248:    * @param a_manager servant manager being set. If the RETAIN policy applies, the
 249:    * manager must implement a {@link ServantActivator}. If the NON_RETAIN
 250:    * policy applies, the manager must implement a {@link ServantLocator}.
 251:    *
 252:    * @throws WrongPolicy if the required USE_SERVANT_MANAGER policy does not
 253:    * apply to this POA.
 254:    *
 255:    * @throws OBJ_ADAPTER minor code 4 if the passed manager does not
 256:    * implement the required interface ({@link ServantActivator},
 257:    * {@link ServantLocator}).
 258:    *
 259:    * @throws BAD_INV_ORDER minor code 6 if the method is called more than once
 260:    * on the same POA. The manager can be set only once.
 261:    */
 262:   void set_servant_manager(ServantManager a_manager)
 263:                     throws WrongPolicy;
 264: 
 265:   /**
 266:    * Get the servant manager, associated with this POA.
 267:    *
 268:    * @return the associated servant manager or null if it has
 269:    * been previously set.
 270:    *
 271:    * @throws WrongPolicy if the required USE_SERVANT_MANAGER policy does not
 272:    * apply to this POA.
 273:    */
 274:   ServantManager get_servant_manager()
 275:                               throws WrongPolicy;
 276: 
 277:   /**
 278:    * Get the unique Id of the POA in the process in which it is created.
 279:    * This Id is needed by portable interceptors. The id is unique
 280:    * for the life span of the POA in the process. For persistent
 281:    * POAs, if a POA is created in the same path with the same name as
 282:    * another POA, these POAs are identical have the same id. All transient
 283:    * POAs are assumed unique.
 284:    */
 285:   byte[] id();
 286: 
 287:   /**
 288:    * Returns the reference to the active object with the given Id.
 289:    *
 290:    * @param the_Object_Id the object id.
 291:    *
 292:    * @throws ObjectNotActive if there is no active object with such Id.
 293:    * @throws WrongPolicy if the required RETAIN policy does not apply to
 294:    * this POA.
 295:    */
 296:   org.omg.CORBA.Object id_to_reference(byte[] the_Object_Id)
 297:                                 throws ObjectNotActive, WrongPolicy;
 298: 
 299:   /**
 300:    * Returns the servant that serves the active object with the given Id.
 301:    *
 302:    * @param the_Object_Id the object id.
 303:    *
 304:    * @throws ObjectNotActive if there is no active object with such Id.
 305:    * @throws WrongPolicy This method requires either RETAIN or
 306:    * USE_DEFAULT_SERVANT policies and reaises the WrongPolicy if none of them
 307:    * apply to this POA.
 308:    */
 309:   Servant id_to_servant(byte[] the_Object_Id)
 310:                  throws ObjectNotActive, WrongPolicy;
 311: 
 312:   /**
 313:    * Returns the Object Id, encapsulated in the given object reference.
 314:    *
 315:    * @param the_Object the object that has been previously created with this
 316:    * POA. It need not be active.
 317:    *
 318:    * @throws WrongAdapter if the passed object has not been previously created
 319:    * with this POA.
 320:    * @throws WrongPolicy never (declared for the future extensions only).
 321:    */
 322:   byte[] reference_to_id(org.omg.CORBA.Object the_Object)
 323:                   throws WrongAdapter, WrongPolicy;
 324: 
 325:   /**
 326:    * Returns the servant that is serving this object.
 327:    *
 328:    * @return if the RETAIN policy applies and the object is in the Active
 329:    * Object Map, the method returns the servant, associated with this object.
 330:    * Otherwise, if the USE_DEFAULT_SERVANT policy applies, the method returns
 331:    * the default servant (if one was set).
 332:    *
 333:    * @throws ObjectNotActive if none of the conditions above are satisfied.
 334:    * @throws WrongAdapter if the object reference was not created with this POA.
 335:    * @throws WrongPolicy This method requires either RETAIN or
 336:    * USE_DEFAULT_SERVANT policies and reaises the WrongPolicy if none of them
 337:    * apply to this POA.
 338:    */
 339:   Servant reference_to_servant(org.omg.CORBA.Object the_Object)
 340:                         throws ObjectNotActive, WrongPolicy, WrongAdapter;
 341: 
 342:   /**
 343:   * Returns the id of the object, served by the given servant. The id is found
 344:   * in one of the following ways.
 345:   * <ul>
 346:   * <li>If the POA has both the RETAIN and the UNIQUE_ID policy and
 347:   * the specified servant is active, the method return the Object Id associated
 348:   * with that servant.
 349:   * </li><li>
 350:   * If the POA has both the RETAIN and the IMPLICIT_ACTIVATION policy and
 351:   * either the POA has the MULTIPLE_ID policy or the specified servant is
 352:   * inactive, the method activates the servant using a POA-generated Object Id
 353:   * and the Interface Id associated with the servant, and returns that
 354:   * Object Id.
 355:   * </li>
 356:   * <li>If the POA has the USE_DEFAULT_SERVANT policy, the servant specified
 357:   * is the default servant, and the method is being invoked in the context o
 358:   * f executing a request on the default servant, the method returns the
 359:   * ObjectId associated with the current invocation.
 360:   * </li>
 361:   * </ul>
 362:   * @throws ServantNotActive in all cases, not listed in the list above.
 363:   * @throws WrongPolicy The method requres USE_DEFAULT_SERVANT policy or
 364:   * a combination of the RETAIN policy and either the UNIQUE_ID or
 365:   * IMPLICIT_ACTIVATION policies and throws the WrongPolicy if these conditions
 366:   * are not satisfied.
 367:   */
 368:   byte[] servant_to_id(Servant the_Servant)
 369:                 throws ServantNotActive, WrongPolicy;
 370: 
 371:   /**
 372:    * <p>Converts the given servant to the object reference.
 373:    * The servant will serve all methods, invoked on the returned object.
 374:    * The returned object reference can be passed to the remote client,
 375:    * enabling remote invocations.
 376:    * </p><p>
 377:    * If the specified servant already serves some active object, that
 378:    * object is returned. Otherwise,
 379:    * if the POA has the IMPLICIT_ACTIVATION policy the method activates
 380:    * the servant, creating an new object with the POA-generated Object Id.
 381:    * In this case, if the servant activator is set, the
 382:    * {@link ServantActivatorOperations#incarnate} method will be called.
 383:    * </p>
 384:    *
 385:    * @throws ServantNotActive if the servant is inactive and no
 386:    * IMPLICIT_ACTIVATION policy applies.
 387:    * @throws WrongPolicy This method needs the RETAIN policy and either the
 388:    * UNIQUE_ID or IMPLICIT_ACTIVATION policies.
 389:    *
 390:    * @return the object, exposing the given servant in the context of this POA.
 391:    */
 392:   org.omg.CORBA.Object servant_to_reference(Servant the_Servant)
 393:                                      throws ServantNotActive, WrongPolicy;
 394: 
 395:   /**
 396:    * Return the POA manager, associated with this POA.
 397:    *
 398:    * @return the associated POA manager (always available).
 399:    */
 400:   POAManager the_POAManager();
 401: 
 402:   /**
 403:    * Returns the adapter activator, associated with this POA.
 404:    * The newly created POA has no activator (null would be
 405:    * returned). The ORB root POA also initially has no activator.
 406:    *
 407:    * @return tha adapter activator or null if this POA has no
 408:    * associated adapter activator.
 409:    */
 410:   AdapterActivator the_activator();
 411: 
 412:   /**
 413:   * Set the adapter activator for this POA.
 414:   *
 415:   * @param activator the activator being set.
 416:   */
 417:   void the_activator(AdapterActivator activator);
 418: 
 419:   /**
 420:   * The children of this POA.
 421:   *
 422:   * @return the array of all childs for this POA.
 423:   */
 424:   POA[] the_children();
 425: 
 426:   /**
 427:    * Return the name of this POA.
 428:    *
 429:    * @return the name of POA, relative to its parent.
 430:    */
 431:   String the_name();
 432: 
 433:   /**
 434:    * Return the parent of this POA.
 435:    *
 436:    * @return the parent POA or <code>null</code> if this is a root POA.
 437:    */
 438:   POA the_parent();
 439: 
 440:   /**
 441:    * <p> Destroy this POA and all descendant POAs. The destroyed POAs can be
 442:    * later re-created via {@link AdapterActivator} or by invoking
 443:    * {@link #create_POA}.
 444:    * This differs from {@link POAManagerOperations#deactivate} that does
 445:    * not allow recreation of the deactivated POAs. After deactivation,
 446:    * recreation is only possible if the POAs were later destroyed.
 447:    * </p><p>
 448:    * The remote invocation on the target, belonging to the POA that is
 449:    * currently destroyed return the remote exception ({@link TRANSIENT},
 450:    * minor code 4).
 451:    * </p>
 452:    * @param etherealize_objects if true, and POA has RETAIN policy, and the
 453:    * servant manager is available, the servant manager method
 454:    * {@link ServantActivatorOperations#etherealize} is called for each
 455:    *  <i>active</i> object in the Active Object Map. This method should not
 456:    * try to access POA being destroyed. If <code>destroy</code> is called
 457:    * multiple times before the destruction completes,
 458:    * the etherialization should be invoked only once.
 459:    *
 460:    * @param wait_for_completion if true, the method waits till the POA being
 461:    * destroyed completes all current requests and etherialization. If false,
 462:    * the method returns immediately.
 463:    */
 464:   void destroy(boolean etherealize_objects, boolean wait_for_completion);
 465: 
 466:   /**
 467:    * Create the IdUniquenessPolicy policy.
 468:    *
 469:    * @param a_value states which one Id uniqueness policy will apply.
 470:    *
 471:    * @return the created policy.
 472:    */
 473:   IdUniquenessPolicy create_id_uniqueness_policy(IdUniquenessPolicyValue a_value);
 474: 
 475:   /**
 476:    * Create the ImplicitActivationPolicy policy.
 477:    *
 478:    * @param a_value states which one activation policy will apply.
 479:    *
 480:    * @return the created policy.
 481:    */
 482:   ImplicitActivationPolicy create_implicit_activation_policy(ImplicitActivationPolicyValue a_value);
 483: 
 484:   /**
 485:    * Create the LifespanPolicy policy.
 486:    *
 487:    * @param a_value states which one object lifespan policy will apply.
 488:    *
 489:    * @return the created policy.
 490:    */
 491:   LifespanPolicy create_lifespan_policy(LifespanPolicyValue a_value);
 492: 
 493:   /**
 494:    * Create the RequestProcessingPolicy policy.
 495:    *
 496:    * @param a_value states which one request processing policy will apply.
 497:    *
 498:    * @return the created policy.
 499:    */
 500:   RequestProcessingPolicy create_request_processing_policy(RequestProcessingPolicyValue a_value);
 501: 
 502:   /**
 503:    * Create the ServantRetentionPolicy policy.
 504:    *
 505:    * @param a_value states which one servant retention policy will apply.
 506:    *
 507:    * @return the created policy.
 508:    */
 509:   ServantRetentionPolicy create_servant_retention_policy(ServantRetentionPolicyValue a_value);
 510: 
 511:   /**
 512:    * Create the ThreadPolicy policy.
 513:    *
 514:    * @param a_value states which one thread policy will apply.
 515:    *
 516:    * @return the created policy.
 517:    */
 518:   ThreadPolicy create_thread_policy(ThreadPolicyValue a_value);
 519: 
 520:   /**
 521:   * Create the ID assignment policy with the given value.
 522:   *
 523:   * @param value states which one ID assignment policy will apply.
 524:   *
 525:   * @return the created policy.
 526:   */
 527:   IdAssignmentPolicy create_id_assignment_policy(IdAssignmentPolicyValue value);
 528: 
 529: }