summaryrefslogtreecommitdiff
path: root/libjava/classpath/org/omg/PortableServer/POAOperations.java
blob: f989d26819e9bb520554e4a924af6f9f166d0d5e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
/* POAOperations.java --
   Copyright (C) 2005, 2006 Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */


package org.omg.PortableServer;

import org.omg.CORBA.BAD_INV_ORDER;
import org.omg.CORBA.BAD_PARAM;
import org.omg.CORBA.OBJ_ADAPTER;
import org.omg.CORBA.Policy;
import org.omg.CORBA.TRANSIENT;
import org.omg.PortableServer.POAPackage.AdapterAlreadyExists;
import org.omg.PortableServer.POAPackage.AdapterNonExistent;
import org.omg.PortableServer.POAPackage.InvalidPolicy;
import org.omg.PortableServer.POAPackage.NoServant;
import org.omg.PortableServer.POAPackage.ObjectAlreadyActive;
import org.omg.PortableServer.POAPackage.ObjectNotActive;
import org.omg.PortableServer.POAPackage.ServantAlreadyActive;
import org.omg.PortableServer.POAPackage.ServantNotActive;
import org.omg.PortableServer.POAPackage.WrongAdapter;
import org.omg.PortableServer.POAPackage.WrongPolicy;

/**
 * Defines the operations, applicable to the POA.
 *
 * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
 */
public interface POAOperations
{
  /**
   * Creates a new POA as a child of the target POA.
   *
   * @param child_name the name of the child POA being created.
   * @param manager the manager that will control the new POA. If this parameter
   * is null, a new POA manager is created and associated with the new POA.
   *
   * @param policies the policies, applicable for the parent POA. Policies
   * are <i>not</i> inherited from the parent POA. If some policy type
   * is missing in the array (or the zero size array is passed), the missing
   * policies obtain the default values from the table, specified
   * in the {@link POA} documentation header.
   *
   * @return an newly created POA. The POA will be intially in the holding
   * state and must be activated to start processing requests.
   *
   * @throws AdapterAlreadyExists if the child with the given child_name
   * already exists for the current POA.
   * @throws InvalidPolicy if the policies conflict with each other or are
   * otherwise inappropriate.
   *
   * @see POA for the list of required policies.
   * @see #the_children()
   */
  POA create_POA(String child_name, POAManager manager, Policy[] policies)
          throws AdapterAlreadyExists, InvalidPolicy;

  /**
  * Find and optionally activate the child POA with the given name.
  *
  * @param poa_name the name of the POA to find.
  * @param activate_it if the child with the specified name is not found
  * or inactive and this parameter is true, the target POA activator is
  * invoked to activate that child. If this succeeds, that child POA
  * is returned.
  *
  * @throws AdapterNonExistent if no active child with the given name
  * is found and one of the following is true:
  * a) the target POA has no associated
  * {@link AdapterActivator}. b) that activator fails to activate the
  * child POA. c) <code>activate_id</code> = false.
  */
  POA find_POA(String poa_name, boolean activate_it)
        throws AdapterNonExistent;

  /**
   * Generate the Object Id for the given servant and add the servant to
   * the Active Object Map using this Id a a key. If the servant
   * activator is set, its incarnate method will be called. In this case,
   * the passed servant in this method can be null; in this case, the servant,
   * returned by {@link ServantActivatorOperations#incarnate} will
   * be used.
   *
   * @param a_servant a servant that would serve the object with the
   * returned Object Id.
   *
   * @return the generated objert Id for the given servant.
   *
   * @throws ServantAlreadyActive if this servant is already in the
   * Active Object Map and the UNIQUE_ID policy applies.
   *
   * @throws WrongPolicy if the required policies SYSTEM_ID and RETAIN
   * do not apply to this POA.
   */
  byte[] activate_object(Servant a_servant)
                  throws ServantAlreadyActive, WrongPolicy;

  /**
   * Add the given servant to the Active Object Map as a servant for the
   * object with the provided Object Id. If the servant activator is
   * set, its incarnate method will be called. In this case,
   * the passed servant in this method can be null; in this case, the servant,
   * returned by {@link ServantActivatorOperations#incarnate} will
   * be used.
   *
   * @param an_Object_Id an object id for the given object.
   * @param a_servant a servant that will serve the object with the given
   * Object Id.
   *
   * @throws ObjectAlreadyActive if the given object id is already in the
   * Active Object Map.
   * @throws WrongPolicy if the required RETAIN policy does not apply to
   * this POA.
   * @throws BAD_PARAM if the passed object id is invalid due any reason.
   */
  void activate_object_with_id(byte[] an_Object_Id, Servant a_servant)
                        throws ServantAlreadyActive, ObjectAlreadyActive,
                               WrongPolicy;

