Using CORBA Request-Level Interceptors

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Request-Level Interceptor API

This chapter documents the following interfaces that you use to implement request-level interceptors:

Each of these interfaces is a locality-constrained object. Any attempt to pass a reference outside its locality (that is, its process), or any attempt to externalize an object supporting this interface using the CORBA ORB object_to_string operation, results in the CORBA MARSHAL system exception (CORBA::MARSHAL) being raised.

 


Interceptor Hierarchy

Request-level interceptors are divided into two interfaces, providing separate client- and target-side functionality. The following figure illustrates the inheritance hierarchy of the request-level interceptors supported in the Oracle Tuxedo product.

Note on Unused Interfaces

The method signatures for operations on classes derived from the RequestLevelInterceptor interface include parameters for the following interfaces:

These interfaces are not used in the Oracle Tuxedo product. However, they are defined in the Oracle Tuxedo product so that you do not need to recompile your CORBA application if an implementation of these interfaces is ever provided in a future release of the Oracle Tuxedo product. The ORB always passes a nil for the actual argument. You should not attempt to use this argument; doing so will likely end the process with a serious error.

 


Interceptors::Interceptor Interface

The Interceptors::Interceptor interface is defined as the base interface of all types of interceptors, including request-level interceptors. This interface contains the set of operations and attributes that are supported by all types of interceptors. The Interceptors::Interceptor interface is defined as an abstract interface; thus an instance of the interface cannot be instantiated.

Listing 8-1 OMG IDL for the Interceptors::Interceptor Interface
//File: Interceptors.idl
#ifndef _INTERCEPTORS_IDL
#define _INTERCEPTORS_IDL

#pragma prefix "beasys.com"

module Interceptors
  {
  native ExceptionValue;

  local Interceptor
    {
    readonly attribute string id; // identifier of interceptor

    // called by ORB when interceptor is being shutdown
    ShutdownReturnStatus shutdown(
                                   in ShutdownReason reason,
                                   out ExceptionValue excep_val
                                 );
    }; // locality constrained
  };
#endif /* _INTERCEPTORS_IDL */

The implementation of the operations _duplicate, _narrow, and _nil are inherited from the implementation of the CORBA::LocalBase interface provided by the CORBA ORB in the Oracle Tuxedo product.

Listing 8-2 C++ Declaration of the Interceptors::Interceptor Interface
#ifndef _INTERCEPTORS_H
#define _INTERCEPTORS_H

#include <string.h>
#include <CORBA.h>

class OBBEXPDLL Interceptors
  {
  public:
  class Interceptor;
  typedef Interceptor * Interceptor_ptr;

  enum InvokeReturnStatus
    {
    INVOKE_NO_EXCEPTION,// proceed normally
    REPLY_NO_EXCEPTION, // stop proceeding; start reply processing
    REPLY_EXCEPTION // stop proceeding; reply with exception
    };

  enum ResponseReturnStatus
    {
        RESPONSE_NO_EXCEPTION, // proceed normally
        RESPONSE_EXCEPTION
    };

  enum ShutdownReturnStatus
    {
    SHUTDOWN_NO_EXCEPTION,
    SHUTDOWN_EXCEPTION
    };

  enum ShutdownReason
    {
    ORB_SHUTDOWN,
    CONNECTION_ABORTED,
    RESOURCES_EXCEEDED
    };

  struct Version
    {
    CORBA::Octet major_version;
    CORBA::Octet minor_version;
    };
  typedef Version * Version_ptr;

  //+
  // Abstract base interface for all Interceptors
  //-
  class OBBEXPDLL Interceptor : public virtual CORBA::LocalBase
    {
    public:
      static Interceptor_ptr _duplicate(Interceptor_ptr obj);
      static Interceptor_ptr _narrow(Interceptor_ptr obj);
      static Interceptor_ptr _nil();
      virtual ShutdownReturnStatus
        shutdown( ShutdownReason reason,
                  CORBA::Exception_ptr & excep_val) = 0;
      virtual CORBA::String id() = 0;

    protected:
      Interceptor();
      virtual ~Interceptor();
    };
  };#endif /* _INTERCEPTORS_H */

 


Interceptor::id

Synopsis

Obtains the vendor assigned identity of the interceptor as a string value.

C++ Mapping

virtual CORBA::String id() = 0;

Parameters

None.

Exceptions

None.

Description

The id accessor operation is used by the ORB to obtain the vendor assigned identity of the interceptor as a string value. This attribute is used primarily for debugging and tracing of operations on the interceptors called by the ORB.

Return Values

This operation returns a pointer to a null-terminated string containing the identity of the interceptor as assigned by the provider of the interceptor implementation.

 


Interceptor::shutdown

Synopsis

Notifies an implementation of an interceptor that the interceptor is being shut down.

C++ Binding

virtual ShutdownReturnStatus 
shutdown( ShutdownReason reason,
CORBA::Exception_ptr & excep_val) = 0;

Parameters

reason

A ShutdownReason value that indicates the reason why the interceptor is being shut down. The following ShutdownReason values can be passed to the operation:

Status Value
Description
ORB_SHUTDOWN
Indicates that the ORB is being shut down.
RESOURCES_EXCEEDED
Indicates that resources of the process have been exhausted.
CONNECTION_ABORTED
This exception is not reported in Oracle Tuxedo 8.0.

excep_val

