%
% $Id: transportcurrent.tex,v 1.1 2007-02-17 19:09:39 brose Exp $ 
%

Using the org.jacorb.transport.Current Feature

\em{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 l
oaded. This service makes the Transport::Current interface available through 
orb->resolve\_initial\_references() . The basic idea is simple - whenever a Transport 
is chosen by the ORB, the Transport::Current (or a protocolo-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. Iowever, 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 orb->resolve\_initial\_references("JacORbIIOPTransportCurrent"). 

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