  /**
   * <p>Deactivate object with the given id. Client, trying to call
   * method on the deactivated object will either receive the remote
   * exception ({@link org.omg.CORBA.OBJECT_NOT_EXIST}, minor 0x535503ec),
   * incomplete) or the object will be reactivated and serve the request.
   * The object can be reactivated only if the implicit activation
   * policy applies and the servant activator is set.</p><p>
   * The deactivated object will continue to process requests that arrived
   * before decativation.
   * If this POA has the associated servant manager, a
   * {@link ServantActivatorOperations#etherealize} is <i>immediately</i>
   * invoked on the passed id. The deactivated object can be reactivated
   * by {@link #activate_object_with_id}.</p>
   * <p>The deactivation will not release thread, port or memory resources,
   * taken by that object. This is due requirement to make the
   * object reactivation possible at any time. To release the resources,
   * you must destroy the POA.
   * </p>
   *
   * @throws WrongPolicy if the required RETAIN policy does not apply to
   * this POA.
   */
  void deactivate_object(byte[] the_Object_Id)
                  throws ObjectNotActive, WrongPolicy;

  /**
  * Create the object reference, encapsulating the given repository Id and
  * the Object Id, generated by this POA. The returned object will not be
  * activated by default and may be activated on the first invocation by
  * the servant manager (if it is set and if policies are applicable).
  * The returned object can also be narrowed by helper and used locally.
  * In this case, the servant will be activated on the first local call of
  * any method. The methods on returned object can also be invoked by
  * name, using {@link org.omg.CORBA.Request}.
  *
  * @param a_repository_id the repository id for the given object. When
  * narrowing the returned object with some helper, it will be checked for
  * equality with value, returned by the the helper id().
  *
  * @throws WrongPolicy if the required SYSTEM_ID policy does not apply to
  * this POA.
  */
  org.omg.CORBA.Object create_reference(String a_repository_id)
                                 throws WrongPolicy;

  /**
  * <p> Create the object reference, encapsulating the given repository Id and
  * the given Object Id. The returned object will not be
  * activated by default and may be activated on the first invocation by
  * the servant manager (if it is set and if policies are applicable).
  * </p><p>
  * The returned object can also be narrowed by helper and used locally.
  * In this case, the servant will be activated on the first local call of
  * any method. The methods on returned object can also be invoked by
  * name, using {@link org.omg.CORBA.Request}.
  * </p>
  *
  * @param an_object_id the object id for the object being created.
  * If the POA uses the SYSTEM_ID policy, the portable application
  * must only supply ids, generated by that POA.
  *
  * @param a_repository_id the repository id for the given object. When
  * narrowing the returned object with some helper, it will be checked for
  * equality with value, returned by the the helper id().
  */
  org.omg.CORBA.Object create_reference_with_id(byte[] an_object_id,
                                                String a_repository_id
                                               );

  /**
   * Returns a default servant for this POA.
   *
   * @return a servant that will be used for requests for
   * which no servant is found in the Active Object Map.
   *
   * @throws NoServant if there is no default servant associated with this POA.
   * @throws WrongPolicy if the USE_DEFAULT_SERVANT policy is not active.
   */
  Servant get_servant()
               throws NoServant, WrongPolicy;

  /**
   * Sets the default servant for this POA.
   *
   * @param a_servant a servant that will be used for requests for
   * which no servant is found in the Active Object Map.
   *
   * @throws WrongPolicy if the USE_DEFAULT_SERVANT policy is not active.
   */
  void set_servant(Servant a_servant)
            throws WrongPolicy;

  /**
   * Set a servant manager for this POA.
   *
   * @param a_manager servant manager being set. If the RETAIN policy applies, the
   * manager must implement a {@link ServantActivator}. If the NON_RETAIN
   * policy applies, the manager must implement a {@link ServantLocator}.
   *
   * @throws WrongPolicy if the required USE_SERVANT_MANAGER policy does not
   * apply to this POA.
   *
   * @throws OBJ_ADAPTER minor code 4 if the passed manager does not
   * implement the required interface ({@link ServantActivator},
   * {@link ServantLocator}).
   *
   * @throws BAD_INV_ORDER minor code 6 if the method is called more than once
   * on the same POA. The manager can be set only once.
   */
  void set_servant_manager(ServantManager a_manager)
                    throws WrongPolicy;

