Mercurial > jdk8-mips64-public > corba / file revision
src/share/classes/org/omg/PortableServer/poa.idl@6845b95cba6b
src/share/classes/org/omg/PortableServer/poa.idl
Thu, 31 Aug 2017 18:10:36 +0800
- author
- aoqi
- date
- Thu, 31 Aug 2017 18:10:36 +0800
- changeset 748
- 6845b95cba6b
- parent 158
- 91006f157c46
- parent 0
- 7ef37b2cdcad
- permissions
- -rw-r--r--
merge
1 /*
2 * Copyright (c) 1997, 2001, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
26 #include "corba.idl"
27 #include "CORBAX.idl"
29 #pragma prefix "omg.org"
30 /**
31 * All Mapping corresponds to the Chapter 11 of
32 * CORBA V2.3.1 specified by OMG document formal/99-10-07.pdf.
33 * The exception to this is the id attribute, which is added in ptc/00-08-06,
34 * section 11.3.8.26.
35 */
36 module PortableServer {
38 #pragma version PortableServer 2.3
40 // forward reference
41 interface POA;
43 /**
44 * List of POAs
45 */
46 typedef sequence<POA> POAList;
48 /**
49 * Values of type Servant support a language specific
50 * programming interface that can be used by the ORB to
51 * obtain a default POA for that servant.
52 * Some language mappings may allow Servant values to
53 * be implicitly converted to object references under
54 * appropriate conditions.
55 */
56 native Servant;
58 /**
59 * ObjectId value associated with the object reference.
60 */
61 typedef sequence<octet> ObjectId;
63 /**
64 * ForwardRequest to indicate to the ORB
65 * that it is responsible for delivering
66 * the current request and subsequent
67 * requests to the object denoted in the
68 * forward_reference member of the exception.
69 */
70 exception ForwardRequest { Object forward_reference; };
72 // **********************************************
73 //
74 // Policy interfaces
75 //
76 // **********************************************
78 /**
79 * The value representing THREAD_POLICY_ID.
80 */
81 const CORBA::PolicyType THREAD_POLICY_ID = 16;
82 /**
83 * The value representing LIFESPAN_POLICY_ID.
84 */
85 const CORBA::PolicyType LIFESPAN_POLICY_ID = 17;
86 /**
87 * The value representing ID_UNIQUENESS_POLICY_ID.
88 */
89 const CORBA::PolicyType ID_UNIQUENESS_POLICY_ID = 18;
90 /**
91 * The value representing ID_ASSIGNMENT_POLICY_ID.
92 */
93 const CORBA::PolicyType ID_ASSIGNMENT_POLICY_ID = 19;
94 /**
95 * The value representing IMPLICIT_ACTIVATION_POLICY_ID.
96 */
97 const CORBA::PolicyType IMPLICIT_ACTIVATION_POLICY_ID = 20;
98 /**
99 * The value representing SERVANT_RETENTION_POLICY_ID.
100 */
101 const CORBA::PolicyType SERVANT_RETENTION_POLICY_ID = 21;
102 /**
103 * The value representing REQUEST_PROCESSING_POLICY_ID.
104 */
105 const CORBA::PolicyType REQUEST_PROCESSING_POLICY_ID = 22;
107 /**
108 * The ThreadPolicyValue can have the following values.
109 * ORB_CTRL_MODEL - The ORB is responsible for assigning
110 * requests for an ORB- controlled POA to threads.
111 * SINGLE_THREAD_MODEL - Requests for a single-threaded
112 * POA are processed sequentially.
113 */
114 enum ThreadPolicyValue { ORB_CTRL_MODEL, SINGLE_THREAD_MODEL };
116 /**
117 * The ThreadPolicy specifies the threading model
118 * used with the created POA. The default is
119 * ORB_CTRL_MODEL.
120 */
121 interface ThreadPolicy : CORBA::Policy {
122 #pragma sun_local ThreadPolicy ""
123 /**
124 * specifies the policy value
125 */
126 readonly attribute ThreadPolicyValue value;
127 };
129 /**
130 * The LifespanPolicyValue can have the following values.
131 * TRANSIENT - The objects implemented in the POA
132 * cannot outlive the POA instance in which they are
133 * first created.
134 * PERSISTENT - The objects implemented in the POA can
135 * outlive the process in which they are first created.
136 */
137 enum LifespanPolicyValue { TRANSIENT, PERSISTENT };
139 /**
140 * The LifespanPolicy specifies the lifespan of the
141 * objects implemented in the created POA. The default
142 * is TRANSIENT.
143 */
144 interface LifespanPolicy : CORBA::Policy {
145 #pragma sun_local LifespanPolicy ""
146 /**
147 * specifies the policy value
148 */
149 readonly attribute LifespanPolicyValue value;
150 };
152 /**
153 * IdUniquenessPolicyValue can have the following values.
154 * UNIQUE_ID - Servants activated with that POA support
155 * exactly one Object Id. MULTIPLE_ID - a servant
156 * activated with that POA may support one or more
157 * Object Ids.
158 */
159 enum IdUniquenessPolicyValue { UNIQUE_ID, MULTIPLE_ID };
161 /**
162 * The IdUniquenessPolicy specifies whether the servants
163 * activated in the created POA must have unique object i
164 * identities. The default is UNIQUE_ID.
165 */
166 interface IdUniquenessPolicy : CORBA::Policy {
167 #pragma sun_local IdUniquenessPolicy ""
168 /**
169 * specifies the policy value
170 */
171 readonly attribute IdUniquenessPolicyValue value;
172 };
174 /**
175 * The IdAssignmentPolicyValue can have the following
176 * values. USER_ID - Objects created with that POA are
177 * assigned Object Ids only by the application.
178 * SYSTEM_ID - Objects created with that POA are
179 * assigned Object Ids only by the POA. If the POA also
180 * has the PERSISTENT policy, assigned Object Ids must
181 * be unique across all instantiations of the same POA.
182 */
183 enum IdAssignmentPolicyValue { USER_ID, SYSTEM_ID };
185 /**
186 * IdAssignmentPolicy specifies whether Object Ids in
187 * the created POA are generated by the application or
188 * by the ORB. The default is SYSTEM_ID.
189 */
190 interface IdAssignmentPolicy : CORBA::Policy {
191 #pragma sun_local IdAssignmentPolicy ""
192 /**
193 * specifies the policy value
194 */
195 readonly attribute IdAssignmentPolicyValue value;
196 };
198 /**
199 * ImplicitActivationPolicyValue has the following
200 * semantics.
201 * IMPLICIT_ACTIVATION to indicate implicit activation
202 * of servants. This requires SYSTEM_ID and RETAIN
203 * policies to be set.
204 * NO_IMPLICIT_ACTIVATION to indicate no implicit
205 * servant activation.
206 */
207 enum ImplicitActivationPolicyValue {
208 IMPLICIT_ACTIVATION, NO_IMPLICIT_ACTIVATION
209 };
211 /**
212 * This policy specifies whether implicit activation
213 * of servants is supported in the created POA.
214 */
215 interface ImplicitActivationPolicy : CORBA::Policy {
216 #pragma sun_local ImplicitActivationPolicy ""
217 /**
218 * specifies the policy value
219 */
220 readonly attribute ImplicitActivationPolicyValue value;
221 };
223 /**
224 * ServantRetentionPolicyValue can have the following
225 * values. RETAIN - to indicate that the POA will retain
226 * active servants in its Active Object Map.
227 * NON_RETAIN - to indicate Servants are not retained by
228 * the POA. If no ServantRetentionPolicy is specified at
229 * POA creation, the default is RETAIN.
230 */
231 enum ServantRetentionPolicyValue { RETAIN, NON_RETAIN };
233 /**
234 * This policy specifies whether the created POA retains
235 * active servants in an Active Object Map.
236 */
237 interface ServantRetentionPolicy : CORBA::Policy {
238 #pragma sun_local ServantRetentionPolicy ""
239 /**
240 * specifies the policy value
241 */
242 readonly attribute ServantRetentionPolicyValue value;
243 };
245 /**
246 * The RequestProcessingPolicyValue can have the following
247 * values. USE_ACTIVE_OBJECT_MAP_ONLY - If the Object Id
248 * is not found in the Active Object Map,
249 * an OBJECT_NOT_EXIST exception is returned to the
250 * client. The RETAIN policy is also required.
251 * USE_DEFAULT_SERVANT - If the Object Id is not found in
252 * the Active Object Map or the NON_RETAIN policy is
253 * present, and a default servant has been registered
254 * with the POA using the set_servant operation,
255 * the request is dispatched to the default servant.
256 * USE_SERVANT_MANAGER - If the Object Id is not found
257 * in the Active Object Map or the NON_RETAIN policy
258 * is present, and a servant manager has been registered
259 * with the POA using the set_servant_manager operation,
260 * the servant manager is given the opportunity to
261 * locate a servant or raise an exception.
262 */
263 enum RequestProcessingPolicyValue {
264 USE_ACTIVE_OBJECT_MAP_ONLY, USE_DEFAULT_SERVANT, USE_SERVANT_MANAGER
265 };
267 /**
268 * This policy specifies how requests are processed by
269 * the created POA. The default is
270 * USE_ACTIVE_OBJECT_MAP_ONLY.
271 */
272 interface RequestProcessingPolicy : CORBA::Policy {
273 #pragma sun_local RequestProcessingPolicy ""
274 /**
275 * specifies the policy value
276 */
277 readonly attribute RequestProcessingPolicyValue value;
278 };
281 // **************************************************
282 //
283 // POAManager interface
284 //
285 // **********************************
286 /**
287 * Each POA object has an associated POAManager object.
288 * A POA manager may be associated with one or more
289 * POA objects. A POA manager encapsulates the processing
290 * state of the POAs it is associated with.
291 */
292 interface POAManager {
293 #pragma sun_local POAManager ""
294 exception AdapterInactive{ };
295 /**
296 * Specifies the states for the POAManager
297 */
298 enum State {HOLDING, ACTIVE, DISCARDING, INACTIVE};
300 /**
301 * This operation changes the state of the POA manager
302 * to active, causing associated POAs to start processing
303 * requests.
304 * @exception AdapterInactive is raised if the operation is
305 * invoked on the POAManager in inactive state.
306 */
307 void activate()
308 raises(AdapterInactive);
309 /**
310 * This operation changes the state of the POA manager
311 * to holding, causing associated POAs to queue incoming
312 * requests.
313 * @param wait_for_completion if FALSE, the operation
314 * returns immediately after changing state.
315 * If TRUE, it waits for all active requests
316 * to complete.
317 * @exception AdapterInactive is raised if the operation is
318 * invoked on the POAManager in inactive state.
319 */
320 void hold_requests(in boolean wait_for_completion)
321 raises(AdapterInactive);
322 /**
323 * This operation changes the state of the POA manager
324 * to discarding. This causes associated POAs to discard
325 * incoming requests.
326 * @param wait_for_completion if FALSE, the operation
327 * returns immediately after changing state.
328 * If TRUE, it waits for all active requests
329 * to complete.
330 * @exception AdapterInactive is raised if the operation is
331 * invoked on the POAManager in inactive state.
332 */
333 void discard_requests(in boolean wait_for_completion)
334 raises(AdapterInactive);
336 /**
337 * This operation changes the state of the POA manager
338 * to inactive, causing associated POAs to reject the
339 * requests that have not begun executing as well as
340 * as any new requests.
341 * @param etherealize_objects a flag to indicate whether
342 * to invoke the etherealize operation of the
343 * associated servant manager for all active
344 * objects.
345 * @param wait_for_completion if FALSE, the operation
346 * returns immediately after changing state.
347 * If TRUE, it waits for all active requests
348 * to complete.
349 * @exception AdapterInactive is raised if the operation is
350 * invoked on the POAManager in inactive state.
351 */
352 void deactivate(in boolean etherealize_objects,
353 in boolean wait_for_completion)
354 raises(AdapterInactive);
355 /**
356 * This operation returns the state of the POA manager.
357 */
358 State get_state();
359 };
362 // **************************************************
363 //
364 // AdapterActivator interface
365 //
366 // ****************************
368 /**
369 * An adapter activator supplies a POA with the ability
370 * to create child POAs on demand, as a side-effect of
371 * receiving a request that names the child POA
372 * (or one of its children), or when find_POA is called
373 * with an activate parameter value of TRUE.
374 */
376 interface AdapterActivator {
377 #pragma sun_local AdapterActivator ""
378 #pragma version AdapterActivator 2.3
379 /**
380 * This operation is invoked when the ORB receives
381 * a request for an object reference that identifies
382 * a target POA that does not exist. The ORB invokes
383 * this operation once for each POA that must be
384 * created in order for the target POA to exist.
385 * @param parent indicates the parent POA for the POA
386 * that needs to be created.
387 * @param name identifies the name of the POA relative to
388 * the parent.
389 * @return returns TRUE if the POA was created or FALSE
390 * otherwise.
391 */
392 boolean unknown_adapter(in POA parent, in string name);
393 };
396 // **************************************************
397 //
398 // ServantManager interface
399 //
400 // ******************************
402 /**
403 * A servant manager supplies a POA with the ability
404 * to activate objects on demand when the POA receives
405 * a request targeted at an inactive object. A servant
406 * manager is registered with a POA as a callback object,
407 * to be invoked by the POA when necessary.
408 * ServantManagers can either be ServantActivators or
409 * ServantLocators. A ServantManager object must be
410 * local to the process containing the POA objects
411 * it is registered with.
412 */
414 interface ServantManager
415 { #pragma sun_local ServantManager "" };
418 /**
419 * When the POA has the RETAIN policy it uses servant
420 * managers that are ServantActivators.
421 */
422 interface ServantActivator : ServantManager {
423 #pragma version ServantActivator 2.3
424 #pragma sun_localservant ServantActivator ""
425 /**
426 * This operation is invoked by the POA whenever the
427 * POA receives a request for an object that is not
428 * currently active, assuming the POA has the
429 * USE_SERVANT_MANAGER and RETAIN policies.
430 * @param oid object Id associated with the object on
431 * the request was made.
432 * @param adapter object reference for the POA in which
433 * the object is being activated.
434 * @return Servant corresponding to oid is created or
435 * located by the user supplied servant manager.
436 * @exception ForwardRequest to indicate to the ORB
437 * that it is responsible for delivering
438 * the current request and subsequent
439 * requests to the object denoted in the
440 * forward_reference member of the exception.
441 */
442 Servant incarnate ( in ObjectId oid, in POA adapter )
443 raises (ForwardRequest);
444 /**
445 * This operation is invoked whenever a servant for
446 * an object is deactivated, assuming the POA has
447 * the USE_SERVANT_MANAGER and RETAIN policies.
448 * @param oid object Id associated with the object
449 * being deactivated.
450 * @param adapter object reference for the POA in which
451 * the object was active.
452 * @param serv contains reference to the servant
453 * associated with the object being deactivated.
454 * @param cleanup_in_progress if TRUE indicates that
455 * destroy or deactivate is called with
456 * etherealize_objects param of TRUE. FALSE
457 * indicates that etherealize was called due to
458 * other reasons.
459 * @param remaining_activations indicates whether the
460 * Servant Manager can destroy a servant. If
461 * set to TRUE, the Servant Manager should wait
462 * until all invocations in progress have
463 * completed.
464 */
465 void etherealize ( in ObjectId oid,
466 in POA adapter,
467 in Servant serv,
468 in boolean cleanup_in_progress,
469 in boolean remaining_activations);
470 };
473 /**
474 * When the POA has the NON_RETAIN policy it uses servant
475 * managers that are ServantLocators. Because the POA
476 * knows that the servant returned by this servant
477 * manager will be used only for a single request,
478 * it can supply extra information to the servant
479 * manager's operations and the servant manager's pair
480 * of operations may be able to cooperate to do
481 * something different than a ServantActivator.
482 * When the POA uses the ServantLocator interface,
483 * immediately after performing the operation invocation
484 * on the servant returned by preinvoke, the POA will
485 * invoke postinvoke on the servant manager, passing the
486 * ObjectId value and the Servant value as parameters
487 * (among others). This feature may be used to force
488 * every request for objects associated with a POA to
489 * be mediated by the servant manager.
490 */
491 interface ServantLocator : ServantManager {
492 #pragma sun_localservant ServantLocator ""
493 /**
494 * Opaque data used to pass the information from
495 * preinvoke to postinvoke hooks. This specific
496 * by the language mapping, that is why it is
497 * specified as native.
498 */
499 native Cookie;
500 /**
501 * This operations is used to get a servant that will be
502 * used to process the request that caused preinvoke to
503 * be called.
504 * @param oid the object id associated with object on
505 * which the request was made.
506 * @param adapter the reference for POA in which the
507 * object is being activated.
508 * @param operation the operation name.
509 * @param the_cookie an opaque value that can be set
510 * by the servant manager to be used
511 * during postinvoke.
512 * @return Servant used to process incoming request.
513 * @exception ForwardRequest to indicate to the ORB
514 * that it is responsible for delivering
515 * the current request and subsequent
516 * requests to the object denoted in the
517 * forward_reference member of the exception.
518 */
519 Servant preinvoke( in ObjectId oid, in POA adapter,
520 in CORBA::Identifier operation,
521 out Cookie the_cookie )
522 raises (ForwardRequest);
523 /**
524 * This operation is invoked whenener a servant completes
525 * a request.
526 * @param oid the object id ssociated with object on which
527 * the request was made.
528 * @param adapter the reference for POA in which the
529 * object was active.
530 * @param the_cookie an opaque value that contains
531 * the data set by preinvoke.
532 * @param the_servant reference to the servant that is
533 * associated with the object.
534 */
535 void postinvoke( in ObjectId oid, in POA adapter,
536 in CORBA::Identifier operation,
537 in Cookie the_cookie,
538 in Servant the_servant);
539 };
542 // **************************************************
543 //
544 // POA interface
545 //
546 // *****************************************
548 /**
549 * A POA object manages the implementation of a
550 * collection of objects. The POA supports a name space
551 * for the objects, which are identified by Object Ids.
552 * A POA also provides a name space for POAs. A POA is
553 * created as a child of an existing POA, which forms a
554 * hierarchy starting with the root POA. A POA object
555 * must not be exported to other processes, or
556 * externalized with ORB::object_to_string.
557 */
558 interface POA {
559 #pragma sun_local POA ""
560 #pragma version POA 2.3
561 /**
562 * specifies that an child POA with the specified
563 * name already exists.
564 */
565 exception AdapterAlreadyExists { };
567 /**
568 * This is raised if the POA with a specified Name cannot
569 * be found.
570 */
571 exception AdapterNonExistent { };
573 /**
574 * This is raised if any of the policy objects are
575 * not valid for the ORB
576 */
577 exception InvalidPolicy {
578 unsigned short index;
579 };
581 /**
582 * This is raised if no default servant is associated
583 * with the POA.
584 */
585 exception NoServant { };
587 /**
588 * specifies that an object is already active or
589 * exists in the Active Object Map.
590 */
591 exception ObjectAlreadyActive { };
592 /**
593 * specifies that the object is not active or its
594 * mapping does not exist in the Active Object Map.
595 */
597 exception ObjectNotActive { };
599 /**
600 * This is raised when an attempt is made to activate
601 * a servant that is already active or has a mapping in
602 * the Active Object Map.
603 */
604 exception ServantAlreadyActive { };
606 /**
607 * This is raised when an attempt is made to access a
608 * servant that is not active or is not registered in
609 * the Active Object Map.
610 */
611 exception ServantNotActive { };
613 /**
614 * This is raised if the reference was not created by
615 * the POA
616 * specified in the reference.
617 */
618 exception WrongAdapter { };
620 /**
621 * WrongPolicy is specified when the POA does not
622 * specify the policy appropriate for its operations.
623 */
624 exception WrongPolicy { };
627 //----------------------------------------
628 //
629 // POA creation and destruction
630 //
631 //-------------------------------
633 /**
634 * This operation creates a new POA as a child of the
635 * target POA.
636 * @param adapter_name identifies the new POA with
637 * respect to other POAs with the same parent POA.
638 * @param a_POAManager specifies the POA Manager to be
639 * associated with the new POA.
640 * @param policies specifies policy objects to be
641 * associated with the POA to control its behavior.
642 * @exception AdapterAlreadyExists specifies that the
643 * target POA already has a child POA with
644 * the specified name.
645 * @exception InvalidPolicy is raised if any of the
646 * policy objects are not valid for the ORB,
647 * or are in conflict, or require an
648 * administrative action that has not been
649 * performed.
650 */
651 POA create_POA(in string adapter_name,
652 in POAManager a_POAManager,
653 in CORBA::PolicyList policies)
654 raises (AdapterAlreadyExists, InvalidPolicy);
656 /**
657 * If the target POA is the parent of a child POA with
658 * the specified name (relative to the target POA), that
659 * child POA is returned.
660 * @param adapter_name POA name to be found.
661 * @param activate_it if a POA with the specified
662 * name does not exist and the value of
663 * the activate_it parameter is TRUE, the target
664 * POA's AdapterActivator, if one exists,
665 * is invoked.
666 * @return POA if one exists or is activated by the
667 * AdapterActivator.
668 * @return AdapterNonExistent is raised if POA with
669 * a specified name cannot be found or
670 * activated using AdapaterActivator.
671 */
672 POA find_POA(in string adapter_name,
673 in boolean activate_it)
674 raises (AdapterNonExistent);
676 /**
677 * This operation destroys the POA and all descendant
678 * POAs. All descendant POAs are destroyed (recursively)
679 * before the destruction of the containing POA. The POA
680 * so destroyed (that is, the POA with its name) may be
681 * re-created later in the same process.
682 * @param etherealize_objects flag to indicate whether
683 * etherealize operation on servant manager needs
684 * to be called.
685 * @param wait_for_completion flag to indicate whether
686 * POA and its children need to wait for active
687 * requests and the etherealization to complete.
688 *
689 */
690 void destroy( in boolean etherealize_objects,
691 in boolean wait_for_completion);
693 // **************************************************
694 //
695 // Factories for Policy objects
696 //
697 // ************
698 /**
699 * These operations each return a reference to a policy
700 * object with the specified value.
701 * @param value policy type
702 * @return ThreadPolcy Object
703 */
704 ThreadPolicy create_thread_policy(
705 in ThreadPolicyValue value);
706 /**
707 * These operations each return a reference to a policy
708 * object with the specified value.
709 * @param value policy type
710 * @return LifespanPolicy Object.
711 */
712 LifespanPolicy create_lifespan_policy(
713 in LifespanPolicyValue value);
714 /**
715 * These operations each return a reference to a policy
716 * object with the specified value.
717 * @param value policy type
718 * @return IdUniquenessPolicy Object.
719 */
720 IdUniquenessPolicy create_id_uniqueness_policy(
721 in IdUniquenessPolicyValue value);
722 /**
723 * These operations each return a reference to a policy
724 * object with the specified value.
725 * @param value policy type
726 * @return IdAssignmentPolicy Object.
727 */
728 IdAssignmentPolicy create_id_assignment_policy(
729 in IdAssignmentPolicyValue value);
730 /**
731 * These operations each return a reference to a policy
732 * object with the specified value.
733 * @param value policy type
734 * @return ImplicitActivationPolicy Object.
735 */
736 ImplicitActivationPolicy create_implicit_activation_policy(
737 in ImplicitActivationPolicyValue value);
738 /**
739 * These operations each return a reference to a policy
740 * object with the specified value.
741 * @param value policy type
742 * @return ServantRetentionPolicy Object.
743 */
744 ServantRetentionPolicy create_servant_retention_policy(
745 in ServantRetentionPolicyValue value);
746 /**
747 * These operations each return a reference to a policy
748 * object with the specified value.
749 * @param value policy type
750 * @return RequestProcessingPolicy Object.
751 */
753 RequestProcessingPolicy create_request_processing_policy(
754 in RequestProcessingPolicyValue value);
756 //--------------------------------------------------
757 //
758 // POA attributes
759 //
760 //-----------------------------------
761 /**
762 * This attribute identifies the POA relative to its
763 * parent. This name is assigned when the POA is created.
764 */
765 readonly attribute string the_name;
766 /**
767 * This attribute identifies the parent of the POA.
768 * The parent of the root POA is null.
769 */
770 readonly attribute POA the_parent;
771 /**
772 * This attribute identifies the current set of all
773 * child POAs of the POA. The set of child POAs
774 * includes only the POA's immediate children, and
775 * not their descendants.
776 */
777 readonly attribute POAList the_children;
778 /**
779 * This attribute identifies the POA manager
780 * associated with the POA.
781 */
782 readonly attribute POAManager the_POAManager;
784 /**
785 * This attribute identifies the adapter activator
786 * associated with the POA.
787 */
788 attribute AdapterActivator the_activator;
790 //--------------------------------------------------
791 //
792 // Servant Manager registration:
793 //
794 //--------------------------------------------------
795 /**
796 *
797 * If the ServantRetentionPolicy of the POA is RETAIN,
798 * then the ServantManager argument (imgr) shall support
799 * the ServantActivator interface. For a NON_RETAIN policy,
800 * the ServantManager shall support the ServantLocator
801 * interface. If the argument is nil, or does not support
802 * the required interface, then the OBJ_ADAPTER
803 * exception is raised.
804 * @return ServantManager associated with a POA or null if
805 * none exists.
806 * @exception WrongPolicy raised if the
807 * USE_SERVANT_MANAGER policy is not specified.
808 */
809 ServantManager get_servant_manager()
810 raises (WrongPolicy);
811 /**
812 *
813 * This operation sets the default servant manager
814 * associated with the POA. This operation may only be
815 * invoked once after a POA has been created. Attempting
816 * to set the servant manager after one has already
817 * been set will result in the BAD_INV_ORDER exception
818 * being raised.
819 * @param imgr servant manager to be used as a default.
820 * @exception WrongPolicy raised if the
821 * USE_SERVANT_MANAGER policy is not specified.
822 */
823 void set_servant_manager( in ServantManager imgr)
824 raises (WrongPolicy);
826 //--------------------------------------------------
827 //
828 // operations for the USE_DEFAULT_SERVANT policy
829 //
830 //----------
831 /**
832 * This operation returns the default servant associated
833 * with the POA.
834 * @return p_servant default servant associated with a POA.
835 * @exception NoServant raised if no default servant is
836 * associated with the POA.
837 * @exception WrongPolicy raised if the
838 * USE_DEFAULT_SERVANT policy is not specified.
839 */
840 Servant get_servant()
841 raises (NoServant, WrongPolicy);
843 /**
844 *
845 * This operation registers the specified servant with
846 * the POA as the default servant. This servant will
847 * be used for all requests for which no servant is
848 * found in the Active Object Map.
849 * @param p_servant servant to be used as a default.
850 * @exception WrongPolicy raised if the
851 * USE_DEFAULT_SERVANT policy is not specified.
852 */
853 void set_servant(in Servant p_servant)
854 raises (WrongPolicy);
856 // **************************************************
857 //
858 // object activation and deactivation
859 //
860 // ************
862 /**
863 *
864 * This operation generates an Object Id and enters
865 * the Object Id and the specified servant in the
866 * Active Object Map.
867 * @param p_servant servant to be associated with an
868 * object to be activated.
869 * @return POA generated object id.
870 * @exception ServantAlreadyActive is raised if the
871 * POA has UNIQUE_ID policy and servant is
872 * is already in the Active Object Map.
873 * @exception WrongPolicy raised if the SYSTEM_ID and
874 * RETAIN policies are not specified.
875 */
876 ObjectId activate_object( in Servant p_servant )
877 raises (ServantAlreadyActive, WrongPolicy);
878 /**
879 * This operation enters an association between the
880 * specified Object Id and the specified servant in the
881 * Active Object Map.
882 * @param id object id for the object to be activated.
883 * @param p_servant servant to be associated with the
884 * object.
885 * @exception ServantAlreadyActive raised if the POA
886 * has the UNIQUE_ID policy and the servant
887 * is already in the Active Object Map.
888 * @exception ObjectAlreadyActive raised if the object is
889 * already active in the POA.
890 * @exception WrongPolicy raised if the RETAIN policy is
891 * is not specified.
892 */
894 void activate_object_with_id( in ObjectId id,
895 in Servant p_servant)
896 raises ( ServantAlreadyActive, ObjectAlreadyActive,
897 WrongPolicy);
898 /**
899 *
900 * This operation causes the ObjectId specified in the
901 * oid parameter to be deactivated. An ObjectId which
902 * has been deactivated continues to process requests
903 * until there are no active requests for that ObjectId.
904 * A deactivated ObjectId is removed from the Active
905 * Object Map when all requests executing for that
906 * ObjectId have completed.
907 * @param oid Object Id for the object to be deactivated.
908 * @exception ObjectNotActive if the object with the
909 * specified oid is not in the Active Object
910 * Map.
911 * @exception WrongPolicy raised if the RETAIN policy is
912 * is not specified.
913 */
914 void deactivate_object(in ObjectId oid)
915 raises (ObjectNotActive, WrongPolicy);
917 // **************************************************
918 //
919 // reference creation operations
920 //
921 // *****************
922 /**
923 * This operation creates an object reference that
924 * encapsulates a POA-generated Object Id value and
925 * the specified interface repository id.
926 *
927 * @param intf rep id for creating an object reference.
928 * @return object reference created using intf.
929 * @exception WrongPolicy if SYSTEM_ID policy is not
930 * specified.
931 */
932 Object create_reference ( in CORBA::RepositoryId intf )
933 raises (WrongPolicy);
935 /**
936 * This operation creates an object reference that
937 * encapsulates the specified Object Id and interface
938 * repository Id values. It does not cause an activation
939 * to take place. The resulting reference may be passed
940 * to clients, so that subsequent requests on those
941 * references will cause the object to be activated
942 * if necessary, or the default servant used, depending
943 * on the applicable policies.
944 * @param oid object id for creating an objref
945 * @param intf rep id for creating an objref
946 * @return object reference created using oid and intf
947 * @exception BAD_PARAM is raised if the POA has the
948 * SYSTEM_ID policy and it detects that the
949 * Object Id value was not generated by the
950 * system or for this POA.
951 */
952 Object create_reference_with_id ( in ObjectId oid,
953 in CORBA::RepositoryId intf );
954 // not specified in 11.3.8.19 raises (WrongPolicy);
956 //--------------------------------------------------
957 //
958 // Identity mapping operations:
959 //
960 //--------------------------------------------------
961 /**
962 * This operation has four possible behaviors.
963 * 1. If the POA has the UNIQUE_ID policy and the
964 * specified servant is active, the Object Id associated
965 * with that servant is returned.
966 * 2. If the POA has the IMPLICIT_ACTIVATION policy and
967 * either the POA has the MULTIPLE_ID policy or the
968 * specified servant is not active, the servant is
969 * activated using a POA-generated Object Id and the
970 * Interface Id associated with the servant, and that
971 * Object Id is returned.
972 * 3. If the POA has the USE_DEFAULT_SERVANT policy,
973 * the servant specified is the default servant, and the
974 * operation is being invoked in the context of executing
975 * a request on the default servant, then the ObjectId
976 * associated with the current invocation is returned.
977 * 4. Otherwise, the ServantNotActive exception is raised.
978 *
979 * @param p_servant servant for which the object disi returned.
980 * @return object id associated with the servant.
981 * @exception ServantNotActive if the above rules and
982 * policy combination is not met.
983 * @exception WrongPolicy if the USE_DEFAULT_SERVANT policy
984 * or a combination of the RETAIN policy and
985 * either the UNIQUE_ID or IMPLICIT_ACTIVATION
986 * policies are not present.
987 */
988 ObjectId servant_to_id(in Servant p_servant)
989 raises (ServantNotActive, WrongPolicy);
991 /**
992 * This operation requires the RETAIN policy and either
993 * the UNIQUE_ID or IMPLICIT_ACTIVATION policies if
994 * invoked outside the context of an operation dispatched
995 * by this POA. It has four possible behaviors.
996 * 1. If the POA has both the RETAIN and the
997 * UNIQUE_ID policy and the specified servant is active,
998 * an object reference encapsulating the information used
999 * to activate the servant is returned.
1000 * 2. If the POA has both the RETAIN and the
1001 * IMPLICIT_ACTIVATION policy and either the POA has the
1002 * MULTIPLE_ID policy or the specified servant is not
1003 * active, the servant is activated using a POA-generated
1004 * Object Id and the Interface Id associated with the
1005 * servant, and a corresponding object reference is
1006 * returned.
1007 * 3. If the operation was invoked in the context of
1008 * executing a request on the specified servant, the
1009 * reference associated with the current invocation
1010 * is returned.
1011 * 4. Otherwise, the ServantNotActive exception is raised.
1012 *
1013 * @param p_servant servant for which the object reference
1014 * needs to be obtained.
1015 * @return object reference associated with the servant.
1016 * @exception WrongPolicy if the operation is not invoked
1017 * in the context of executing a request on
1018 * the specified servant and the required
1019 * policies are not present.
1020 * @exception ServantNotActive if the above specified
1021 * policies and rules are not met.
1022 */
1023 Object servant_to_reference(in Servant p_servant)
1024 raises (ServantNotActive, WrongPolicy);
1026 /**
1027 * If the POA has the RETAIN policy and the specified
1028 * object is present in the Active Object Map, this
1029 * operation returns the servant associated with that
1030 * object in the Active Object Map. Otherwise, if the
1031 * POA has the USE_DEFAULT_SERVANT policy and a default
1032 * servant has been registered with the POA, this
1033 * operation returns the default servant. If the object
1034 * reference was not created by this POA,
1035 * the WrongAdapter exception is raised. (OMG Issue
1036 * on inconsistency with the POA.IDL.
1037 *
1038 * @param reference object reference for which the
1039 * servant is returned.
1040 * @return servant associated with the reference.
1041 * @exception WrongPolicy if neither the RETAIN policy or
1042 * the USE_DEFAULT_SERVANT policy is present.
1043 * @exception ObjectNotActive if the servant is not
1044 * present in the Active Object Map (for RETAIN)
1045 * or no default servant is registered (for
1046 * USE_DEFAULT_POLICY).
1047 * @exception WrongAdapter if reference was not created by
1048 * this POA instance.
1049 */
1050 Servant reference_to_servant(in Object reference)
1051 raises (ObjectNotActive, WrongPolicy, WrongAdapter);
1053 /**
1054 * This operation returns the Object Id value
1055 * encapsulated by the specified reference. This
1056 * operation is valid only if the reference was created
1057 * by the POA on which the operation is being performed.
1058 * The object denoted by the reference does not have
1059 * to be active for this operation to succeed.
1060 *
1061 * @param reference the object reference from which the
1062 * object id needs to be returned.
1063 * @return object id encapsulated in the reference.
1064 * @exception WrongAdapter if the reference was not
1065 * created by the POA specified in the
1066 * reference.
1067 * @exception WrongPolicy declared to allow future
1068 * extensions.
1069 *
1070 */
1071 ObjectId reference_to_id(in Object reference)
1072 raises (WrongAdapter, WrongPolicy);
1074 /**
1075 * If the POA has the RETAIN policy and the specified
1076 * ObjectId is in the Active Object Map, this operation
1077 * returns the servant associated with that object in
1078 * the Active Object Map. Otherwise, if the POA has
1079 * the USE_DEFAULT_SERVANT policy and a default servant
1080 * has been registered with the POA, this operation
1081 * returns the default servant.
1082 *
1083 * @param oid object id for the which the servant is
1084 * returned.
1085 * @return servant associated with oid.
1086 * @exception ObjectNotActive is raised if ObjectId is
1087 * is not in the Active Object Map (for RETAIN
1088 * policy), or no default servant is registered
1089 * (for USE_DEFAULT_SERVANT policy).
1090 *
1091 * @exception WrongPolicy is raised if the RETAIN policy
1092 * or the USE_DEFAULT_SERVANT
1093 * policy is not present.
1094 */
1095 Servant id_to_servant(in ObjectId oid)
1096 raises (ObjectNotActive, WrongPolicy);
1098 /**
1099 * If an object with the specified Object Id value is
1100 * currently active, a reference encapsulating the
1101 * information used to activate the object is returned.
1102 *
1103 * @param oid id of the object for which the
1104 * reference is returned.
1105 * @return the object reference
1106 *
1107 * @exception ObjectNotActive if the Object Id value
1108 * is not active in the POA.
1109 * @exception WrongPolicy if the RETAIN policy is not
1110 * present.
1111 */
1112 Object id_to_reference(in ObjectId oid)
1113 raises (ObjectNotActive, WrongPolicy);
1115 /**
1116 * This returns the unique id of the POA in the process in which it
1117 * is created. It is for use by portable interceptors.
1118 * <p>
1119 * This id is guaranteed unique for the life span of the POA in the
1120 * process. For persistent POAs, this means that if a POA is created
1121 * in the same path with the same name as another POA, these POAs
1122 * are identical and, therefore, have the same id. For transient
1123 * POAs, each POA is unique.
1124 */
1125 readonly attribute ::org::omg::CORBA::OctetSeq id;
1127 };
1129 // *****************************************************
1130 //
1131 // Current interface:
1132 //
1133 // *****************************************************
1135 /**
1136 * The PortableServer::Current interface, derived from
1137 * CORBA::Current, provides method implementations with
1138 * access to the identity of the object on which the
1139 * method was invoked. The Current interface is provided
1140 * to support servants that implement multiple objects,
1141 * but can be used within the context of POA-dispatched
1142 * method invocations on any servant. To provide location
1143 * transparency, ORBs are required to support use of
1144 * Current in the context of both locally and remotely
1145 * invoked operations. An instance of Current can be
1146 * obtained by the application by issuing the
1147 * CORBA::ORB::resolve_initial_references("POACurrent")
1148 * operation. Thereafter, it can be used within the
1149 * context of a method dispatched by the POA to obtain
1150 * the POA and ObjectId that identify the object on
1151 * which that operation was invoked.
1152 */
1153 interface Current : CORBA::Current {
1154 #pragma sun_local Current ""
1155 #pragma version Current 2.3
1156 /**
1157 * The exception that is used to indicate that the
1158 * operation is invoked outside the context of the
1159 * POA-dispatched operation.
1160 */
1162 exception NoContext { };
1164 /**
1165 * Returns reference to the POA implementing the
1166 * object in whose context it is called.
1167 *
1168 * @return The poa implementing the object
1169 *
1170 * @exception NoContext is raised when the operation is
1171 * outside the context of a POA-dispatched
1172 * operation
1173 */
1174 POA get_POA()
1175 raises (NoContext);
1177 /**
1178 * Returns the ObjectId identifying the object in
1179 * whose context it is called.
1180 *
1181 * @return the ObjectId of the object
1182 *
1183 * @exception NoContext is raised when the operation
1184 * is called outside the context of a POA-dispatched
1185 * operation.
1186 */
1188 ObjectId get_object_id()
1189 raises (NoContext);
1190 };
1191 };