A reference to an ExceptionValue in which the operation is to store any exception raised. This parameter is valid only if a value of SHUTDOWN_EXCEPTION is returned from the operation. ExceptionValue is mapped to the class CORBA::Exception.

Exceptions

None.

Description

The shutdown operation is used by the ORB to notify an implementation of an interceptor that the interceptor is being shut down. The ORB destroys the instance of the interceptor once control is returned from the operation back to the ORB.

Return Values

SHUTDOWN_NO_EXCEPTION

Indicates that the operation has not raised an exception.

SHUTDOWN_EXCEPTION

Indicates that the operation has raised an exception. The value of the exception is stored in the excep_val parameter.

 


RequestLevelInterceptor::
RequestInterceptor Interface

The RequestLevelInterceptor::RequestInterceptor interface is the base interface of all request-level interceptors. It inherits directly from the Interceptors::Interceptor interface. The RequestLevelInterceptor::RequestInterceptor interface:

The local keyword in OMG IDL indicates that the RequestInterceptor interface is not a normal CORBA object, so it cannot be used as such.

Listing 8-3 OMG IDL for the RequestLevelInterceptor::RequestInterceptor Interface
#ifndef _REQUEST_LEVEL_INTERCEPTOR_IDL
#define _REQUEST_LEVEL_INTERCEPTOR_IDL

#include <orb.idl>
#include <Giop.idl>
#include <Interceptors.idl>

#pragma prefix “beasys.com”

module RequestLevelInterceptor
  {
  local RequestInterceptor : Interceptors::Interceptor
    {
    void exception_occurred(
                             in ReplyContext reply_context,
                             in ExceptionValue excep_val
                            );
    };
  };
#endif /* _REQUEST_LEVEL_INTERCEPTOR_IDL */

The implementation of the RequestInterceptor interface inherits from CORBA::LocalBase rather than from CORBA::Object. CORBA::LocalBase provides an implementation of the operations _duplicate, _narrow, and _nil, similar to those of CORBA::Object.

Listing 8-4 C++ Declaration for the RequestInterceptor Interface
#ifndef _RequestLevelInterceptor_h
#define _RequestLevelInterceptor_h

#include <CORBA.h>
#include <IOP.h>
#include <GIOP.h>
#include <Interceptors.h>

