%

Using the org.jacorb.transport.Current Feature

\emph{by Iliyan Jeliazkov}

\section{Scope and Context}

There is no standard-mandated mechanism to facilitate obtaining statistical or pretty
much any operational information about the network transport which the ORB is using.
While this is a direct corollary of the CORBA's design paradigm which mandates hiding
all this hairy stuff behind non-transparent abstractions, it also precludes effective
ORB and network monitoring.

The Transport::Current feature intends to fill this gap by defining a framework
for developing a wide range of solutions to this problem. It also provides a basic
implementation for the most common case - the IIOP transport.

By definition, transport-specific information is available in contexts where the
ORB has selected a Transport:

\begin{itemize}
\item Within Client-side interception points;
\item Within Server-side interception points;
\item Inside a Servant up-call
\end{itemize}

The implementation is based on a generic service-oriented framework, implementing
the Transport::Current interface. It is an optional service, which can be dynamically
loaded. This service makes the Transport::Current interface available through
{\tt orb->resolve\_initial\_references()}. The basic idea is simple - whenever a Transport
is chosen by the ORB, the Transport::Current (or a protocol-specific derivative)
will have access to that instance and be able to provide some useful information.



\section{Programmer's Reference}

Consider the following IDL interface to access transport-specific data.

\begin{verbatim}
module org
{

  module jacorb
  {

    module transport
    {
      /// A type used to represent counters
      typedef unsigned long long CounterT;

      // Used to signal that a call was made outside the
      // correct invocation context.

      exception NoContext
      {
      };

      // The main interface, providing access to the Transport-specific
      // information (traits), available to the current thread of
      // execution.

      local interface Current
      {
          /// Transport ID, unique within the process.
        long id() raises (NoContext);

          /// Bytes sent/received through the transport.
          CounterT bytes_sent() raises (NoContext);
          CounterT bytes_received() raises (NoContext);

          /// Messages (requests and replies) sent/received using the current
          /// protocol.
          CounterT messages_sent() raises (NoContext);
          CounterT messages_received() raises (NoContext);

          /// The absolute time (miliseconds) since the transport has been
          /// open.
          TimeBase::TimeT open_since() raises (NoContext);
      };

    };

  };

};
\end{verbatim}

As an example of a specialized Transport::Current is the Transport::IIOP::Current,
which derives from Transport::Current and has an interface, described in the following IDL:

\begin{verbatim}
module org
{

  module jacorb
  {

    module transport
    {
      /// A type used to represent counters
      typedef unsigned long long CounterT;

      // Used to signal that a call was made outside the
      // correct invocation context.

      exception NoContext
      {
      };

      // The main interface, providing access to the Transport-specific
      // information (traits), available to the current thread of
      // execution.

      local interface Current
      {
          /// Transport ID, unique within the process.
        long id() raises (NoContext);

          /// Bytes sent/received through the transport.
          CounterT bytes_sent() raises (NoContext);
          CounterT bytes_received() raises (NoContext);

          /// Messages (requests and replies) sent/received using the current
          /// protocol.
          CounterT messages_sent() raises (NoContext);
          CounterT messages_received() raises (NoContext);

          /// The absolute time (miliseconds) since the transport has been
          /// open.
          TimeBase::TimeT open_since() raises (NoContext);
      };

    };

  };

};
\end{verbatim}


\section{User's Guide}

The org.jacorb.transport.Current can be used as a base interface for a more
specialized interfaces. However, it is not required that a more specialized
Current inherits from it.

Typical, generic usage is shown in the
tests/regression/src/org/jacorb/test/transport/IIOPTester.java test:

\begin{verbatim}
...
   // Get the Current object.
   Object tcobject =
      orb.resolve_initial_references ("JacOrbIIOPTransportCurrent");
   Current tc = CurrentHelper.narrow (tcobject);

   logger.info("TC: ["+tc.id()+"] from="+tc.local_host() +":"
                + tc.local_port() +", to="
                +tc.remote_host()+":"+tc.remote_port());

   logger.info("TC: ["+tc.id()+"] sent="+tc.messages_sent ()
                + "("+tc.bytes_sent ()+")"
                + ", received="+tc.messages_received ()
                + "("+tc.bytes_received ()+")");
...
\end{verbatim}

\subsection{Configuration, Bootstrap, Initialization and Operation}


To use the Transport Current features the framework must be loaded
through the Service Configuration framework. For example, using something
like this:

\begin{verbatim}
...
        Properties serverProps = new Properties();

        // We need the TC functionality
        serverProps.put ("org.omg.PortableInterceptor.ORBInitializerClass.
                             server_transport_current_interceptor",
                         "org.jacorb.transport.TransportCurrentInitializer");

        serverProps.put ("org.omg.PortableInterceptor.ORBInitializerClass.
                             server_transport_current_iiop_interceptor",
                        "org.jacorb.transport.IIOPTransportCurrentInitializer");

        serverORB = ORB.init(new String[0], serverProps);
...
\end{verbatim}

The ORB initializer registers the "JacORbIIOPTransportCurrent" name with the orb,
so that it could be resolved via {\tt orb->resolve\_initial\_references("JacORbIIOPTransportCurrent")}.

Note that any number of transport-specific Current interfaces may be available at any one time.