  /**
   * Get the servant manager, associated with this POA.
   *
   * @return the associated servant manager or null if it has
   * been previously set.
   *
   * @throws WrongPolicy if the required USE_SERVANT_MANAGER policy does not
   * apply to this POA.
   */
  ServantManager get_servant_manager()
                              throws WrongPolicy;

  /**
   * Get the unique Id of the POA in the process in which it is created.
   * This Id is needed by portable interceptors. The id is unique
   * for the life span of the POA in the process. For persistent
   * POAs, if a POA is created in the same path with the same name as
   * another POA, these POAs are identical have the same id. All transient
   * POAs are assumed unique.
   */
  byte[] id();

  /**
   * Returns the reference to the active object with the given Id.
   *
   * @param the_Object_Id the object id.
   *
   * @throws ObjectNotActive if there is no active object with such Id.
   * @throws WrongPolicy if the required RETAIN policy does not apply to
   * this POA.
   */
  org.omg.CORBA.Object id_to_reference(byte[] the_Object_Id)
                                throws ObjectNotActive, WrongPolicy;

  /**
   * Returns the servant that serves the active object with the given Id.
   *
   * @param the_Object_Id the object id.
   *
   * @throws ObjectNotActive if there is no active object with such Id.
   * @throws WrongPolicy This method requires either RETAIN or
   * USE_DEFAULT_SERVANT policies and reaises the WrongPolicy if none of them
   * apply to this POA.
   */
  Servant id_to_servant(byte[] the_Object_Id)
                 throws ObjectNotActive, WrongPolicy;

  /**
   * Returns the Object Id, encapsulated in the given object reference.
   *
   * @param the_Object the object that has been previously created with this
   * POA. It need not be active.
   *
   * @throws WrongAdapter if the passed object has not been previously created
   * with this POA.
   * @throws WrongPolicy never (declared for the future extensions only).
   */
  byte[] reference_to_id(org.omg.CORBA.Object the_Object)
                  throws WrongAdapter, WrongPolicy;

  /**
   * Returns the servant that is serving this object.
   *
   * @return if the RETAIN policy applies and the object is in the Active
   * Object Map, the method returns the servant, associated with this object.
   * Otherwise, if the USE_DEFAULT_SERVANT policy applies, the method returns
   * the default servant (if one was set).
   *
   * @throws ObjectNotActive if none of the conditions above are satisfied.
   * @throws WrongAdapter if the object reference was not created with this POA.
   * @throws WrongPolicy This method requires either RETAIN or
   * USE_DEFAULT_SERVANT policies and reaises the WrongPolicy if none of them
   * apply to this POA.
   */
  Servant reference_to_servant(org.omg.CORBA.Object the_Object)
                        throws ObjectNotActive, WrongPolicy, WrongAdapter;

  /**
  * Returns the id of the object, served by the given servant. The id is found
  * in one of the following ways.
  * <ul>
  * <li>If the POA has both the RETAIN and the UNIQUE_ID policy and
  * the specified servant is active, the method return the Object Id associated
  * with that servant.
  * </li><li>
  * If the POA has both the RETAIN and the IMPLICIT_ACTIVATION policy and
  * either the POA has the MULTIPLE_ID policy or the specified servant is
  * inactive, the method activates the servant using a POA-generated Object Id
  * and the Interface Id associated with the servant, and returns that
  * Object Id.
  * </li>
  * <li>If the POA has the USE_DEFAULT_SERVANT policy, the servant specified
  * is the default servant, and the method is being invoked in the context o
  * f executing a request on the default servant, the method returns the
  * ObjectId associated with the current invocation.
  * </li>
  * </ul>
  * @throws ServantNotActive in all cases, not listed in the list above.
  * @throws WrongPolicy The method requres USE_DEFAULT_SERVANT policy or
  * a combination of the RETAIN policy and either the UNIQUE_ID or
  * IMPLICIT_ACTIVATION policies and throws the WrongPolicy if these conditions
  * are not satisfied.
  */
  byte[] servant_to_id(Servant the_Servant)
                throws ServantNotActive, WrongPolicy;

