NVList
PIDL represented by ParameterList
IDL.
duke@1: * This exists in order to keep the Portable Interceptor IDL from becoming
duke@1: * PIDL.
duke@1: */
duke@1: struct Parameter {
duke@1: any argument;
duke@1: CORBA::ParameterMode mode;
duke@1: };
duke@1:
duke@1: /**
duke@1: * NVList
PIDL represented by ParameterList
IDL.
duke@1: * This exists in order to keep the Portable Interceptor IDL from becoming
duke@1: * PIDL.
duke@1: */
duke@1: typedef sequenceContextList
PIDL represented by ContextList
duke@1: * IDL. This exists in order to keep the Portable Interceptor IDL from
duke@1: * becoming PIDL.
duke@1: */
duke@1: typedef CORBA::StringSeq ContextList;
duke@1:
duke@1: /**
duke@1: * ExceptionList
PIDL represented by ExceptionList
duke@1: * IDL. This exists in order to keep the Portable Interceptor IDL from
duke@1: * becoming PIDL.
duke@1: */
duke@1: typedef sequenceContext
PIDL represented by RequestContext
duke@1: * IDL. This exists in order to keep the Portable Interceptor IDL from o
duke@1: * becoming PIDL.
duke@1: *
duke@1: * Context
objects are encoded as String[]
. The
duke@1: * Strings
occur in pairs. The first String
in
duke@1: * each pair is the context property name and the second String
duke@1: * in each pair is the associated value.
duke@1: */
duke@1: typedef CORBA::StringSeq RequestContext;
duke@1: };
duke@1:
duke@1: module PortableInterceptor {
duke@1: /**
duke@1: * All Portable Interceptors implement Interceptor.
duke@1: */
duke@1: local interface Interceptor {
duke@1: /**
duke@1: * Returns the name of the interceptor.
duke@1: *
duke@1: * Each Interceptor may have a name that may be used administratively
duke@1: * to order the lists of Interceptors. Only one Interceptor of a given
duke@1: * name can be registered with the ORB for each Interceptor type. An
duke@1: * Interceptor may be anonymous, i.e., have an empty string as the name
duke@1: * attribute. Any number of anonymous Interceptors may be registered with
duke@1: * the ORB.
duke@1: *
duke@1: * @return the name of the interceptor.
duke@1: */
duke@1: readonly attribute string name;
duke@1:
duke@1: // Added in ptc/00-08-06
duke@1: /**
duke@1: * Provides an opportunity to destroy this interceptor.
duke@1: * The destroy method is called during ORB.destroy
. When an
duke@1: * application calls ORB.destroy
, the ORB:
duke@1: *
Interceptor.destroy
operation for each
duke@1: * interceptorInterceptor.destroy
on
duke@1: * object references for objects implemented on the ORB being destroyed
duke@1: * result in undefined behavior. However, method invocations on objects
duke@1: * implemented on an ORB other than the one being destroyed are
duke@1: * permitted. (This means that the ORB being destroyed is still capable
duke@1: * of acting as a client, but not as a server.)
duke@1: */
duke@1: void destroy();
duke@1: };
duke@1:
duke@1:
duke@1: /**
duke@1: * The ForwardRequest
exception is the means by which an
duke@1: * Interceptor can indicate to the ORB that a retry of the request should
duke@1: * occur with the new object given in the exception. This behavior of
duke@1: * causing a retry only occurs if the ORB receives a ForwardRequest from
duke@1: * an interceptor. If ForwardRequest
is thrown anywhere else
duke@1: * it is passed through the ORB as is normal for a user exception.
duke@1: *
duke@1: * If an Interceptor throws a ForwardRequest
exception in
duke@1: * response to a call of an interceptor, no other Interceptors are called
duke@1: * for that interception point. The remaining Interceptors in the Flow Stack
duke@1: * shall have their appropriate ending interception point called:
duke@1: * receive_other
on the client, or send_other
on
duke@1: * the server. The reply_status
in the
duke@1: * receive_other
or send_other
would be
duke@1: * LOCATION_FORWARD
.
duke@1: */
duke@1: exception ForwardRequest {
duke@1: /**
duke@1: * The new object to forward the request to.
duke@1: */
duke@1: Object forward;
duke@1: // Change in ptc/00-08-06
duke@1: // boolean permanent;
duke@1: };
duke@1:
duke@1: /** Reply status, represented as an int */
duke@1: typedef short ReplyStatus;
duke@1:
duke@1: // Valid reply_status values:
duke@1:
duke@1: /**
duke@1: * Indicates a successful Reply Status. One possible value for
duke@1: * RequestInfo.reply_status
.
duke@1: * @see RequestInfo#reply_status
duke@1: * @see SYSTEM_EXCEPTION
duke@1: * @see USER_EXCEPTION
duke@1: * @see LOCATION_FORWARD
duke@1: * @see TRANSPORT_RETRY
duke@1: */
duke@1: const ReplyStatus SUCCESSFUL = 0;
duke@1:
duke@1: /**
duke@1: * Indicates a SystemException reply status. One possible value for
duke@1: * RequestInfo.reply_status
.
duke@1: * @see RequestInfo#reply_status
duke@1: * @see SUCCESSFUL
duke@1: * @see USER_EXCEPTION
duke@1: * @see LOCATION_FORWARD
duke@1: * @see TRANSPORT_RETRY
duke@1: */
duke@1: const ReplyStatus SYSTEM_EXCEPTION = 1;
duke@1:
duke@1: /**
duke@1: * Indicates a UserException reply status. One possible value for
duke@1: * RequestInfo.reply_status
.
duke@1: * @see RequestInfo#reply_status
duke@1: * @see SUCCESSFUL
duke@1: * @see SYSTEM_EXCEPTION
duke@1: * @see LOCATION_FORWARD
duke@1: * @see TRANSPORT_RETRY
duke@1: */
duke@1: const ReplyStatus USER_EXCEPTION = 2;
duke@1:
duke@1: /**
duke@1: * Indicates a LocationForward reply status. One possible value for
duke@1: * RequestInfo.reply_status
.
duke@1: * @see RequestInfo#reply_status
duke@1: * @see SUCCESSFUL
duke@1: * @see SYSTEM_EXCEPTION
duke@1: * @see USER_EXCEPTION
duke@1: * @see TRANSPORT_RETRY
duke@1: */
duke@1: const ReplyStatus LOCATION_FORWARD = 3;
duke@1:
duke@1: // Changes in ptc/00-08-06
duke@1: // const ReplyStatus LOCATION_FORWARD_PERMANENT = 4;
duke@1:
duke@1: /**
duke@1: * Indicates a Transport Retry reply status. One possible value for
duke@1: * RequestInfo.reply_status
.
duke@1: * @see RequestInfo#reply_status
duke@1: * @see SUCCESSFUL
duke@1: * @see SYSTEM_EXCEPTION
duke@1: * @see USER_EXCEPTION
duke@1: * @see LOCATION_FORWARD
duke@1: */
duke@1: const ReplyStatus TRANSPORT_RETRY = 4;
duke@1:
duke@1: /**
duke@1: * XXX
duke@1: */
duke@1: const ReplyStatus UNKNOWN = 5;
duke@1:
duke@1: /** Slot id, represented as an int */
duke@1: typedef unsigned long SlotId;
duke@1:
duke@1: /**
duke@1: * This exception is thrown when get_slot
or
duke@1: * set_slot
is called on a slot that has not been allocated.
duke@1: */
duke@1: exception InvalidSlot {};
duke@1:
duke@1: /**
duke@1: * Portable Interceptors Current (also known as PICurrent
)
duke@1: * is merely a slot table, the slots of which are used by each service to
duke@1: * transfer their context data between their context and the request's or
duke@1: * reply's service context. Each service which wishes to use PICurrent
duke@1: * reserves a slot or slots at initialization time and uses those slots
duke@1: * during the processing of requests and replies.
duke@1: *
duke@1: * Before an invocation is made, PICurrent is obtained via a call to
duke@1: * ORB.resolve_initial_references( "PICurrent" )
. From within
duke@1: * the interception points, the data on PICurrent that has moved from the
duke@1: * thread scope to the request scope is available via the
duke@1: * get_slot
operation on the RequestInfo
object.
duke@1: * A PICurrent can still be obtained via
duke@1: * resolve_initial_references
, but that is the Interceptor's
duke@1: * thread scope PICurrent.
duke@1: */
duke@1: local interface Current : CORBA::Current {
duke@1:
duke@1: /**
duke@1: * Retrieves the slot data the application set in PICurrent via
duke@1: * get_slot
. The data is in the form of an Any.
duke@1: *
duke@1: * If the given slot has not been set, an Any containing a type code
duke@1: * with a TCKind
value of tk_null
and no value
duke@1: * is returned.
duke@1: *
duke@1: * @param id The SlotId
of the slot from which the data will
duke@1: * be returned.
duke@1: * @return The data, in the form of an Any, of the given slot identifier.
duke@1: * @exception InvalidSlot thrown if get_slot is called on a slot that
duke@1: * has not been allocated.
duke@1: * @exception BAD_INV_ORDER thrown if get_slot
is called
duke@1: * from within an ORB initializer
duke@1: */
duke@1: any get_slot (in SlotId id) raises (InvalidSlot);
duke@1:
duke@1: /**
duke@1: * Sets data in a slot. The data is in the form of an Any. If data
duke@1: * already exists in that slot, it is overridden.
duke@1: *
duke@1: * @param id The SlotId
of the slot to which the data will
duke@1: * be set.
duke@1: * @param data The data, in the form of an Any, which will be set
duke@1: * to the identified slot.
duke@1: * @exception InvalidSlot thrown if set_slot
is called on
duke@1: * a slot that has not been allocated.
duke@1: * @exception BAD_INV_ORDER thrown if set_slot
is called
duke@1: * from within an ORB initializer.
duke@1: */
duke@1: void set_slot (in SlotId id, in any data) raises (InvalidSlot);
duke@1: };
duke@1:
duke@1: /**
duke@1: * Request Information, accessible to Interceptors.
duke@1: *
duke@1: * Each interception point is given an object through which the
duke@1: * Interceptor can access request information. Client-side and server-side
duke@1: * interception points are concerned with different information, so there
duke@1: * are two information objects: ClientRequestInfo
is passed
duke@1: * to the client-side interception points and ServerRequestInfo
duke@1: * is passed to the server-side interception points. But there is
duke@1: * information that is common to both, so they both inherit from a common
duke@1: * interface: RequestInfo
.
duke@1: *
duke@1: * @see ClientRequestInfo
duke@1: * @see ServerRequestInfo
duke@1: */
duke@1: local interface RequestInfo {
duke@1: /**
duke@1: * Returns an id that uniquely identifies an active request/reply
duke@1: * sequence. Once a request/reply sequence is concluded this ID may be
duke@1: * reused. Note that this id is not the same as the GIOP
duke@1: * request_id
. If GIOP is the transport mechanism used,
duke@1: * then these IDs may very well be the same, but this is not guaranteed
duke@1: * nor required.
duke@1: */
duke@1: readonly attribute unsigned long request_id;
duke@1:
duke@1: /**
duke@1: * Returns the name of the operation being invoked.
duke@1: */
duke@1: readonly attribute string operation;
duke@1:
duke@1: /**
duke@1: * Returns an array of Parameter
objects, containing the
duke@1: * arguments on the operation being invoked. If there are no arguments,
duke@1: * this attribute will be a zero length array.
duke@1: *
duke@1: * Not all environments provide access to the arguments. With the Java
duke@1: * portable bindings, for example, the arguments are not available.
duke@1: * In these environments, when this attribute is accessed,
duke@1: * NO_RESOURCES
will be thrown with a standard minor code
duke@1: * of 1.
duke@1: *
duke@1: * Note: Arguments are available for DSI/DII calls.
duke@1: *
duke@1: * @exception NO_RESOURCES thrown if arguments are not available.
duke@1: * @see
duke@1: * PortableInterceptor
package comments for
duke@1: * limitations / unimplemented features
duke@1: */
duke@1: readonly attribute Dynamic::ParameterList arguments;
duke@1:
duke@1: /**
duke@1: * Returns an array of TypeCode
objects describing the
duke@1: * TypeCode
s of the user exceptions that this operation
duke@1: * invocation may throw. If there are no user exceptions, this
duke@1: * will return a zero length array.
duke@1: *
duke@1: * Not all environments provide access to the exception list. With
duke@1: * the Java portable bindings, for example, the exception list is
duke@1: * not available. In these environments, when this attribute is
duke@1: * accessed, NO_RESOURCES
will be thrown with a
duke@1: * standard minor code of 1.
duke@1: *
duke@1: * Note: Exceptions are available for DSI/DII calls.
duke@1: *
duke@1: * @exception NO_RESOURCES thrown if exceptions are not available.
duke@1: * @see
duke@1: * PortableInterceptor
package comments for
duke@1: * limitations / unimplemented features
duke@1: */
duke@1: readonly attribute Dynamic::ExceptionList exceptions;
duke@1:
duke@1: /**
duke@1: * Returns an array of String
objects describing the
duke@1: * contexts that may be passed on this operation invocation. If there
duke@1: * are no contexts, this will return a zero length array.
duke@1: *
duke@1: * Not all environments provide access to the context list. With the
duke@1: * Java portable bindings, for example, the context list is not
duke@1: * available. In these environments, when this attribute is accessed,
duke@1: * NO_RESOURCES
will be thrown with a standard minor code
duke@1: * of 1.
duke@1: *
duke@1: * Note: Contexts are available for DSI/DII calls.
duke@1: *
duke@1: * @exception NO_RESOURCES thrown if contexts are not available.
duke@1: * @see
duke@1: * PortableInterceptor
package comments for
duke@1: * limitations / unimplemented features
duke@1: */
duke@1: readonly attribute Dynamic::ContextList contexts;
duke@1:
duke@1: /**
duke@1: * Returns an array of String
objects containing the
duke@1: * contexts being sent on the request.
duke@1: *
duke@1: * Not all environments provide access to the context. With the Java duke@1: * portable bindings, for example, the context is not available. In duke@1: * these environments, when this attribute is accessed, NO_RESOURCES will duke@1: * be thrown with standard minor code of 1. duke@1: *
duke@1: * Note: operation_context
is available for
duke@1: * DSI/DII calls.
duke@1: *
duke@1: * @exception NO_RESOURCES thrown if operation context is not available.
duke@1: * @see
duke@1: * PortableInterceptor
package comments for
duke@1: * limitations / unimplemented features
duke@1: */
duke@1: readonly attribute Dynamic::RequestContext operation_context;
duke@1:
duke@1: /**
duke@1: * Returns an any containing the result of the operation invocation.
duke@1: * If the operation return type is void, this attribute will be an any
duke@1: * containing a type code with a TCKind
value of
duke@1: * tk_void
and no value.
duke@1: *
duke@1: * Not all environments provide access to the result. With the Java
duke@1: * portable bindings, for example, the result is not available. In
duke@1: * these environments, when this attribute is accessed,
duke@1: * NO_RESOURCES
will be thrown with a standard minor code of
duke@1: * 1.
duke@1: *
duke@1: * Note: Result is available for DSI/DII calls.
duke@1: *
duke@1: * @exception NO_RESOURCES thrown if result is not available.
duke@1: * @see
duke@1: * PortableInterceptor
package comments for
duke@1: * limitations / unimplemented features
duke@1: */
duke@1: readonly attribute any result;
duke@1:
duke@1: /**
duke@1: * Indicates whether a response is expected.
duke@1: *
duke@1: * On the client, a reply is not returned when
duke@1: * response_expected
is false, so receive_reply
duke@1: * cannot be called. receive_other
is called unless an
duke@1: * exception occurs, in which case receive_exception
is
duke@1: * called.
duke@1: *
duke@1: * On the client, within send_poll
, this attribute is true.
duke@1: */
duke@1: readonly attribute boolean response_expected;
duke@1:
duke@1: /**
duke@1: * Defines how far the request shall progress before control is returned
duke@1: * to the client. This is defined in the Messaging specification, and
duke@1: * is pertinent only when response_expected
is false. If
duke@1: * response_expected
is true, the value of
duke@1: * sync_scope
is undefined. This attribute may have one of
duke@1: * the following values:
duke@1: *
Messaging.SYNC_NONE
Messaging.SYNC_WITH_TRANSPORT
Messaging.SYNC_WITH_SERVER
Messaging.SYNC_WITH_TARGET
receive_request_service_contexts
,
duke@1: * receive_request
, send_reply
or
duke@1: * send_exception
).
duke@1: *
duke@1: * For SYNC_WITH_SERVER
and SYNC_WITH_TARGET
,
duke@1: * the server does send an empty reply back to the client before the
duke@1: * target is invoked. This reply is not intercepted by server-side
duke@1: * Interceptors.
duke@1: *
duke@1: * @see
duke@1: * PortableInterceptor
package comments for
duke@1: * limitations / unimplemented features
duke@1: */
duke@1: readonly attribute Messaging::SyncScope sync_scope;
duke@1:
duke@1: /**
duke@1: * Describes the state of the result of the operation invocation. The
duke@1: * return value can be one of the following:
duke@1: *
PortableInterceptor.SUCCESSFUL
PortableInterceptor.SYSTEM_EXCEPTION
PortableInterceptor.USER_EXCEPTION
PortableInterceptor.LOCATION_FORWARD
PortableInterceptor.TRANSPORT_RETRY
receive_reply
interception point, this
duke@1: * will only return SUCCESSFUL
receive_exception
interception point,
duke@1: * this will be either SYSTEM_EXCEPTION
or
duke@1: * USER_EXCEPTION
.receive_other
interception point, this
duke@1: * will be any of: SUCCESSFUL
,
duke@1: * LOCATION_FORWARD
, or TRANSPORT_RETRY
.
duke@1: * SUCCESSFUL
means an asynchronous request returned
duke@1: * successfully. LOCATION_FORWARD
means that a reply
duke@1: * came back with LOCATION_FORWARD
as its status.
duke@1: * TRANSPORT_RETRY
means that the transport
duke@1: * mechanism indicated a retry - a GIOP reply with a status of
duke@1: * NEEDS_ADDRESSING_MODE
, for instance. send_reply
interception point, this
duke@1: * will only be SUCCESSFUL
.send_exception
interception point,
duke@1: * this will be either SYSTEM_EXCEPTION
or
duke@1: * USER_EXCEPTION
.send_other
interception point, this
duke@1: * attribute will be any of: SUCCESSFUL
, or
duke@1: * LOCATION_FORWARD
. SUCCESSFUL
means
duke@1: * an asynchronous request returned successfully.
duke@1: * LOCATION_FORWARD
means that a reply came back
duke@1: * with LOCATION_FORWARD
as its status.reply_status
attribute is LOCATION_FORWARD
.
duke@1: * It is indeterminate whether a forwarded request will actually occur.
duke@1: */
duke@1: readonly attribute Object forward_reference;
duke@1:
duke@1: /**
duke@1: * Returns the data from the given slot of the
duke@1: * PortableInterceptor.Current
that is in the scope of
duke@1: * the request.
duke@1: *
duke@1: * If the given slot has not been set, then an any containing a
duke@1: * type code with a TCKind
value of tk_null
is
duke@1: * returned.
duke@1: *
duke@1: * @param id The SlotId
of the slot which is to be
duke@1: * returned.
duke@1: * @return The slot data, in the form of an any, obtained with the
duke@1: * given identifier.
duke@1: * @exception InvalidSlot thrown if the ID does not define an
duke@1: * allocated slot.
duke@1: * @see Current
duke@1: */
duke@1: any get_slot (in SlotId id) raises (InvalidSlot);
duke@1:
duke@1: /**
duke@1: * Returns a copy of the service context with the given ID that
duke@1: * is associated with the request.
duke@1: *
duke@1: * @param id The IOP.ServiceId
of the service context
duke@1: * which is to be returned.
duke@1: * @return The IOP.ServiceContext
obtained with the
duke@1: * given identifier.
duke@1: * @exception BAD_PARAM thrown with a standard minor code of 26, if the
duke@1: * request's service context does not contain an entry for that ID.
duke@1: */
duke@1: IOP::ServiceContext get_request_service_context
duke@1: (in IOP::ServiceId id);
duke@1:
duke@1: /**
duke@1: * Returns a copy of the service context with the given ID that
duke@1: * is associated with the reply.
duke@1: *
duke@1: * @param id The IOP.ServiceId
of the service context
duke@1: * which is to be returned.
duke@1: * @return The IOP.ServiceContext
obtained with the given
duke@1: * identifier.
duke@1: * @exception BAD_PARAM thrown with a standard minor code of 26 if the
duke@1: * request's service context does not contain an entry for that ID.
duke@1: */
duke@1: IOP::ServiceContext get_reply_service_context
duke@1: (in IOP::ServiceId id);
duke@1: };
duke@1:
duke@1: /**
duke@1: * Request Information, accessible to client-side request interceptors.
duke@1: *
duke@1: * Some attributes and operations on ClientRequestInfo
are
duke@1: * not valid at all interception points. The following table shows the
duke@1: * validity of each attribute or operation. If it is not valid, attempting
duke@1: * to access it will result in a BAD_INV_ORDER
being thrown
duke@1: * with a standard minor code of 14.
duke@1: *
duke@1: * duke@1: *
duke@1: * | send_request | duke@1: *send_poll | duke@1: *receive_reply | duke@1: *receive_exception | duke@1: *receive_other | duke@1: *
---|---|---|---|---|---|
Inherited from RequestInfo: | duke@1: *|||||
request_id |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
operation |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
arguments |
duke@1: * yes1 | duke@1: *no | duke@1: *yes | duke@1: *no | duke@1: *no |
exceptions |
duke@1: * yes | duke@1: *no | duke@1: *yes | duke@1: *yes | duke@1: *yes |
contexts |
duke@1: * yes | duke@1: *no | duke@1: *yes | duke@1: *yes | duke@1: *yes |
operation_context |
duke@1: * yes | duke@1: *no | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *
result |
duke@1: * no | duke@1: *no | duke@1: *yes | duke@1: *no | duke@1: *no | duke@1: *
response_expected |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
sync_scope |
duke@1: * yes | duke@1: *no | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *
reply_status |
duke@1: * no | duke@1: *no | duke@1: *yes | duke@1: *yes | duke@1: *yes |
forward_reference |
duke@1: * no | duke@1: *no | duke@1: *no | duke@1: *no | duke@1: *yes2 duke@1: * |
get_slot |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
get_request_service_context |
duke@1: * yes | duke@1: *no | duke@1: *yes | duke@1: *yes | duke@1: *yes |
get_reply_service_context |
duke@1: * no | duke@1: *no | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *
ClientRequestInfo-specific: | duke@1: *|||||
target |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
effective_target |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *
effective_profile |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
received_exception |
duke@1: * no | duke@1: *no | duke@1: *no | duke@1: *yes | duke@1: *no |
received_exception_id |
duke@1: * no | duke@1: *no | duke@1: *no | duke@1: *yes | duke@1: *no |
get_effective_component |
duke@1: * yes | duke@1: *no | duke@1: *yes | duke@1: *yes | duke@1: *yes |
get_effective_components |
duke@1: * yes | duke@1: *no | duke@1: *yes | duke@1: *yes | duke@1: *yes |
get_request_policy |
duke@1: * yes | duke@1: *no | duke@1: *yes | duke@1: *yes | duke@1: *yes |
add_request_service_context |
duke@1: * yes | duke@1: *no | duke@1: *no | duke@1: *no | duke@1: *no |
ClientRequestInfo
is passed to
duke@1: * send_request
, there is an entry in the list for every
duke@1: * argument, whether in, inout, or out. But only the in and inout
duke@1: * arguments will be available.reply_status
atribute is not
duke@1: * LOCATION_FORWARD
, accessing this attribute will
duke@1: * throw BAD_INV_ORDER
with a standard minor code of
duke@1: * 14.reply_status
is LOCATION_FORWARD
,
duke@1: * then on subsequent requests, effective_target
will
duke@1: * contain the forwarded IOR while target will remain unchanged.
duke@1: *
duke@1: * @see #target
duke@1: */
duke@1: readonly attribute Object effective_target;
duke@1:
duke@1: /**
duke@1: * Returns the profile that will be used to send the request. If a
duke@1: * location forward has occurred for this operation's object and
duke@1: * that object's profile changed accordingly, then this profile will
duke@1: * be that located profile.
duke@1: */
duke@1: readonly attribute IOP::TaggedProfile effective_profile;
duke@1:
duke@1: /**
duke@1: * Returns an any which contains the exception to be returned to
duke@1: * the client.
duke@1: *
duke@1: * If the exception is a user exception which cannot be inserted
duke@1: * into an any (e.g., it is unknown or the bindings don t provide
duke@1: * the TypeCode
), then this attribute will be an any
duke@1: * containing the system exception UNKNOWN
with a
duke@1: * standard minor code of 1. However, the repository id of
duke@1: * the exception is available in the received_exception_id
duke@1: * attribute.
duke@1: *
duke@1: * @see #received_exception_id
duke@1: */
duke@1: readonly attribute any received_exception;
duke@1:
duke@1: /**
duke@1: * Returns the repository id of the exception to be returned to
duke@1: * the client.
duke@1: *
duke@1: * @see #received_exception
duke@1: * @see
duke@1: * PortableInterceptor
package comments for
duke@1: * limitations / unimplemented features
duke@1: */
duke@1: readonly attribute CORBA::RepositoryId received_exception_id;
duke@1:
duke@1: /**
duke@1: * Returns the IOP.TaggedComponent
with the given ID from
duke@1: * the profile selected for this request.
duke@1: *
duke@1: * If there is more than one component for a given component ID, it
duke@1: * is undefined which component this operation returns. If there is
duke@1: * more than one component for a given component ID,
duke@1: * get_effective_components
should be called instead.
duke@1: *
duke@1: * @param id The component id of the component which
duke@1: * is to be returned.
duke@1: * @return The IOP.TaggedComponent
obtained with the
duke@1: * given identifier.
duke@1: * @exception BAD_PARAM thrown, with a standard minor code of 28, if
duke@1: * no component exists for the given component ID.
duke@1: * @see #get_effective_components
duke@1: */
duke@1: IOP::TaggedComponent get_effective_component
duke@1: (in IOP::ComponentId id);
duke@1:
duke@1: /**
duke@1: * Returns an array of all tagged components with the given ID from the
duke@1: * profile selected for this request.
duke@1: *
duke@1: * @param id The component id of the components which are to be returned.
duke@1: * @return An array of TaggedComponent
objects, each of
duke@1: * which contains the given identifier.
duke@1: * @exception BAD_PARAM thrown, with a standard minor code of 28, if
duke@1: * no component exists for the given component ID.
duke@1: * @see #get_effective_component
duke@1: */
duke@1: IOP::TaggedComponentSeq get_effective_components
duke@1: (in IOP::ComponentId id);
duke@1:
duke@1: /**
duke@1: * Returns the given policy in effect for this operation.
duke@1: *
duke@1: * @exception INV_POLICY thrown, with a standard minor code of 1, if the
duke@1: * policy type is not valid either because the specified type is
duke@1: * not supported by this ORB or because a policy object of that type
duke@1: * is not associated with this Object
duke@1: * @param type The policy type which specifies the policy to be
duke@1: * returned.
duke@1: * @return The CORBA.Policy
obtained with the given type.
duke@1: * @see
duke@1: * PortableInterceptor
package comments for
duke@1: * limitations / unimplemented features
duke@1: */
duke@1: CORBA::Policy get_request_policy
duke@1: (in CORBA::PolicyType type);
duke@1:
duke@1: /**
duke@1: * Allows Interceptors to add service contexts to the request.
duke@1: *
duke@1: * There is no declaration of the order of the service contexts.
duke@1: * They may or may not appear in the order that they are added.
duke@1: *
duke@1: * @param service_context The IOP.ServiceContext
to be
duke@1: * added to the request.
duke@1: * @param replace Indicates the behavior of this operation when a
duke@1: * service context already exists with the given ID. If false,
duke@1: * then BAD_INV_ORDER
with a standard minor code of 15
duke@1: * is thrown. If true, then the existing service context is
duke@1: * replaced by the new one.
duke@1: */
duke@1: void add_request_service_context (
duke@1: in IOP::ServiceContext service_context,
duke@1: in boolean replace);
duke@1: };
duke@1:
duke@1: // Should be type string
duke@1: typedef string ServerId ;
duke@1:
duke@1: // This should actually be the CORBA::ORBid type once that is available
duke@1: typedef string ORBId ;
duke@1:
duke@1: /** The name of an object adapter. This is unique only within
duke@1: * the scope of the ORB that created the object adapter.
duke@1: */
duke@1: typedef org::omg::CORBA::StringSeq AdapterName ;
duke@1:
duke@1: /** Type of an object id. This provides the identity of a particular
duke@1: * object that was created by an object adapter.
duke@1: */
duke@1: typedef org::omg::CORBA::OctetSeq ObjectId ;
duke@1:
duke@1: /**
duke@1: * Request Information, accessible to server-side request interceptors.
duke@1: *
duke@1: * Some attributes and operations on ServerRequestInfo
are not
duke@1: * valid at all interception points. The following table shows the validity
duke@1: * of each attribute or operation. If it is not valid, attempting to access
duke@1: * it will result in a BAD_INV_ORDER
being thrown with a
duke@1: * standard minor code of 14.
duke@1: *
duke@1: * duke@1: * duke@1: *
duke@1: * | receive_request_ service_contexts |
duke@1: * receive_request | duke@1: *send_reply | duke@1: *send_exception | duke@1: *send_other | duke@1: *
---|---|---|---|---|---|
Inherited from RequestInfo: | duke@1: *|||||
request_id |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
operation |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
arguments |
duke@1: * no | duke@1: *yes1 | duke@1: *yes | duke@1: *no2 | duke@1: *no2 duke@1: * |
exceptions |
duke@1: * no | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
contexts |
duke@1: * no | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
operation_context |
duke@1: * no | duke@1: *yes | duke@1: *yes | duke@1: *no | duke@1: *no | duke@1: *
result |
duke@1: * no | duke@1: *no | duke@1: *yes | duke@1: *no | duke@1: *no | duke@1: *
response_expected |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
sync_scope |
duke@1: * yes | duke@1: *yes | duke@1: *yes | duke@1: *yes | duke@1: *yes |
request_id | duke@1: *yes | yes | yes | yes | yes |
operation | duke@1: *yes | yes | yes | yes | yes |
arguments | duke@1: *no | yes1 duke@1: * | yes | no2 | duke@1: *no2 duke@1: * |
exceptions | duke@1: *no | yes | yes | yes | yes |
contexts | duke@1: *no | yes | yes | yes | yes |
operation_context | duke@1: *no | yes | yes | no | no |
result | duke@1: *no | no | yes | no | no |
response_expected | duke@1: *yes | yes | yes | yes | yes |
sync_scope | duke@1: *yes | yes | yes | yes | yes |
reply_status | duke@1: *no | no | yes | yes | yes |
forward_reference | duke@1: *no | no | no | no | yes2 duke@1: * |
get_slot | duke@1: *yes | yes | yes | yes | yes |
get_request_service_context | duke@1: *yes | no | yes | yes | yes |
get_reply_service_context | duke@1: *no | no | yes | yes | yes |
ServerRequestInfo-specific: | duke@1: *|||||
sending_exception | duke@1: *no | no | no | yes | no |
object_id | duke@1: *no | yes | yes | yes3 | duke@1: *yes3 duke@1: * |
adapter_id | duke@1: *no | yes | yes | yes3 | duke@1: *yes3 duke@1: * |
server_id | duke@1: *no | yes | yes | yes | yes |
orb_id | duke@1: *no | yes | yes | yes | yes |
adapter_name | duke@1: *no | yes | yes | yes | yes |
target_most_derived_interface | duke@1: *no | yes | no4 | duke@1: *no4 | duke@1: *no4 duke@1: * |
get_server_policy | duke@1: *yes | yes | yes | yes | yes |
set_slot | duke@1: *yes | yes | yes | yes | yes |
target_is_a | duke@1: *no | yes | no4 | duke@1: *no4 | duke@1: *no4 duke@1: * |
add_reply_service_context | duke@1: *yes | yes | yes | yes | yes |
ServerRequestInfo
is passed to
duke@1: * receive_request
, there is an entry in the list for
duke@1: * every argument, whether in, inout, or out. But only the in and
duke@1: * inout arguments will be available.reply_status
attribute is not
duke@1: * LOCATION_FORWARD
, accessing this attribute will throw
duke@1: * BAD_INV_ORDER
with a standard minor code of 14.NO_RESOURCES
with a standard minor
duke@1: * code of 1 will be thrown if it is not available.ServantLocator
, then the ORB invokes the interception
duke@1: * point after it calls ServantLocator.postinvoke()
duke@1: * If the exception is a user exception which cannot be inserted into
duke@1: * an any (e.g., it is unknown or the bindings don't provide the
duke@1: * TypeCode
), then this attribute will be an any
duke@1: * containing the system exception UNKNOWN
with a
duke@1: * standard minor code of 1.
duke@1: *
duke@1: * @see
duke@1: * PortableInterceptor
package comments for
duke@1: * limitations / unimplemented features
duke@1: */
duke@1: readonly attribute any sending_exception;
duke@1:
duke@1: /**
duke@1: * Returns the opaque object_id
describing the target of
duke@1: * the operation invocation.
duke@1: */
duke@1: readonly attribute ObjectId object_id;
duke@1:
duke@1: /**
duke@1: * Returns the opaque identifier for the object adapter.
duke@1: */
duke@1: readonly attribute CORBA::OctetSeq adapter_id;
duke@1:
duke@1: /**
duke@1: * Returns the server ID that was specified on ORB::init using the -ORBServerId
duke@1: * argument.
duke@1: */
duke@1: readonly attribute ServerId server_id ;
duke@1:
duke@1: /**
duke@1: * Returns the ID that was used to create the ORB.
duke@1: */
duke@1: readonly attribute ORBId orb_id ;
duke@1:
duke@1: /**
duke@1: * Returns the sequence of strings that identifies the object
duke@1: * adapter instance that is handling this request.
duke@1: */
duke@1: readonly attribute AdapterName adapter_name ;
duke@1:
duke@1: /**
duke@1: * Returns the repository id for the most derived interface of the
duke@1: * servant.
duke@1: */
duke@1: readonly attribute CORBA::RepositoryId
duke@1: target_most_derived_interface;
duke@1:
duke@1: /**
duke@1: * Returns the policy in effect for this operation for the given
duke@1: * policy type. The returned CORBA.Policy
object shall
duke@1: * only be a policy whose type was registered via
duke@1: * register_policy_factory
.
duke@1: *
duke@1: * @param type The CORBA.PolicyType
which specifies the
duke@1: * policy to be returned.
duke@1: * @return The CORBA.Policy
obtained with the given
duke@1: * policy type.
duke@1: * @exception INV_POLICY thrown, with a standard minor code of 2, if
duke@1: * a policy for the given type was not registered via
duke@1: * register_policy_factory
.
duke@1: * @see ORBInitInfo#register_policy_factory
duke@1: */
duke@1: CORBA::Policy get_server_policy
duke@1: (in CORBA::PolicyType type);
duke@1:
duke@1: /**
duke@1: * Allows an Interceptor to set a slot in the
duke@1: * PortableInterceptor.Current
that is in the scope of
duke@1: * the request. If data already exists in that slot, it will be
duke@1: * overwritten.
duke@1: *
duke@1: * @param id The id of the slot.
duke@1: * @param data The data, in the form of an any, to store in that slot.
duke@1: * @exception InvalidSlot thrown if the ID does not define an allocated
duke@1: * slot.
duke@1: * @see Current
duke@1: */
duke@1: void set_slot (in SlotId id, in any data) raises (InvalidSlot);
duke@1:
duke@1: /**
duke@1: * Returns true if the servant is the given repository id,
duke@1: * false if it is not.
duke@1: *
duke@1: * @param id The caller wants to know if the servant is this
duke@1: * repository id.
duke@1: * @return Is the servant the given RepositoryId?
duke@1: */
duke@1: boolean target_is_a (in CORBA::RepositoryId id);
duke@1:
duke@1: /**
duke@1: * Allows Interceptors to add service contexts to the request.
duke@1: *
duke@1: * There is no declaration of the order of the service contexts.
duke@1: * They may or may not appear in the order that they are added.
duke@1: *
duke@1: * @param service_context The IOP.ServiceContext
to add to
duke@1: * the reply.
duke@1: * @param replace Indicates the behavior of this operation when a
duke@1: * service context already exists with the given ID. If false,
duke@1: * then BAD_INV_ORDER
with a standard minor code of 15
duke@1: * is thrown. If true, then the existing service context is
duke@1: * replaced by the new one.
duke@1: * @exception BAD_INV_ORDER thrown, with a standard minor code of 15, if
duke@1: * replace is false and a service context already exists with the
duke@1: * given ID.
duke@1: */
duke@1: void add_reply_service_context (
duke@1: in IOP::ServiceContext service_context,
duke@1: in boolean replace);
duke@1: };
duke@1:
duke@1: /**
duke@1: * Client-side request interceptor.
duke@1: *
duke@1: * A request Interceptor is designed to intercept the flow of a duke@1: * request/reply sequence through the ORB at specific points so that duke@1: * services can query the request information and manipulate the service duke@1: * contexts which are propagated between clients and servers. The primary duke@1: * use of request Interceptors is to enable ORB services to transfer duke@1: * context information between clients and servers. There are two types duke@1: * of request Interceptors: client-side and server-side. duke@1: *
duke@1: * To write a client-side Interceptor, implement the
duke@1: * ClientRequestInterceptor
interface.
duke@1: *
duke@1: * @see ClientRequestInfo
duke@1: */
duke@1: local interface ClientRequestInterceptor : Interceptor {
duke@1: /**
duke@1: * Allows an Interceptor to query request information and modify the
duke@1: * service context before the request is sent to the server.
duke@1: *
duke@1: * This interception point may throw a system exception. If it does,
duke@1: * no other Interceptors' send_request
operations are called.
duke@1: * Those Interceptors on the Flow Stack are popped and their
duke@1: * receive_exception
interception points are called. This
duke@1: * interception point may also throw a ForwardRequest
duke@1: * exception. If an Interceptor throws this exception, no other
duke@1: * Interceptors' send_request
operations are
duke@1: * called. Those Interceptors on the Flow Stack are popped and their
duke@1: * receive_other
interception points are called.
duke@1: *
duke@1: * Compliant Interceptors shall properly follow completion_status
duke@1: * semantics if they throw a system exception from this interception
duke@1: * point. The completion_status
shall be
duke@1: * COMPLETED_NO
.
duke@1: *
duke@1: * @param ri Information about the current request being intercepted.
duke@1: * @exception ForwardRequest If thrown, indicates to the ORB that a
duke@1: * retry of the request should occur with the new object given in
duke@1: * the exception.
duke@1: */
duke@1: void send_request (in ClientRequestInfo ri) raises (ForwardRequest);
duke@1:
duke@1: /**
duke@1: * Allows an Interceptor to query information during a Time-Independent
duke@1: * Invocation (TII) polling get reply sequence.
duke@1: *
duke@1: * With TII, an application may poll for a response to a request sent
duke@1: * previously by the polling client or some other client. This poll is
duke@1: * reported to Interceptors through the send_poll
duke@1: * interception point and the response is returned through the
duke@1: * receive_reply
or receive_exception
duke@1: * interception points. If the response is not available before the
duke@1: * poll time-out expires, the system exception TIMEOUT
is
duke@1: * thrown and receive_exception
is called with this
duke@1: * exception.
duke@1: *
duke@1: * This interception point may throw a system exception. If it does,
duke@1: * no other Interceptors' send_poll
operations are
duke@1: * called. Those Interceptors on the Flow Stack are popped and their
duke@1: * receive_exception
interception points are called.
duke@1: *
duke@1: * Compliant Interceptors shall properly follow
duke@1: * completion_status
semantics if they throw a system
duke@1: * exception from this interception point. The completion_status shall be
duke@1: * COMPLETED_NO
.
duke@1: *
duke@1: * @param ri Information about the current request being intercepted.
duke@1: * @exception TIMEOUT thrown if the response is not available before
duke@1: * the poll time-out expires
duke@1: */
duke@1: void send_poll (in ClientRequestInfo ri);
duke@1:
duke@1: /**
duke@1: * Allows an Interceptor to query the information on a reply after it
duke@1: * is returned from the server and before control is returned to the
duke@1: * client.
duke@1: *
duke@1: * This interception point may throw a system exception. If it does,
duke@1: * no other Interceptors' receive_reply
operations are
duke@1: * called. The remaining Interceptors in the Flow Stack shall have
duke@1: * their receive_exception
interception point called.
duke@1: *
duke@1: * Compliant Interceptors shall properly follow
duke@1: * completion_status
semantics if they throw a system
duke@1: * exception from this interception point. The
duke@1: * completion_status
shall be COMPLETED_YES
.
duke@1: *
duke@1: * @param ri Information about the current request being intercepted.
duke@1: */
duke@1: void receive_reply (in ClientRequestInfo ri);
duke@1:
duke@1: /**
duke@1: * Indicates to the interceptor that an exception occurred. Allows
duke@1: * an Interceptor to query the exception's information before it is
duke@1: * thrown to the client.
duke@1: *
duke@1: * This interception point may throw a system exception. This has the
duke@1: * effect of changing the exception which successive Interceptors
duke@1: * popped from the Flow Stack receive on their calls to
duke@1: * receive_exception
. The exception thrown to the client
duke@1: * will be the last exception thrown by an Interceptor, or the original
duke@1: * exception if no Interceptor changes the exception.
duke@1: *
duke@1: * This interception point may also throw a ForwardRequest
duke@1: * exception. If an Interceptor throws this exception, no other
duke@1: * Interceptors' receive_exception
operations are called.
duke@1: * The remaining Interceptors in the Flow Stack are popped and have their
duke@1: * receive_other
interception point called.
duke@1: *
duke@1: * If the completion_status
of the exception is not
duke@1: * COMPLETED_NO
, then it is inappropriate for this
duke@1: * interception point to throw a ForwardRequest
exception.
duke@1: * The request s at-most-once semantics would be lost.
duke@1: *
duke@1: * Compliant Interceptors shall properly follow
duke@1: * completion_status
semantics if they throw a system
duke@1: * exception from this interception point. If the original exception is
duke@1: * a system exception, the completion_status
of the new
duke@1: * exception shall be the same as on the original. If the original
duke@1: * exception is a user exception, then the completion_status
duke@1: * of the new exception shall be COMPLETED_YES
.
duke@1: *
duke@1: * Under some conditions, depending on what policies are in effect, an
duke@1: * exception (such as COMM_FAILURE
) may result in a retry
duke@1: * of the request. While this retry is a new request with respect to
duke@1: * Interceptors, there is one point of correlation between the original
duke@1: * request and the retry: because control has not returned to the
duke@1: * client, the PortableInterceptor.Current
for both the
duke@1: * original request and the retrying request is the same.
duke@1: *
duke@1: * @param ri Information about the current request being intercepted.
duke@1: * @exception ForwardRequest If thrown, indicates to the ORB that a
duke@1: * retry of the request should occur with the new object given in
duke@1: * the exception.
duke@1: */
duke@1: void receive_exception (in ClientRequestInfo ri) raises (ForwardRequest);
duke@1:
duke@1: /**
duke@1: * Allows an Interceptor to query the information available when a
duke@1: * request results in something other than a normal reply or an
duke@1: * exception. For example, a request could result in a retry
duke@1: * (e.g., a GIOP Reply with a LOCATION_FORWARD
status was
duke@1: * received); or on asynchronous calls, the reply does not immediately
duke@1: * follow the request, but control shall return to the client and an
duke@1: * ending interception point shall be called.
duke@1: *
duke@1: * For retries, depending on the policies in effect, a new request may or
duke@1: * may not follow when a retry has been indicated. If a new request does
duke@1: * follow, while this request is a new request, with respect to
duke@1: * Interceptors, there is one point of correlation between the original
duke@1: * request and the retry: because control has not returned to the client,
duke@1: * the request scoped PortableInterceptor.Current
for both
duke@1: * the original request and the retrying request is the same.
duke@1: *
duke@1: * This interception point may throw a system exception. If it does, no
duke@1: * other Interceptors' receive_other
operations are called.
duke@1: * The remaining Interceptors in the Flow Stack are popped and have
duke@1: * their receive_exception
interception point called.
duke@1: *
duke@1: * This interception point may also throw a ForwardRequest
duke@1: * exception. If an Interceptor throws this exception, successive
duke@1: * Interceptors' receive_other
operations are called with
duke@1: * the new information provided by the ForwardRequest
duke@1: * exception.
duke@1: *
duke@1: * Compliant Interceptors shall properly follow
duke@1: * completion_status
semantics if they throw a system
duke@1: * exception from this interception point. The
duke@1: * completion_status
shall be COMPLETED_NO
.
duke@1: * If the target invocation had completed, this interception point
duke@1: * would not be called.
duke@1: *
duke@1: * @param ri Information about the current request being intercepted.
duke@1: * @exception ForwardRequest If thrown, indicates to the ORB that a
duke@1: * retry of the request should occur with the new object given in
duke@1: * the exception.
duke@1: */
duke@1: void receive_other (in ClientRequestInfo ri) raises (ForwardRequest);
duke@1: };
duke@1:
duke@1: /**
duke@1: * Server-side request interceptor.
duke@1: *
duke@1: * A request Interceptor is designed to intercept the flow of a duke@1: * request/reply sequence through the ORB at specific points so that duke@1: * services can query the request information and manipulate the service duke@1: * contexts which are propagated between clients and servers. The primary duke@1: * use of request Interceptors is to enable ORB services to transfer duke@1: * context information between clients and servers. There are two types duke@1: * of request Interceptors: client-side and server-side. duke@1: *
duke@1: * To write a server-side Interceptor, implement the duke@1: * ServerRequestInterceptor interface. duke@1: * duke@1: * @see ServerRequestInfo duke@1: */ duke@1: local interface ServerRequestInterceptor : Interceptor { duke@1: /** duke@1: * Allows the interceptor to process service context information. duke@1: *
duke@1: * At this interception point, Interceptors must get their service
duke@1: * context information from the incoming request transfer it to
duke@1: * PortableInterceptor.Current
's slots.
duke@1: *
duke@1: * This interception point is called before the servant manager is called. duke@1: * Operation parameters are not yet available at this point. This duke@1: * interception point may or may not execute in the same thread as duke@1: * the target invocation. duke@1: *
duke@1: * This interception point may throw a system exception. If it does,
duke@1: * no other Interceptors' receive_request_service_contexts
duke@1: * operations are called. Those Interceptors on the Flow Stack are
duke@1: * popped and their send_exception
interception points are
duke@1: * called.
duke@1: *
duke@1: * This interception point may also throw a ForwardRequest
duke@1: * exception. If an Interceptor throws this exception, no other
duke@1: * Interceptors' receive_request_service_contexts
operations
duke@1: * are called. Those Interceptors on the Flow Stack are popped and
duke@1: * their send_other
interception points are called.
duke@1: *
duke@1: * Compliant Interceptors shall properly follow
duke@1: * completion_status
semantics if they throw a system
duke@1: * exception from this interception point. The
duke@1: * completion_status
shall be COMPLETED_NO.
duke@1: *
duke@1: * @param ri Information about the current request being intercepted.
duke@1: * @exception ForwardRequest If thrown, indicates to the ORB that a
duke@1: * retry of the request should occur with the new object given in
duke@1: * the exception.
duke@1: */
duke@1: void receive_request_service_contexts (in ServerRequestInfo ri)
duke@1: raises (ForwardRequest);
duke@1:
duke@1: /**
duke@1: * Allows an Interceptor to query request information after all the
duke@1: * information, including operation parameters, are available. This
duke@1: * interception point shall execute in the same thread as the target
duke@1: * invocation.
duke@1: *
duke@1: * In the DSI model, since the parameters are first available when
duke@1: * the user code calls arguments
, receive_request
duke@1: * is called from within arguments
. It is possible that
duke@1: * arguments
is not called in the DSI model. The target
duke@1: * may call set_exception
before calling
duke@1: * arguments
. The ORB shall guarantee that
duke@1: * receive_request
is called once, either through
duke@1: * arguments
or through set_exception
. If it
duke@1: * is called through set_exception
, requesting the
duke@1: * arguments will result in NO_RESOURCES
being thrown with
duke@1: * a standard minor code of 1.
duke@1: *
duke@1: * This interception point may throw a system exception. If it does, no
duke@1: * other Interceptors' receive_request
operations are
duke@1: * called. Those Interceptors on the Flow Stack are popped and their
duke@1: * send_exception
interception points are called.
duke@1: *
duke@1: * This interception point may also throw a ForwardRequest
duke@1: * exception. If an Interceptor throws this exception, no other
duke@1: * Interceptors' receive_request
operations are called.
duke@1: * Those Interceptors on the Flow Stack are popped and their
duke@1: * send_other
interception points are called.
duke@1: *
duke@1: * Compliant Interceptors shall properly follow
duke@1: * completion_status
semantics if they throw a system
duke@1: * exception from this interception point. The
duke@1: * completion_status
shall be COMPLETED_NO
.
duke@1: *
duke@1: * @param ri Information about the current request being intercepted.
duke@1: * @exception ForwardRequest If thrown, indicates to the ORB that a
duke@1: * retry of the request should occur with the new object given in
duke@1: * the exception.
duke@1: */
duke@1: void receive_request (in ServerRequestInfo ri) raises (ForwardRequest);
duke@1:
duke@1: /**
duke@1: * Allows an Interceptor to query reply information and modify the
duke@1: * reply service context after the target operation has been invoked
duke@1: * and before the reply is returned to the client. This interception
duke@1: * point shall execute in the same thread as the target invocation.
duke@1: *
duke@1: * This interception point may throw a system exception. If it does,
duke@1: * no other Interceptors' send_reply
operations are called.
duke@1: * The remaining Interceptors in the Flow Stack shall have their
duke@1: * send_exception
interception point called.
duke@1: *
duke@1: * Compliant Interceptors shall properly follow
duke@1: * completion_status
semantics if they throw a
duke@1: * system exception from this interception point. The
duke@1: * completion_status
shall be COMPLETED_YES
.
duke@1: *
duke@1: * @param ri Information about the current request being intercepted.
duke@1: */
duke@1: void send_reply (in ServerRequestInfo ri);
duke@1:
duke@1: /**
duke@1: * Allows an Interceptor to query the exception information and modify
duke@1: * the reply service context before the exception is thrown to the client.
duke@1: * When an exception occurs, this interception point is called. This
duke@1: * interception point shall execute in the same thread as the target
duke@1: * invocation.
duke@1: *
duke@1: * This interception point may throw a system exception. This has the
duke@1: * effect of changing the exception which successive Interceptors
duke@1: * popped from the Flow Stack receive on their calls to
duke@1: * send_exception
. The exception thrown to the client will
duke@1: * be the last exception thrown by an Interceptor, or the original
duke@1: * exception if no Interceptor changes the exception.
duke@1: *
duke@1: * This interception point may also throw a ForwardRequest
duke@1: * exception. If an Interceptor throws this exception, no other
duke@1: * Interceptors' send_exception
operations are called. The
duke@1: * remaining Interceptors in the Flow Stack shall have their
duke@1: * send_other
interception points called.
duke@1: *
duke@1: * If the completion_status
of the exception is not
duke@1: * COMPLETED_NO
, then it is inappropriate for this
duke@1: * interception point to throw a ForwardRequest
exception.
duke@1: * The request's at-most-once semantics would be lost.
duke@1: *
duke@1: * Compliant Interceptors shall properly follow
duke@1: * completion_status
semantics if they throw a system
duke@1: * exception from this interception point. If the original exception
duke@1: * is a system exception, the completion_status
of the new
duke@1: * exception shall be the same as on the original. If the original
duke@1: * exception is a user exception, then the completion_status
duke@1: * of the new exception shall be COMPLETED_YES
.
duke@1: *
duke@1: * @param ri Information about the current request being intercepted.
duke@1: * @exception ForwardRequest If thrown, indicates to the ORB that a
duke@1: * retry of the request should occur with the new object given in
duke@1: * the exception.
duke@1: */
duke@1: void send_exception (in ServerRequestInfo ri) raises (ForwardRequest);
duke@1:
duke@1: /**
duke@1: * Allows an Interceptor to query the information available when a
duke@1: * request results in something other than a normal reply or an
duke@1: * exception. For example, a request could result in a retry
duke@1: * (e.g., a GIOP Reply with a LOCATION_FORWARD
status was
duke@1: * received). This interception point shall execute in the same thread
duke@1: * as the target invocation.
duke@1: *
duke@1: * This interception point may throw a system exception. If it does,
duke@1: * no other Interceptors' send_other
operations are called.
duke@1: * The remaining Interceptors in the Flow Stack shall have their
duke@1: * send_exception
interception points called.
duke@1: *
duke@1: * This interception point may also throw a ForwardRequest
duke@1: * exception. If an Interceptor throws this exception, successive
duke@1: * Interceptors' send_other
operations are called with
duke@1: * the new information provided by the ForwardRequest
duke@1: * exception.
duke@1: *
duke@1: * Compliant Interceptors shall properly follow
duke@1: *
duke@1: * If a policy for the given type is not known to the ORB, then this
duke@1: * operation will throw
duke@1: * Any number of components may exist with the same component ID.
duke@1: *
duke@1: * @param a_component The IOP.TaggedComponent to add.
duke@1: */
duke@1: void add_ior_component
duke@1: (in IOP::TaggedComponent tagged_component);
duke@1:
duke@1: /**
duke@1: * A portable ORB service implementation calls
duke@1: *
duke@1: * Any number of components may exist with the same component ID.
duke@1: *
duke@1: * @param a_component The
duke@1: * In some cases, a portable ORB service implementation may need to add
duke@1: * information describing the server's or object's ORB service related
duke@1: * capabilities to object references in order to enable the ORB service
duke@1: * implementation in the client to function properly.
duke@1: *
duke@1: * This is supported through the
duke@1: * An implementation of
duke@1: * Any exception thrown from this method is handled by the Object
duke@1: * Adapter that called this interceptor. In the case of the POA,
duke@1: * an exception results in a OBJ_ADAPTER exception with an OMG
duke@1: * standard minor code of 6.
duke@1: * @param info The IORInfo for the object adapter being created.
duke@1: */
duke@1: void components_established( in IORInfo info ) ;
duke@1:
duke@1: /** Called whenever the state of an adapter manager changes.
duke@1: * For the POA, that is the POAManager. If the state change
duke@1: * is reported through
duke@1: * A portable ORB service implementation registers an instance of the
duke@1: *
duke@1: * The ORB calls
duke@1: * The
duke@1: * An Interceptor may be anonymous, i.e., have an empty string as the
duke@1: * name attribute. Any number of anonymous Interceptors may be
duke@1: * registered with the ORB so, if the Interceptor being registered
duke@1: * is anonymous, the registration operation will not throw
duke@1: *
duke@1: * This operation is only valid during post_init.
duke@1: */
duke@1: Object resolve_initial_references (in ObjectId id) raises (InvalidName);
duke@1:
duke@1: /**
duke@1: * Used to add a client-side request Interceptor to the list of
duke@1: * client-side request Interceptors.
duke@1: *
duke@1: * @param interceptor The
duke@1: * Note that while slot id's can be allocated within an ORB initializer,
duke@1: * the slots themselves cannot be initialized.
duke@1: *
duke@1: * @return The index to the slot which has been allocated.
duke@1: * @exception BAD_INV_ORDER thrown, with a standard minor code of 14, if
duke@1: *
duke@1: * Interceptors are intended to be a means by which ORB services gain
duke@1: * access to ORB processing, effectively becoming part of the ORB.
duke@1: * Since Interceptors are part of the ORB, when
duke@1: * An Interceptor is registered by registering an associated
duke@1: *
duke@1: * Registering ORB Initializers in Java
duke@1: *
duke@1: * ORBInitializers are registered via Java ORB properties.
duke@1: *
duke@1: * The property names are of the form:
duke@1: *
duke@1: * Example
duke@1: *
duke@1: * A client-side logging service written by company X, for example, may
duke@1: * have the following ORBInitializer implementation:
duke@1: *
duke@1: * Notes about Registering Interceptors
duke@1: *
duke@1: * Request Interceptors are registered on a per-ORB basis.
duke@1: *
duke@1: * To achieve virtual per-object Interceptors, query the policies on the
duke@1: * target from within the interception points to determine whether they
duke@1: * should do any work.
duke@1: *
duke@1: * To achieve virtual per-POA Interceptors, instantiate each POA with a
duke@1: * different ORB. While Interceptors may be ordered administratively,
duke@1: * there is no concept of order with respect to the registration of
duke@1: * Interceptors. Request Interceptors are concerned with service contexts.
duke@1: * Service contexts have no order, so there is no purpose for request
duke@1: * Interceptors to have an order. IOR Interceptors are concerned with
duke@1: * tagged components. Tagged components also have no order, so there
duke@1: * is no purpose for IOR Interceptors to have an order.
duke@1: *
duke@1: * Registration code should avoid using the ORB (i.e., calling
duke@1: *
duke@1: * Calling the completion_status
semantics if they throw a system
duke@1: * exception from this interception point. The
duke@1: * completion_status
shall be COMPLETED_NO
.
duke@1: *
duke@1: * @param ri Information about the current request being intercepted.
duke@1: * @exception ForwardRequest If thrown, indicates to the ORB that a
duke@1: * retry of the request should occur with the new object given in
duke@1: * the exception.
duke@1: */
duke@1: void send_other (in ServerRequestInfo ri) raises (ForwardRequest);
duke@1: };
duke@1:
duke@1: /** The object reference factory. This provides the capability of
duke@1: * creating an object reference.
duke@1: */
duke@1: abstract valuetype ObjectReferenceFactory {
duke@1: /** make_object creates a CORBA object reference according
duke@1: * to the data in this template, with the given repository ID and
duke@1: * object ID.
duke@1: */
duke@1: Object make_object( in string repositoryId, in ObjectId object_id ) ;
duke@1: } ;
duke@1:
duke@1: /** The object reference template. An instance of this must
duke@1: * exist for each object adapter created in an ORB. The server_id,
duke@1: * orb_id, and adapter_name attributes uniquely identify this template
duke@1: * within the scope of an IMR. Note that adapter_id is similarly unique
duke@1: * within the same scope, but it is opaque, and less useful in many
duke@1: * cases.
duke@1: */
duke@1: abstract valuetype ObjectReferenceTemplate : ObjectReferenceFactory {
duke@1:
duke@1: readonly attribute ServerId server_id ;
duke@1:
duke@1: readonly attribute ORBId orb_id ;
duke@1:
duke@1: readonly attribute AdapterName adapter_name ;
duke@1: } ;
duke@1:
duke@1: /** Sequence of object reference templates is used for reporting state
duke@1: * changes that do not occur on the adapter manager.
duke@1: */
duke@1: typedef sequenceIORInterceptor.establish_components
.
duke@1: *
duke@1: * @see IORInterceptor
duke@1: */
duke@1: local interface IORInfo {
duke@1:
duke@1: /**
duke@1: * Allows an ORB service implementation to determine what server side
duke@1: * policy of a particular type is in effect for an IOR being
duke@1: * constructed. When the IOR being constructed is for an object
duke@1: * implemented using a POA, all Policy objects passed to the
duke@1: * PortableServer.POA.create_POA
call that created that
duke@1: * POA are accessable via get_effective_policy
.
duke@1: * INV_POLICY
with a standard minor
duke@1: * code of 2.
duke@1: *
duke@1: * @param type an int specifying the type of policy to return.
duke@1: * @return The effective CORBA.Policy
object of the
duke@1: * requested type. If the given policy type is known, but no policy
duke@1: * of that type is in effect, then this operation will return a
duke@1: * nil object reference.
duke@1: */
duke@1: CORBA::Policy get_effective_policy
duke@1: (in CORBA::PolicyType type);
duke@1:
duke@1: /**
duke@1: * A portable ORB service implementation calls
duke@1: * add_ior_component
from its implementation of
duke@1: * establish_components
to add a tagged component to the
duke@1: * set which will be included when constructing IORs. The components in
duke@1: * this set will be included in all profiles.
duke@1: * add_ior_component_to_profile
from its implementation of
duke@1: * establish_components
to add a tagged component to the
duke@1: * set which will be included when constructing IORs. The components in
duke@1: * this set will be included in the specified profile.
duke@1: * IOP.TaggedComponent
to add.
duke@1: * @param profile_id The profile id of the profile to
duke@1: * which this component will be added.
duke@1: * @exception BAD_PARAM thrown, with a standard minor code of 29, if the
duke@1: * given profile ID does not define a known profile or it is
duke@1: * impossible to add components to that profile.
duke@1: */
duke@1: void add_ior_component_to_profile (
duke@1: in IOP::TaggedComponent tagged_component,
duke@1: in IOP::ProfileId profile_id);
duke@1:
duke@1: /** Return the adapter manager id of the object adapter
duke@1: * that was just created and is running IOR interceptors.
duke@1: */
duke@1: readonly attribute AdapterManagerId manager_id ;
duke@1:
duke@1: /** Return the adapter state of the object adapter
duke@1: * that was just created and is running IOR interceptors.
duke@1: */
duke@1: readonly attribute AdapterState state ;
duke@1:
duke@1: /** Return the object reference template of the object adapter
duke@1: * that was just created and is running IOR interceptors.
duke@1: */
duke@1: readonly attribute ObjectReferenceTemplate adapter_template ;
duke@1:
duke@1: /** On read, returns the current factory that will be used to create
duke@1: * object references for the object adapter that was just created
duke@1: * and is running IOR interceptors. By default, this factory is the same
duke@1: * as the value of the adapter_template attribute. The current_factory
duke@1: * may also be set to another object reference template inside an
duke@1: * IORInterceptor_3_0.
duke@1: */
duke@1: attribute ObjectReferenceFactory current_factory ;
duke@1: };
duke@1:
duke@1: /**
duke@1: * Interceptor used to establish tagged components in the profiles within
duke@1: * an IOR.
duke@1: * IORInterceptor
and
duke@1: * IORInfo
interfaces.
duke@1: *
duke@1: * @see IORInfo
duke@1: */
duke@1: local interface IORInterceptor : Interceptor {
duke@1: /**
duke@1: * A server side ORB calls the establish_components
duke@1: * operation on all registered IORInterceptor
instances
duke@1: * when it is assembling the list of components that will be included
duke@1: * in the profile or profiles of an object reference. This operation
duke@1: * is not necessarily called for each individual object reference.
duke@1: * In the case of the POA, this operation is called each time POA::create_POA
duke@1: * is called. In any case, establish_components
is
duke@1: * guaranteed to be called at least once for each distinct set of
duke@1: * server policies.
duke@1: * establish_components
must not
duke@1: * throw exceptions. If it does, the ORB shall ignore the exception
duke@1: * and proceed to call the next IOR Interceptor's
duke@1: * establish_components
operation.
duke@1: *
duke@1: * @param info The IORInfo
instance used by the ORB
duke@1: * service to query applicable policies and add components to be
duke@1: * included in the generated IORs.
duke@1: */
duke@1: void establish_components (in IORInfo info);
duke@1: };
duke@1:
duke@1: local interface IORInterceptor_3_0 : IORInterceptor {
duke@1: /** The components_established method is invoked on all registered
duke@1: * IORInterceptor_3_0 instances after establish_components
duke@1: * has been invoked on all registered IORInterceptor instances.
duke@1: * The adapter_template is available in info during this call.
duke@1: * The current_factory may be get or set in info during this call.
duke@1: * adapter_manager_state_changed
,
duke@1: * it is not reported through adapter_state_changed
.
duke@1: * @param id the adapter manager id of the adapter manager that
duke@1: * changed state
duke@1: * @param state the new state of the adapter manager
duke@1: */
duke@1: void adapter_manager_state_changed( in AdapterManagerId id,
duke@1: in AdapterState state ) ;
duke@1:
duke@1: /** Called whenever the state of an object adapter changes, and
duke@1: * the state change is not caused by an adapter manager. Such
duke@1: * changes are reported to all registered IORInterceptor_3_0
duke@1: * instances.
duke@1: * @param templates the sequence of ObjectReferenceTemplate
instances
duke@1: * on which this state change occurred.
duke@1: * @param state the new AdapterState
shared by all of the templates.
duke@1: */
duke@1: void adapter_state_changed( in ObjectReferenceTemplateSeq templates,
duke@1: in AdapterState state ) ;
duke@1: };
duke@1:
duke@1: /**
duke@1: * Enables policy types to be constructed using
duke@1: * CORBA.ORB.create_policy
.
duke@1: * PolicyFactory
interface during ORB initialization in order
duke@1: * to enable its policy types to be constructed using
duke@1: * CORBA.ORB.create_policy
. The POA is required to preserve
duke@1: * any policy which is registered with ORBInitInfo
in this
duke@1: * manner.
duke@1: *
duke@1: * @see ORBInitInfo#register_policy_factory
duke@1: */
duke@1: local interface PolicyFactory
duke@1: {
duke@1: /**
duke@1: * Returns an instance of the appropriate interface derived from
duke@1: * CORBA.Policy
whose value corresponds to the
duke@1: * specified any.
duke@1: * create_policy
on a registered
duke@1: * PolicyFactory
instance when
duke@1: * CORBA.ORB.create_policy
is called for the
duke@1: * PolicyType
under which the PolicyFactory
has
duke@1: * been registered. The create_policy
operation then
duke@1: * returns an instance of the appropriate interface derived from
duke@1: * CORBA.Policy
whose value corresponds to the specified
duke@1: * any. If it cannot, it shall throw an exception as described for
duke@1: * CORBA.ORB.create_policy
.
duke@1: *
duke@1: * @param type An int specifying the type of policy being created.
duke@1: * @param value An any containing data with which to construct the
duke@1: * CORBA.Policy
.
duke@1: * @return A CORBA.Policy
object of the specified type and
duke@1: * value.
duke@1: */
duke@1: CORBA::Policy create_policy
duke@1: (in CORBA::PolicyType type, in any value)
duke@1: raises (CORBA::PolicyError);
duke@1: };
duke@1:
duke@1: /**
duke@1: * Passed to each
ORBInitializer
, allowing it to
duke@1: * to register interceptors and perform other duties while the ORB is
duke@1: * initializing.
duke@1: * ORBInitInfo
object is only valid during
duke@1: * ORB.init
. If a service keeps a reference to its
duke@1: * ORBInitInfo
object and tries to use it after
duke@1: * ORB.init
returns, the object no longer exists and an
duke@1: * OBJECT_NOT_EXIST
exception shall be thrown.
duke@1: *
duke@1: * @see ORBInitializer
duke@1: */
duke@1: local interface ORBInitInfo {
duke@1:
duke@1: /** Object id, represented as a String */
duke@1: typedef string ObjectId;
duke@1:
duke@1: /**
duke@1: * Only one Interceptor of a given name can be registered with the
duke@1: * ORB for each Interceptor type. If an attempt is made to register a
duke@1: * second Interceptor with the same name, DuplicateName is thrown.
duke@1: * DuplicateName
.
duke@1: */
duke@1: exception DuplicateName {
duke@1: /**
duke@1: * The name for which there was already an interceptor registered.
duke@1: */
duke@1: string name;
duke@1: };
duke@1:
duke@1: /**
duke@1: * This exception is thrown by
duke@1: * register_initial_reference
and
duke@1: * resolve_initial_references
.
duke@1: * register_initial_reference
throws InvalidName
duke@1: * if:
duke@1: *
duke@1: *
duke@1: * resolve_initial_references
throws
duke@1: * InvalidName
if the name to be resolved is invalid.
duke@1: */
duke@1: exception InvalidName {};
duke@1:
duke@1: /**
duke@1: * Returns the arguments passed to ORB.init
. They may or
duke@1: * may not contain the ORB's arguments.
duke@1: */
duke@1: readonly attribute CORBA::StringSeq arguments;
duke@1:
duke@1: /**
duke@1: * Returns the ID of the ORB being initialized.
duke@1: */
duke@1: readonly attribute string orb_id;
duke@1:
duke@1: /**
duke@1: * Returns the IOP.CodecFactory
. The
duke@1: * CodecFactory
is normally obtained via a call to
duke@1: * ORB.resolve_initial_references( "CodecFactory" )
, but
duke@1: * since the ORB is not yet available and Interceptors, particularly when
duke@1: * processing service contexts, will require a Codec
, a
duke@1: * means of obtaining a Codec
is necessary during ORB
duke@1: * initialization.
duke@1: */
duke@1: readonly attribute IOP::CodecFactory codec_factory;
duke@1:
duke@1: /**
duke@1: * Identical to ORB.register_initial_reference
. This same
duke@1: * functionality exists here because the ORB, not yet fully initialized,
duke@1: * is not yet available but initial references may need to be
duke@1: * registered as part of Interceptor registration. The only difference
duke@1: * is that the version of this operation on the ORB uses PIDL
duke@1: * (CORBA.ORB.ObjectId
) and
duke@1: * (CORBA.ORB.InvalidName
) whereas the version in this
duke@1: * interface uses IDL defined in this interface; the semantics are
duke@1: * identical.
duke@1: */
duke@1: void register_initial_reference (in ObjectId id, in Object obj)
duke@1: raises (InvalidName);
duke@1:
duke@1: // This was incorrectly returning void in orbos/99-12-02, correction
duke@1: // from errata in orbos/00-01-01
duke@1: /**
duke@1: * Identical to ORB.resolve_initial_references
. This same
duke@1: * functionality exists here because the ORB, not yet fully initialized,
duke@1: * is not yet available but initial references may be required from the
duke@1: * ORB as part of Interceptor registration. The only difference is that
duke@1: * the version of this operation on the ORB uses PIDL
duke@1: * (CORBA::ORB::ObjectId
and
duke@1: * CORBA::ORB::InvalidName
) whereas the version in this
duke@1: * interface uses IDL defined in this interface; the semantics
duke@1: * are identical.
duke@1: * ClientRequestInterceptor
to be
duke@1: * added.
duke@1: * @exception DuplicateName thrown if a client-side request Interceptor
duke@1: * has already been registered with this Interceptor's name.
duke@1: */
duke@1: void add_client_request_interceptor
duke@1: (in ClientRequestInterceptor interceptor)
duke@1: raises (DuplicateName);
duke@1:
duke@1: /**
duke@1: * Used to add a server-side request Interceptor to the list of
duke@1: * server-side request Interceptors.
duke@1: *
duke@1: * @param interceptor The ServerRequestInterceptor to be added.
duke@1: * @exception DuplicateName thrown if a server-side request Interceptor
duke@1: * has already been registered with this Interceptor's name
duke@1: */
duke@1: void add_server_request_interceptor (
duke@1: in ServerRequestInterceptor interceptor)
duke@1: raises (DuplicateName);
duke@1:
duke@1: /**
duke@1: * Used to add an IOR Interceptor to the list of IOR Interceptors.
duke@1: *
duke@1: * @param interceptor The IORInterceptor to be added.
duke@1: * @exception DuplicateName thrown if an IOR Interceptor has already
duke@1: * been registered with this Interceptor's name.
duke@1: */
duke@1: void add_ior_interceptor (in IORInterceptor interceptor)
duke@1: raises (DuplicateName);
duke@1:
duke@1: /**
duke@1: * Called to allocate a slot on PortableInterceptor.Current
.
duke@1: * set_slot
or get_slot
is called on the
duke@1: * PICurrent
within an ORB initializer.
duke@1: * @see Current
duke@1: */
duke@1: SlotId allocate_slot_id ();
duke@1:
duke@1: /**
duke@1: * Registers a PolicyFactory
for the given
duke@1: * PolicyType
.
duke@1: *
duke@1: * @param type The policy type that the given PolicyFactory
duke@1: * serves.
duke@1: * @param policy_factory The factory for the given policy type.
duke@1: * @exception BAD_INV_ORDER thrown, with a standard minor code of 16, if
duke@1: * a PolicyFactory
already exists for the given
duke@1: * PolicyType
.
duke@1: */
duke@1: void register_policy_factory (
duke@1: in CORBA::PolicyType type,
duke@1: in PolicyFactory policy_factory);
duke@1: };
duke@1:
duke@1: /**
duke@1: * Facilitates interceptor registration and ORB initialization.
duke@1: * ORB.init
duke@1: * returns an ORB, the Interceptors shall have been registered.
duke@1: * Interceptors cannot be registered on an ORB after it has been
duke@1: * returned by a call to ORB.init
.
duke@1: * ORBInitializer
object which implements the
duke@1: * ORBInitializer
interface. When an ORB is initializing,
duke@1: * it shall call each registered ORBInitializer
, passing it
duke@1: * an ORBInitInfo
object which is used to register its
duke@1: * Interceptor.
duke@1: *
duke@1: * where
duke@1: * org.omg.PortableInterceptor.ORBInitializerClass.<Service>
duke@1: *
<Service>
is the string name of a class
duke@1: * which implements
duke@1: *
duke@1: * To avoid name collisions, the reverse DNS name convention should be
duke@1: * used. For example, if company X has three initializers, it could define
duke@1: * the following properties:
duke@1: *
duke@1: * org.omg.PortableInterceptor.ORBInitializer
duke@1: *
duke@1: *
duke@1: * During ORB.init, these ORB properties which begin with
duke@1: *
duke@1: * org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init1
duke@1: *
duke@1: * org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init2
duke@1: *
duke@1: * org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init3
duke@1: *
org.omg.PortableInterceptor.ORBInitializerClass
shall be
duke@1: * collected, the <Service>
portion of each property
duke@1: * shall be extracted, an object shall be instantiated with the
duke@1: * <Service>
string as its class name, and the
duke@1: * pre_init
and post_init
methods shall be
duke@1: * called on that object. If there are any exceptions, the ORB shall
duke@1: * ignore them and proceed.
duke@1: *
duke@1: * To run a program called
duke@1: * package com.x.logging;
duke@1: *
duke@1: * import org.omg.PortableInterceptor.Interceptor;
duke@1: * import org.omg.PortableInterceptor.ORBInitializer;
duke@1: * import org.omg.PortableInterceptor.ORBInitInfo;
duke@1: *
duke@1: * public class LoggingService implements ORBInitializer {
duke@1: * void pre_init( ORBInitInfo info ) {
duke@1: * // Instantiate the Logging Service s Interceptor.
duke@1: * Interceptor interceptor = new LoggingInterceptor();
duke@1: *
duke@1: * // Register the Logging Service s Interceptor.
duke@1: * info.add_client_request_interceptor( interceptor );
duke@1: * }
duke@1: *
duke@1: * void post_init( ORBInitInfo info ) {
duke@1: * // This service does not need two init points.
duke@1: * }
duke@1: * }
duke@1: *
MyApp
using this logging
duke@1: * service, the user could type:
duke@1: *
duke@1: *
duke@1: * java
duke@1: *-Dorg.omg.PortableInterceptor.ORBInitializerClass.com.x.Logging.LoggingService
duke@1: * MyApp
duke@1: *
ORB.init
with the provided orb_id
). Since
duke@1: * registration occurs during ORB initialization, results of invocations
duke@1: * on this ORB while it is in this state are undefined.
duke@1: *
duke@1: * @see ORBInitInfo
duke@1: */
duke@1: local interface ORBInitializer {
duke@1:
duke@1: /**
duke@1: * Called during ORB initialization. If it is expected that initial
duke@1: * services registered by an interceptor will be used by other
duke@1: * interceptors, then those initial services shall be registered at
duke@1: * this point via calls to
duke@1: * ORBInitInfo.register_initial_reference
.
duke@1: *
duke@1: * @param info provides initialization attributes and operations by
duke@1: * which Interceptors can be registered.
duke@1: */
duke@1: void pre_init (in ORBInitInfo info);
duke@1:
duke@1: /**
duke@1: * Called during ORB initialization. If a service must resolve initial
duke@1: * references as part of its initialization, it can assume that all
duke@1: * initial references will be available at this point.
duke@1: * post_init
operations is not the final
duke@1: * task of ORB initialization. The final task, following the
duke@1: * post_init
calls, is attaching the lists of registered
duke@1: * interceptors to the ORB. Therefore, the ORB does not contain the
duke@1: * interceptors during calls to post_init
. If an
duke@1: * ORB-mediated call is made from within post_init
, no
duke@1: * request interceptors will be invoked on that call.
duke@1: * Likewise, if an operation is performed which causes an IOR to be
duke@1: * created, no IOR interceptors will be invoked.
duke@1: *
duke@1: * @param info provides initialization attributes and
duke@1: * operations by which Interceptors can be registered.
duke@1: */
duke@1: void post_init (in ORBInitInfo info);
duke@1: };
duke@1: };