class OBBEXPDLL RequestLevelInterceptor
  {
  public:
    class RequestInterceptor;
    typedef RequestInterceptor * RequestInterceptor_ptr;

    struct RequestContext
      {
      Interceptors::Version struct_version;
      CORBA::ULong request_id;
      CORBA::Octet response_flags;
      GIOP::TargetAddress target;
      CORBA::String_var interface_id;
      CORBA::String_var operation;
      RequestContext &operator=(const RequestContext &_obj);
      };

    typedef RequestContext * RequestContext_ptr;
    typedef GIOP::ReplyStatusType_1_2 ReplyStatus;

    struct ReplyContext
     {
      Interceptors::Version struct_version;
      CORBA::ULong request_id;
      ReplyStatus reply_status;
      };

    typedef ReplyContext * ReplyContext_ptr;

    class OBBEXPDLL RequestInterceptor :
            public virtual Interceptors::Interceptor
      {
      public:
        static RequestInterceptor_ptr
                 _duplicate(RequestInterceptor_ptr obj);
        static RequestInterceptor_ptr
                 _narrow(RequestInterceptor_ptr obj);
        inline static RequestInterceptor_ptr _nil() { return 0; }

        virtual void
          exception_occurred( const ReplyContext & reply_context,
                              CORBA::Exception_ptr excep_val) = 0;

      protected:
        RequestInterceptor(CORBA::LocalBase_ptr obj = 0) { }
        virtual ~RequestInterceptor(){ }

      private:
        RequestInterceptor( const RequestInterceptor&) { }
        void operator=(const RequestInterceptor&) { }
      }; // class RequestInterceptor
#endif /* _RequestLevelInterceptor_h */

 


RequestContext Structure

Synopsis

Contains the information that represents the context in which a request is to be processed.

C++ Binding

struct  RequestContext 
{
Interceptors::Version struct_version;
CORBA::ULong request_id;
CORBA::Octet response_flags;
GIOP::TargetAddress target;
CORBA::String_var interface_id;
CORBA::String_var operation;
RequestContext &operator=(const RequestContext &_obj);
};

Members

struct_version

An indication of the version of the RequestContext that provides an indication of the format and members. The version information is separated into the following two pieces:

Version Member
Description
major_version
Indicates the major version value. The value of this member is incremented anytime a change is made to the contents or layout of a RequestContext that is not backward compatible with previous versions.
minor_version
Indicates the minor version value. The value of this member is incremented anytime a change is made to the contents or layout of a RequestContext that is backward compatible with previous versions.

request_id

An unsigned long value that specifies the identifier assigned to a request by the initiating ORB.

response_flags

The lowest order bit of response_flags is set to 1 if a reply message is expected for this request. If the operation is not defined as oneway, and the request is not invoked via the DII with the INV_NO_RESPONSE flag set, response_flags will be set to \x03. If the operation is defined as oneway, or the request is invoked via the DII with the INV_NO_RESPONSE flag set, response_flags may be set to \x00 or \x01. When this flag is set to \x01 for a oneway operation, receipt of a reply does not imply that the operation has necessarily completed.

target

A discriminated union that identifies the object that is the target of the invocation. The discriminator indicates the format in which the target addressing is presented. The possible discriminator values are:

Discriminator
Description
KeyAddr
The object_key field from the transport-specific GIOP profile (for example, from the encapsulated IIOP profile of the IOR for the target object). This value is meaningful only to the server and is not interpreted or modified by the client.
ProfileAddr
The transport-specific GIOP profile selected for the target’s IOR by the client ORB.

Note: In the Oracle Tuxedo 8.0 product, this discriminator value is not supported, but is provided for future support of GIOP 1.2.

ReferenceAddr
The full IOR of the target object. The selected_profile_index indicates the transport-specific GIOP profile that was selected by the client ORB.

Note: In the Oracle Tuxedo 8.0 product, this discriminator value is not supported, but is provided for future support of GIOP 1.2.

interface_id

A NULL-terminated string that specifies the repository identifier assigned to the interface of the object.

operation

A NULL-terminated string that specifies the name of the operation being requested on the target object indicated by the target member and that supports the interface specified by the value of the interface_id member.

Description

The RequestContext data object contains the information that represents the context in which a request is to be processed. The context information contained in the RequestContext provides information necessary to coordinate between the processing of a given request and its corresponding reply.

The context information in the RequestContext structure cannot be modified by the interceptor implementation. The ORB maintains ownership of the RequestContext and is responsible for freeing any resources associated with the RequestContext when it has completed using it.

 


ReplyContext Structure

Synopsis

Contains the information that represents the context in which a reply is to be processed.

C++ Binding

struct  ReplyContext 
{
Interceptors::Version struct_version;
CORBA::ULong request_id;
ReplyStatus reply_status;
};

Members

struct_version

An indication of the version of the ReplyContext that provides an indication of the format and members. The version information is separated into the following two pieces:

Version Member
Description
major_version
Indicates the major version value. The value of this member is incremented anytime a change is made to the contents or layout of a ReplyContext that is not backward compatible with previous versions.
minor_version
Indicates the minor version value. The value of this member is incremented anytime a change is made to the contents or layout of a ReplyContext that is backward compatible with previous versions.

request_id

An unsigned long value that specifies the identifier assigned to a request by the initiating ORB.

reply_status

Indicates the completion status of the associated request, and also determines part of the reply body contents.

Status Value
Description
NO_EXCEPTION
Indicates that the requested operation completed successfully and that the value of the arg_stream parameter contains the return values of the operation.
USER_EXCEPTION
Indicates that the requested operation failed because of an exception reported by the target object.
SYSTEM_EXCEPTION
Indicates that the request operation failed because of an exception reported either by the target object or by the infrastructure.
LOCATION_FORWARD
Indicates that the body contains an object reference (IOR). The client ORB is responsible for resending the original request to that (different) object. This resending is transparent to the client program making the request, but the resending is not transparent to the interceptor.
LOCATION_FORWARD_PERM
Indicates that the body contains an object reference. The usage is similar to LOCATION_FORWARD, but when used by a server, this value also provides an indication to the client that the client may replace the old IOR with the new IOR. Both the old IOR and the new IOR are valid, but the new IOR is preferred for future use. This resending is transparent to the client program making the request, but the resending is not transparent to the interceptor.
NEEDS_ADDRESSING_MODE
Indicates that the body contains a GIOP::AddressingDisposition. The client ORB is responsible for resending the original request using the requested addressing mode. This resending is transparent to the client program making the request, but the resending is not transparent to the interceptor.

Description

The ReplyContext data object contains the information that represents the context in which a reply is to be processed. The context information contained in ReplyContext provides information necessary to coordinate between the processing of a given request and its corresponding reply.

The context information in ReplyContext cannot be modified by the interceptor implementation. The ORB maintains ownership of ReplyContext and is responsible for freeing any resources associated with ReplyContext when it has completed using it.

 


RequestInterceptor::exception_occurred

Synopsis

Is called by the ORB to allow the interceptor to clean up any state that the interceptor might have been managing that is specific to a request.

C++ Binding

virtual void 
exception_occurred( const ReplyContext & reply_context,
CORBA::Exception_ptr excep_val) = 0;

Parameters

reply_context

A reference to a ReplyContext that contains information about the context in which the reply is being performed.

excep_val

A pointer to the exception reported by the ORB or by another interceptor.

Exceptions

None.

Description

The exception_occurred operation is called on a request-level interceptor implementation in one of three cases:

  1. Another interceptor sets an exception (rather than an exception being generated by the ORB or the method).
  2. The ORB detects an operating system or communication-related problem.
  3. A client deletes a Request object that was used to initiate a deferred synchronous DII. The exception_occurred method is called instead of the client_response or target_response method of that interceptor. The ORB calls the exception_occurred method to allow the interceptor implementation to clean up any state that it might have been managing that is specific to a request.

Return Values

None.

 


RequestLevelInterceptor::
ClientRequestInterceptor Interface

This is the base interface of all request-level interceptors. It inherits directly from the RequestLevelInterceptor::RequestInterceptor interface. The interface contains the set of operations and attributes that are supported by all client-side request-level interceptors.

Listing 8-5 OMG IDL Definition
//File: RequestLevelInterceptor.idl

#ifndef _REQUEST_LEVEL_INTERCEPTOR_IDL
#define _REQUEST_LEVEL_INTERCEPTOR_IDL

#include <orb.idl>
#include <Giop.idl>
#include <Interceptors.idl>

#pragma prefix “beasys.com”

module RequestLevelInterceptor
  {
  local ClientRequestInterceptor : RequestInterceptor
    {
    InvokeReturnStatus
      client_invoke(
             in    RequestContext           request_context,
             in    ServiceContextList       service_context,
             in    CORBA::DataInputStream   request_arg_stream,
             in    CORBA::DataOutputStream  reply_arg_stream,
             out   ExceptionValue           excep_val
                   );

    ResponseReturnStatus
      client_response(
                    in    ReplyContext           reply_context,
                    in    ServiceContextList     service_context,
                    in    CORBA::DataInputStream arg_stream,
                    out   ExceptionValue         excep_val
                     );
    };
  };
#endif /* _REQUEST_LEVEL_INTERCEPTOR_IDL */

The implementation of the operations _duplicate, _narrow, and _nil are inherited indirectly from the implementation of the CORBA::LocalBase interface provided by the CORBA ORB in the Oracle Tuxedo product.

Listing 8-6 C++ Declaration
#ifndef _RequestLevelInterceptor_h
#define _RequestLevelInterceptor_h

#include <CORBA.h>
#include <IOP.h>
#include <GIOP.h>
#include <Interceptors.h>

class OBBEXPDLL RequestLevelInterceptor
  {
  public:
    class   ClientRequestInterceptor;
    typedef ClientRequestInterceptor *
               ClientRequestInterceptor_ptr;

    class OBBEXPDLL ClientRequestInterceptor :
            public virtual RequestInterceptor
      {
      public:
        static ClientRequestInterceptor_ptr
          _duplicate(ClientRequestInterceptor_ptr obj);
        static ClientRequestInterceptor_ptr
          _narrow(ClientRequestInterceptor_ptr obj);
        inline static ClientRequestInterceptor_ptr
          _nil() { return 0; }

        virtual Interceptors::InvokeReturnStatus
          client_invoke(
              const RequestContext & request_context,
              ServiceContextList_ptr service_context,
              CORBA::DataInputStream_ptr request_arg_stream,
              CORBA::DataOutputStream_ptr reply_arg_stream,
              CORBA::Exception_ptr & excep_val ) = 0;

        virtual Interceptors::ResponseReturnStatus
          client_response(
              const ReplyContext & reply_context,
              ServiceContextList_ptr service_context,
              CORBA::DataInputStream_ptr arg_stream,
              CORBA::Exception_ptr & excep_val ) = 0;

      protected:
        ClientRequestInterceptor(CORBA::LocalBase_ptr obj = 0) { }
        virtual ~ClientRequestInterceptor(){ }

      private:
        ClientRequestInterceptor( const ClientRequestInterceptor&)
            { }
        void operator=(const ClientRequestInterceptor&) { }
      }; // class ClientRequestInterceptor
  };
#endif /* _RequestLevelInterceptor_h */

 


ClientRequestInterceptor::client_invoke

Synopsis

Is called by the client-side ORB anytime the client application sends an invocation to a target object.

C++ Binding

virtual Interceptors::InvokeReturnStatus 
client_invoke(
const RequestContext & request_context,
ServiceContextList_ptr service_context,
CORBA::DataInputStream_ptr request_arg_stream,
CORBA::DataOutputStream_ptr reply_arg_stream,
CORBA::Exception_ptr & excep_val ) = 0;

Parameters

request_context

A reference to a RequestContext that contains information about the context in which the request is being performed.

service_context

A pointer to a ServiceContextList containing service context information to be sent as part of the request to the target object.
Note: In Oracle Tuxedo 8.0, the value of this parameter is always a nil object.

request_arg_stream

A pointer to a DataInputStream that can be used by the interceptor implementation to retrieve the value of the parameter of the operation. The DataInputStream contains all in and inout parameters, in the order in which they are specified in the operation’s IDL definition, from left to right. A nil DataInputStream indicates that no arguments exist.

reply_arg_stream

A pointer to a CORBA::DataOutputStream that can be used to populate the parameters to be returned to the initiator of the invocation as a reply. The use of this parameter is only valid if a status of REPLY_NO_EXCEPTION is returned.
Note: In Oracle Tuxedo 8.0, the value of this parameter is always a nil object.

excep_val

A reference to a location in which the interceptor can return an exception in order to report an error. The use of this parameter is only valid if a status of REPLY_EXCEPTION is returned. Note that the ORB is responsible for the memory management for the excep_val parameter.

Exceptions

None.

Description

The client_invoke operation is called on an interceptor implementation that supports the RequestLevelInterceptor::ClientRequestInterceptor interceptor interface. The operation is called by the ORB anytime that an invocation is being sent to a target object, regardless of whether the target object is in a different address space or the same address space as the target object.

Return Values

INVOKE_NO_EXCEPTION

Indicates that the interceptor successfully performed any processing required and that the ORB should continue processing the invocation in order to deliver it to the target object.

REPLY_NO_EXCEPTION

Indicates that the interceptor successfully performed any processing required to totally satisfy the request. The ORB should consider the request completed and begins processing any information in the reply_arg_stream, if any, as the return parameter values for the request.
Note: In Oracle Tuxedo 8.0, an interceptor cannot return this status value.

REPLY_EXCEPTION

Indicates that the interceptor encountered an error that should result in the discontinued processing of the request toward the target. The parameter excep_val is used to report the exception to the ORB. The ORB calls interceptors on the way back to the client application with the exception_occurred operation rather than with the client_response operation. Note that the ORB is responsible for the memory management for the excep_val parameter.

 


ClientRequestInterceptor::client_response

Synopsis

Is called on an interceptor implementation that supports the RequestLevelInterceptor::ClientRequestInterceptor interface.

C++ Binding

virtual Interceptors::ResponseReturnStatus 
client_response(
const ReplyContext & reply_context,
ServiceContextList_ptr service_context,
CORBA::DataInputStream_ptr arg_stream,
CORBA::Exception_ptr & excep_val ) = 0;

Parameters

reply_context

A reference to a ReplyContext that contains information about the context in which the reply is being performed.

service_context

A pointer to a ServiceContextList containing service context information received as a result of processing the request by the target object. Note: In Oracle Tuxedo 8.0, the value of this parameter is always a nil object.

arg_stream

A pointer to a DataInputStream that can be used by the interceptor implementation to retrieve the value of the reply parameters of the operation.
The following table identifies what the client_response method returns in the DataInputStream object based on the status contained in the ReplyContext object:

Status Value
Description
LOCATION_FORWARD, LOCATION_FORWARD_PERM, or NEEDS_ADDRESSING_MODE
A nil DataInputStream is supplied.
NO_EXCEPTION
The DataInputStream contains first any operation return value, then any inout and out parameters in the order in which they appear in the operation's IDL definition, from left to right. A nil DataInputStream indicates that no arguments exist.
USER_EXCEPTION or SYSTEM_EXCEPTION
The DataInputStream contains the exception that was raised by the operation.

Note: Exceptions contain a string followed by any exception members. The string contains the repository ID for the exception. The exception members are passed in the same manner as a struct. A system exception contains two unsigned long members, a minor code, and a completion status.

excep_val

A reference to a location in which the interceptor can return an exception in order to report an error. The use of this parameter is only valid if a status of REPLY_EXCEPTION is returned. Note that the ORB is responsible for the memory management for the excep_val parameter.

Exceptions

None.

Description

The client_response operation is called on an interceptor implementation that supports the RequestLevelInterceptor::ClientRequestInterceptor interface. The operation is called by the ORB anytime that a reply to an invocation is being received by the initiator of the request, regardless of whether the initiator is in a different address space or the same address space as the target object.

Return Values

RESPONSE_NO_EXCEPTION

Indicates that the interceptor successfully performed any processing required and that the ORB should continue processing the reply to the request to deliver it to the initiator of the request.

RESPONSE_EXCEPTION

Indicates that the interceptor encountered an error. The parameter excep_val is used to report the exception to the ORB. Any interceptors not yet called on the way back to the client have their exception_occurred operation called by the ORB to notify them that processing the request has failed.

 


RequestLevelInterceptor::
TargetRequestInterceptor Interface

This is the base interface of all request-level interceptors. It inherits directly from the RequestLevelInterceptor::RequestInterceptor interface. The interface contains the set of operations and attributes that are supported by all target-side request-level interceptors.

Listing 8-7 OMG IDL Definition
//File: RequestLevelInterceptor.idl

#ifndef _REQUEST_LEVEL_INTERCEPTOR_IDL
#define _REQUEST_LEVEL_INTERCEPTOR_IDL

#include <orb.idl>
#include <Giop.idl>
#include <Interceptors.idl>

#pragma prefix “beasys.com”

module RequestLevelInterceptor
  {
  local TargetRequestInterceptor : RequestInterceptor
    {
    InvokeReturnStatus
      target_invoke(
               in    RequestContext           request_context,
               in    ServiceContextList       service_context,
               in    CORBA::DataInputStream   request_arg_stream,
               in    CORBA::DataOutputStream  reply_arg_stream,
               out    ExceptionValue          excep_val
                   );

    ResponseReturnStatus
      target_response(
                    in    ReplyContext            reply_context,
                    in    ServiceContextList      service_context,
                    in    CORBA::DataInputStream  arg_stream,
                    out   ExceptionValue          excep_val
                     );
    };
  };
#endif /* _REQUEST_LEVEL_INTERCEPTOR_IDL */

The implementation of the operations _duplicate, _narrow, and _nil are inherited indirectly from the implementation of the CORBA::LocalBase interface provided by the CORBA ORB in the Oracle Tuxedo product.

Listing 8-8 C++ Declaration
#ifndef _RequestLevelInterceptor_h
#define _RequestLevelInterceptor_h

#include <CORBA.h>
#include <IOP.h>
#include <GIOP.h>
#include <Interceptors.h>

class OBBEXPDLL RequestLevelInterceptor
  {
  public:
    class TargetRequestInterceptor;
    typedef TargetRequestInterceptor *
               TargetRequestInterceptor_ptr;

    class OBBEXPDLL TargetRequestInterceptor :
            public virtual RequestInterceptor
      {
      public:
        static TargetRequestInterceptor_ptr
            _duplicate(TargetRequestInterceptor_ptr obj);
        static TargetRequestInterceptor_ptr
            _narrow(TargetRequestInterceptor_ptr obj);
        inline static TargetRequestInterceptor_ptr
            _nil() { return 0; }

        virtual Interceptors::InvokeReturnStatus            target_invoke(
               const RequestContext & request_context,
               ServiceContextList_ptr service_context,
               CORBA::DataInputStream_ptr request_arg_stream,
               CORBA::DataOutputStream_ptr reply_arg_stream,
               CORBA::Exception_ptr & excep_val ) = 0;

        virtual Interceptors::ResponseReturnStatus
          target_response(
               const ReplyContext & reply_context,
               ServiceContextList_ptr service_context,
               CORBA::DataInputStream_ptr arg_stream,
               CORBA::Exception_ptr & excep_val ) = 0;

      protected:
        TargetRequestInterceptor(CORBA::LocalBase_ptr obj = 0) { }
        virtual ~TargetRequestInterceptor(){ }

      private:
        TargetRequestInterceptor( const TargetRequestInterceptor&)
           { }
        void operator=(const TargetRequestInterceptor&) { }
      }; // class TargetRequestInterceptor
  };
#endif /* _RequestLevelInterceptor_h */

 


TargetRequestInterceptor::target_invoke

Synopsis

Is called by the target-side ORB anytime an invocation is being received by a target object.

C++ Binding

virtual Interceptors::InvokeReturnStatus 
target_invoke(
const RequestContext & request_context,
ServiceContextList_ptr service_context,
CORBA::DataInputStream_ptr request_arg_stream,
CORBA::DataOutputStream_ptr reply_arg_stream,
CORBA::Exception_ptr & excep_val ) = 0;

Parameters

request_context

A reference to a RequestContext that contains information about the context in which the request is being performed.

service_context

A pointer to a ServiceContextList containing service context information received as part of the request to the target object. In Oracle Tuxedo 8.0, the value of this parameter is always a nil object.

request_arg_stream

A pointer to a DataInputStream that can be used by the interceptor implementation to retrieve the value of the parameter of the operation. The DataInputStream contains all in and inout parameters, in the order in which they are specified in the operation’s IDL definition, from left to right. A nil DataInputStream indicates that no arguments exist.

reply_arg_stream

A pointer to a DataOutputStream that can be used to populate the parameters to be returned to the initiator of the invocation as a reply. The use of this parameter is only valid if a status of REPLY_NO_EXCEPTION is returned.
In Oracle Tuxedo 8.0, the value of this parameter is always a nil object.

excep_val

A reference to a location in which the interceptor can return an exception in order to report an error. The use of this parameter is only valid if a status of REPLY_EXCEPTION is returned. Note that the ORB is responsible for the memory management for the excep_val parameter.

Exceptions

None.

Description

The target_invoke operation is called on an interceptor implementation that supports the RequestLevelInterceptor::TargetRequestInterceptor interface. The operation is called by the ORB anytime that an invocation is being received by a target object, regardless of whether the target object is in a different address space or the same address space as the target object.

Return Values

INVOKE_NO_EXCEPTION

Indicates that the interceptor successfully performed any processing required and that the ORB should continue processing the invocation in order to deliver it to the target object.

REPLY_NO_EXCEPTION

Indicates that the interceptor successfully performed any processing required to totally satisfy the request. The ORB should consider the request completed and begins processing any information in the reply_arg_stream, if any, as the return parameter values for the request.
Note: In Oracle Tuxedo 8.0, an interceptor cannot return this status value.

REPLY_EXCEPTION

Indicates that the interceptor encountered an error that should result in the discontinued processing of the request in order to deliver it to the target object. The parameter excep_val is used to report the exception to the ORB. The ORB calls interceptors on the way back to the client with the exception_occurred operation, rather than with the target_response operation. Note that the ORB is responsible for the memory management for the excep_val parameter.

 


TargetRequestInterceptor::target_response

Synopsis

Is called by the target-side ORB anytime that a reply to an invocation is being sent to the initiator of the request.

C++ Binding

virtual Interceptors::ResponseReturnStatus 
target_response(
const ReplyContext & reply_context,
ServiceContextList_ptr service_context,
CORBA::DataInputStream_ptr arg_stream,
CORBA::Exception_ptr & excep_val ) = 0;

Parameters

reply_context

A reference to a ReplyContext that contains information about the context in which the reply is being performed.

service_context

A pointer to a ServiceContextList containing service context information to be sent as a result of processing the request by the target object. Note: In Oracle Tuxedo 8.0, the value of this parameter is always a nil object.

arg_stream

A pointer to a DataInputStream that can be used by the interceptor implementation to retrieve the value of the reply parameters of the operation.
The following table identifies what the target_response method returns in the DataInputStream object based on the status contained in the ReplyContext object:

Status Value
Description
LOCATION_FORWARD, LOCATION_FORWARD_PERM, or NEEDS_ADDRESSING_MODE
A nil DataInputStream is supplied
NO_EXCEPTION
The DataInputStream contains first any operation return value, then any inout and out parameters in the order in which they appear in the operation's IDL definition, from left to right. A nil DataInputStream indicates that no arguments exist.
USER_EXCEPTION or SYSTEM_EXCEPTION
The DataInputStream contains the exception that was raised by the operation.

Note: Exceptions contain a string followed by any exception members. The string contains the repository ID for the exception. The exception members are passed in the same manner as a struct. A system exception contains two unsigned long members, a minor code, and a completion status.

excep_val

A reference to a location in which the interceptor can return an exception in order to report an error. The use of this parameter is valid only if a status of REPLY_EXCEPTION is returned. Note that the ORB is responsible for the memory management for the excep_val parameter.

Exceptions

None.

Description

The target_response operation is called on an interceptor implementation that supports the RequestLevelInterceptor::TargetRequestInterceptor interface. The operation is called by the target-side ORB anytime that a reply to an invocation is being sent to the initiator of the request, regardless of whether the initiator is in a different address space or the same address space as the target object.

Return Values

RESPONSE_NO_EXCEPTION
Indicates that the interceptor successfully performed any processing required and that the ORB should continue processing the reply to the request to deliver it to the initiator of the request.
RESPONSE_EXCEPTION
Indicates that the interceptor encountered an error. The parameter excep_val is used to report the exception to the ORB. Any interceptors not yet called on the way back to the client have their exception_occurred operation called by the ORB in order to notify them that processing the request has failed. Note that the ORB is responsible for the memory management for the excep_val parameter.

 


AppRequestInterceptorInit

Synopsis

Instantiates and initializes client-side and target-side interceptors.

C++ Binding

typedef void (*AppRequestInterceptorInit)(
CORBA::ORB_ptr TheORB,
RequestLevelInterceptor::ClientRequestInterceptor ** ClientPtr,
RequestLevelInterceptor::TargetRequestInterceptor ** TargetPtr,
CORBA::Boolean * RetStatus);

Parameters

TheORB

A pointer to the ORB object with which the implementation of the interceptors are associated.

ClientPtr

A pointer in which to return a pointer to the instance of the RequestLevelInterceptor::ClientRequestInterceptor that was instantiated for use by the ORB.

TargetPtr

A pointer in which to return a pointer to the instance of the RequestLevelInterceptor::TargetRequestInterceptor that was instantiated for use by the ORB.

RetStatus

A pointer to a location into which the interceptor implementation indicates whether the instantiation and initialization of the interceptor was successful. A value of CORBA::TRUE is used to indicate that instantiation and initialization of the interceptors was successful. A value of CORBA::FALSE is used to indicate that the instantiation and initialization of the interceptors was unsuccessful for some reason.

Exceptions

None.

Description

The AppRequestInterceptorInit function is a user-provided function that is used by the ORB to instantiate and initialize client-side and target-side interceptors.

Return Values

None.

 


CORBA::DataInputStream Interface

The abstract valuetype keywords in IDL applied to DataInputStream indicates that it is not the same as an interface.

Listing 8-9 OMG IDL Definition
module CORBA  {
//... all the rest

// Definitions used by DataInputStream
  typedef sequence<any>            AnySeq;
  typedef sequence<boolean>        BooleanSeq;
  typedef sequence<char>           CharSeq;
  typedef sequence<octet>          OctetSeq;
  typedef sequence<short>          ShortSeq;
  typedef sequence<unsigned short> UShortSeq;
  typedef sequence<long>           LongSeq;
  typedef sequence<unsigned long>  ULongSeq;
  typedef sequence<float>          FloatSeq;
  typedef sequence<double>         DoubleSeq;

// DataInputStream - for reading data from the stream
  abstract valuetype DataInputStream
          {
        any                        read_any(); // Raises NO_IMPLEMENT
        boolean                    read_boolean();
        char                       read_char();
        octet                      read_octet();
        short                      read_short();
        unsigned short             read_ushort();
        long                       read_long();
        unsigned long              read_ulong();
        float                      read_float();
        double                     read_double();
        string                     read_string ();
        Object                     read_Object();
        TypeCode                   read_TypeCode();
        void                       read_any_array( inout AnySeq seq,
                                                   in unsigned long offset,
                                                   in unsigned long length);
                                              // Raises NO_IMPLEMENT
        void                        read_boolean_array(inout BooleanSeq seq,
                                                   in unsigned long offset,
                                                   in unsigned long length);
        void                        read_char_array( inout CharSeq seq,
                                                      in unsigned long offset,
                                                      in unsigned long length);
        void                         read_octet_array(inout OctetSeq seq,
                                                      in unsigned long offset,
                                                      in unsigned long length);
        void                         read_short_array(inout ShortSeq seq,
                                                      in unsigned long offset,
                                                      in unsigned long length);
        void                         read_ushort_array(inout UShortSeq seq,
                                                      in unsigned long offset,
                                                      in unsigned long length);
        void                         read_long_array( inout LongSeq seq,
                                                      in unsigned long offset,
                                                      in unsigned long length);
        void                         read_ulong_array(inout ULongSeq seq,
                                                      in unsigned long offset,
                                                      in unsigned long length);
        void                         read_float_array(inout FloatSeq seq,
                                                      in unsigned long offset,
                                                      in unsigned long length);
        void                         read_double_array(inout DoubleSeq seq,
                                                      in unsigned long offset,
                                                      in unsigned long length);
            };
};

The implementation of CORBA::DataInputStream inherits from CORBA::ValueBase rather than from CORBA::Object. You cannot use, for example, _duplicate, _narrow, and _nil operations since they apply only to CORBA::Object. At this time, there is nothing of interest for users in the CORBA::ValueBase interface.

Listing 8-10 C++ Declaration
class  CORBA
{
public:

  class      AnySeq {/* Normal sequence definition */};
  typedef    AnySeq *    AnySeq_ptr;

  class      BooleanSeq {/* Normal sequence definition */};
  typedef    BooleanSeq *    BooleanSeq_ptr;
  static const CORBA::TypeCode_ptr _tc_BooleanSeq;

  class      CharSeq {/* Normal sequence definition */};
  typedef    CharSeq *    CharSeq_ptr;
  static const CORBA::TypeCode_ptr _tc_CharSeq;

  class      OctetSeq {/* Normal sequence definition */};
  typedef    OctetSeq *    OctetSeq_ptr;
  static const CORBA::TypeCode_ptr _tc_OctetSeq;

  class      ShortSeq {/* Normal sequence definition */};
  typedef    ShortSeq *    ShortSeq_ptr;
  static const CORBA::TypeCode_ptr _tc_ShortSeq;

  class      UshortSeq {/* Normal sequence definition */};
  typedef    UShortSeq *    UShortSeq_ptr;
  static const CORBA::TypeCode_ptr _tc_UShortSeq;

  class      LongSeq {/* Normal sequence definition */};
  typedef    LongSeq *    LongSeq_ptr;
  static const CORBA::TypeCode_ptr _tc_LongSeq;

  class      UlongSeq {/* Normal sequence definition */};
  typedef    ULongSeq *    ULongSeq_ptr;
  static const CORBA::TypeCode_ptr _tc_ULongSeq;

  class      FloatSeq {/* Normal sequence definition */};
  typedef    FloatSeq *    FloatSeq_ptr;
  static const CORBA::TypeCode_ptr _tc_FloatSeq;

  class      DoubleSeq {/* Normal sequence definition */};
  typedef    DoubleSeq *    DoubleSeq_ptr;
  static const CORBA::TypeCode_ptr _tc_DoubleSeq;

  class OBBEXPDLL DataInputStream : public virtual ValueBase
  {
   public:
    static DataInputStream_ptr _downcast(ValueBase_ptr obj);

    virtual Any *         read_any (); // Raises NO_IMPLEMENT
    virtual Boolean       read_boolean ();
    virtual Char          read_char ();
    virtual Octet         read_octet ();
    virtual Short         read_short ();
    virtual UShort        read_ushort ();
    virtual Long          read_long ();
    virtual ULong         read_ulong ();
    virtual Float         read_float ();
    virtual Double        read_double ();
    virtual Char *        read_string ();
    virtual Object_ptr    read_Object ();
    virtual TypeCode_ptr  read_TypeCode ();

    virtual void read_any_array ( AnySeq & seq,
                        ULong offset, ULong length);
                        // Raises NO_IMPLEMENT
    virtual void read_boolean_array(BooleanSeq & seq,
                        ULong offset, ULong length);
    virtual void read_char_array ( CharSeq & seq,
                        ULong offset, ULong length);
    virtual void read_octet_array ( OctetSeq & seq,
                        ULong offset, ULong length);
    virtual void read_short_array ( ShortSeq & seq,
                        ULong offset, ULong length);
    virtual void read_ushort_array (UShortSeq & seq,
                        ULong offset, ULong length);
    virtual void read_long_array ( LongSeq & seq,
                        ULong offset, ULong length);
    virtual void read_ulong_array ( ULongSeq & seq,
                        ULong offset, ULong length);
    virtual void read_float_array ( FloatSeq & seq,
                        ULong offset, ULong length);
    virtual void read_double_array (DoubleSeq & seq,
                        ULong offset, ULong length);

   protected:
    DataInputStream(){ };
    virtual ~DataInputStream(){ }

    private:
    void operator=(const DataInputStream&) { }
};

typedef    DataInputStream *    DataInputStream_ptr;
};

 


DataInputStream::read_<primitive>

Synopsis

Returns a value from the stream.

C++ Binding

<primitive> read_<primitive>();

Parameters

None.

Exceptions

None.

Description

The operations to read a primitive element (<primitive>) from a DataInputStream all have the same format. Each operation returns a value from the stream.

Note: String_var, TypeCode_var, or Object_var can be used for memory management. Otherwise, strings must be released using the string_free() operation on the CORBA object, and TypeCode or Object pointers must be released using the release() operation on the CORBA object.

The primitives are the following:

AnySeq  (Not implemented)
BooleanSeq
CharSeq
OctetSeq
ShortSeq
UshortSeq
LongSeq
UlongSeq
FloatSeq
DoubleSeq

Return Values

None.

 


DataInputStream::read_array_<primitive>

Synopsis

Returns an array of primitive values from the stream into a CORBA sequence.

C++ Binding

void read_array_<primitive>(     <primitive>Seq & seq, 
ULong offset,
ULong length);

Parameters

<primitive>Seq

A sequence of the appropriate type that will receive the array elements read.
If the sequence was not long enough to contain the additional elements, the length will be set to the sum offset+length. (The length will not be adjusted down.)

Offset

The offset into the array to read the elements. That is, the array will have new elements starting at array index offset up to array index offset+length-1.

Length

The number of elements of the array to be returned into the seq parameter.

Exceptions

None.

Description

The operations to read an array of primitive elements (<primitive>) from a DataInputStream all have the same format. Each operation returns an array of primitive values from the stream into a CORBA sequence of that same primitive type.

The primitives are the following:

AnySeq (Not implemented)
BooleanSeq
CharSeq
OctetSeq
ShortSeq
UshortSeq
LongSeq
UlongSeq
FloatSeq
DoubleSeq

Return Values

None.


  Back to Top       Previous  Next