| Frames | No Frames |
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: }