001 /* POAOperations.java --
002 Copyright (C) 2005, 2006 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package org.omg.PortableServer;
040
041 import org.omg.CORBA.BAD_INV_ORDER;
042 import org.omg.CORBA.BAD_PARAM;
043 import org.omg.CORBA.OBJ_ADAPTER;
044 import org.omg.CORBA.Policy;
045 import org.omg.CORBA.TRANSIENT;
046 import org.omg.PortableServer.POAPackage.AdapterAlreadyExists;
047 import org.omg.PortableServer.POAPackage.AdapterNonExistent;
048 import org.omg.PortableServer.POAPackage.InvalidPolicy;
049 import org.omg.PortableServer.POAPackage.NoServant;
050 import org.omg.PortableServer.POAPackage.ObjectAlreadyActive;
051 import org.omg.PortableServer.POAPackage.ObjectNotActive;
052 import org.omg.PortableServer.POAPackage.ServantAlreadyActive;
053 import org.omg.PortableServer.POAPackage.ServantNotActive;
054 import org.omg.PortableServer.POAPackage.WrongAdapter;
055 import org.omg.PortableServer.POAPackage.WrongPolicy;
056
057 /**
058 * Defines the operations, applicable to the POA.
059 *
060 * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
061 */
062 public interface POAOperations
063 {
064 /**
065 * Creates a new POA as a child of the target POA.
066 *
067 * @param child_name the name of the child POA being created.
068 * @param manager the manager that will control the new POA. If this parameter
069 * is null, a new POA manager is created and associated with the new POA.
070 *
071 * @param policies the policies, applicable for the parent POA. Policies
072 * are <i>not</i> inherited from the parent POA. If some policy type
073 * is missing in the array (or the zero size array is passed), the missing
074 * policies obtain the default values from the table, specified
075 * in the {@link POA} documentation header.
076 *
077 * @return an newly created POA. The POA will be intially in the holding
078 * state and must be activated to start processing requests.
079 *
080 * @throws AdapterAlreadyExists if the child with the given child_name
081 * already exists for the current POA.
082 * @throws InvalidPolicy if the policies conflict with each other or are
083 * otherwise inappropriate.
084 *
085 * @see POA for the list of required policies.
086 * @see #the_children()
087 */
088 POA create_POA(String child_name, POAManager manager, Policy[] policies)
089 throws AdapterAlreadyExists, InvalidPolicy;
090
091 /**
092 * Find and optionally activate the child POA with the given name.
093 *
094 * @param poa_name the name of the POA to find.
095 * @param activate_it if the child with the specified name is not found
096 * or inactive and this parameter is true, the target POA activator is
097 * invoked to activate that child. If this succeeds, that child POA
098 * is returned.
099 *
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 }