  /**
   * <p>Converts the given servant to the object reference.
   * The servant will serve all methods, invoked on the returned object.
   * The returned object reference can be passed to the remote client,
   * enabling remote invocations.
   * </p><p>
   * If the specified servant already serves some active object, that
   * object is returned. Otherwise,
   * if the POA has the IMPLICIT_ACTIVATION policy the method activates
   * the servant, creating an new object with the POA-generated Object Id.
   * In this case, if the servant activator is set, the
   * {@link ServantActivatorOperations#incarnate} method will be called.
   * </p>
   *
   * @throws ServantNotActive if the servant is inactive and no
   * IMPLICIT_ACTIVATION policy applies.
   * @throws WrongPolicy This method needs the RETAIN policy and either the
   * UNIQUE_ID or IMPLICIT_ACTIVATION policies.
   *
   * @return the object, exposing the given servant in the context of this POA.
   */
  org.omg.CORBA.Object servant_to_reference(Servant the_Servant)
                                     throws ServantNotActive, WrongPolicy;

  /**
   * Return the POA manager, associated with this POA.
   *
   * @return the associated POA manager (always available).
   */
  POAManager the_POAManager();

  /**
   * Returns the adapter activator, associated with this POA.
   * The newly created POA has no activator (null would be
   * returned). The ORB root POA also initially has no activator.
   *
   * @return tha adapter activator or null if this POA has no
   * associated adapter activator.
   */
  AdapterActivator the_activator();

  /**
  * Set the adapter activator for this POA.
  *
  * @param activator the activator being set.
  */
  void the_activator(AdapterActivator activator);

  /**
  * The children of this POA.
  *
  * @return the array of all childs for this POA.
  */
  POA[] the_children();

  /**
   * Return the name of this POA.
   *
   * @return the name of POA, relative to its parent.
   */
  String the_name();

  /**
   * Return the parent of this POA.
   *
   * @return the parent POA or <code>null</code> if this is a root POA.
   */
  POA the_parent();

  /**
   * <p> Destroy this POA and all descendant POAs. The destroyed POAs can be
   * later re-created via {@link AdapterActivator} or by invoking
   * {@link #create_POA}.
   * This differs from {@link POAManagerOperations#deactivate} that does
   * not allow recreation of the deactivated POAs. After deactivation,
   * recreation is only possible if the POAs were later destroyed.
   * </p><p>
   * The remote invocation on the target, belonging to the POA that is
   * currently destroyed return the remote exception ({@link TRANSIENT},
   * minor code 4).
   * </p>
   * @param etherealize_objects if true, and POA has RETAIN policy, and the
   * servant manager is available, the servant manager method
   * {@link ServantActivatorOperations#etherealize} is called for each
   *  <i>active</i> object in the Active Object Map. This method should not
   * try to access POA being destroyed. If <code>destroy</code> is called
   * multiple times before the destruction completes,
   * the etherialization should be invoked only once.
   *
   * @param wait_for_completion if true, the method waits till the POA being
   * destroyed completes all current requests and etherialization. If false,
   * the method returns immediately.
   */
  void destroy(boolean etherealize_objects, boolean wait_for_completion);

  /**
   * Create the IdUniquenessPolicy policy.
   *
   * @param a_value states which one Id uniqueness policy will apply.
   *
   * @return the created policy.
   */
  IdUniquenessPolicy create_id_uniqueness_policy(IdUniquenessPolicyValue a_value);

  /**
   * Create the ImplicitActivationPolicy policy.
   *
   * @param a_value states which one activation policy will apply.
   *
   * @return the created policy.
   */
  ImplicitActivationPolicy create_implicit_activation_policy(ImplicitActivationPolicyValue a_value);

  /**
   * Create the LifespanPolicy policy.
   *
   * @param a_value states which one object lifespan policy will apply.
   *
   * @return the created policy.
   */
  LifespanPolicy create_lifespan_policy(LifespanPolicyValue a_value);

  /**
   * Create the RequestProcessingPolicy policy.
   *
   * @param a_value states which one request processing policy will apply.
   *
   * @return the created policy.
   */
  RequestProcessingPolicy create_request_processing_policy(RequestProcessingPolicyValue a_value);

  /**
   * Create the ServantRetentionPolicy policy.
   *
   * @param a_value states which one servant retention policy will apply.
   *
   * @return the created policy.
   */
  ServantRetentionPolicy create_servant_retention_policy(ServantRetentionPolicyValue a_value);

  /**
   * Create the ThreadPolicy policy.
   *
   * @param a_value states which one thread policy will apply.
   *
   * @return the created policy.
   */
  ThreadPolicy create_thread_policy(ThreadPolicyValue a_value);

  /**
  * Create the ID assignment policy with the given value.
  *
  * @param value states which one ID assignment policy will apply.
  *
  * @return the created policy.
  */
  IdAssignmentPolicy create_id_assignment_policy(IdAssignmentPolicyValue value);

}