Request-Level Interceptor API

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

• Interceptors::Interceptor

• RequestLevelInterceptor::RequestInterceptor

• RequestLevelInterceptor::ClientRequestInterceptor

• RequestLevelInterceptor::TargetRequestInterceptor

• CORBA::DataInputStream

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 BEA Tuxedo product.

 

Note on Unused Interfaces

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

• RequestLevelInterceptor::DataOutputStream

• RequestLevelInterceptor::ServiceContextList

These interfaces are not used in the BEA Tuxedo product. However, they are defined in the BEA 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 BEA 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 BEA 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 */