org.objectweb.jonathan.protocols.api

Interface Protocol

Known Subinterfaces:
HttpProtocol
Known Implementing Classes:
MulticastIpProtocol, MultiplexProtocol, RTPProtocol, TcpIpProtocol

public interface Protocol

The protocol abstraction represents protocols like TCP, IP or GIOP. A protocol is a naming context that only deals with a specific family of interfaces -- called sessions --, and manages names -- called session identifiers -- to designate these interfaces. A protocol is actually a binder, since it may give access to the interfaces it identifies.

The Protocol, and ProtocolGraph abstractions have been designed in Jonathan to allow the creation of arbitrary protocol stacks, or even graphs.

The first step in this process is the creation of a protocol graph that will represent the expected protocol structure. Methods to create such graphs must be provided by protocols. A protocol graph is a directed (acyclic) graph composed of protocol-specific nodes, and describing a path to be followed by messages when they are sent over the net, or received. Each node has a protocol-specific arity.

Imagine for instance that you want to build a stack with the GIOP protocol on top of TCP/IP. You need first to create a graph reduced to one TCP/IP node (by calling the appropriate method on the TCP/IP protocol), and then to extend it with a GIOP node pointing to the TCP/IP node you have just obtained: The GIOP layer is not designed to issue requests over a network, and thus expects to issue its requests to a lower layer. The GIOP nodes are built using a protocol graph representing that lower layer. Note that nothing would forbid a different architecture, with possibly two graphs representing two different lower layers, one used to issue one-way requests, and the other for two way requests.

When graphs are created, it is also possible to specify additional information: for instance, the TCP/IP protocol lets you specify a preferred port number. That's why there is no generic newProtocolGraph operation: the structure of a node and the information to store in it are very dependent on the specific protocol used.

Once you have obtained a specific protocol graph, you can use it to export an interface of a specific type: Session_Low. This provides you with a session identifier, which is a name for the exported interface. You only need to call the export method on the root of the protocol graph: The appropriate calls will be recursively issued on its sub-graphs.

Information contained in this session identifier may be tranmitted over the network, and a copy of the session identifier re-constructed on a different machine (using the appropriate methods provided by protocols). To be able to access the exported interface, you will have to call the bind operation to obtain a session of type Session_High, that will let you send messages to the exported session.

Method Summary

ProtocolGraph
createProtocolGraph(ProtocolGraph subgraphs, Context hints)
Creates a new protocol graph with a number of given sub protocol graphs.
SessionIdentifier
createSessionIdentifier(Properties info, SessionIdentifier next)
Creates a new session identifier with the provided info
boolean
isAnInvocationProtocol()
Returns true if the target protocol is an invocation protocol.

Method Details

createProtocolGraph

public ProtocolGraph createProtocolGraph(ProtocolGraph subgraphs,
                                         Context hints)
            throws JonathanException
Creates a new protocol graph with a number of given sub protocol graphs.

Parameters:
subgraphs - the lower-level graphs
hints - the information req'd to build the graph

Returns:
a new ProtocolGraph


createSessionIdentifier

public SessionIdentifier createSessionIdentifier(Properties info,
                                                 SessionIdentifier next)
            throws JonathanException
Creates a new session identifier with the provided info


isAnInvocationProtocol

public boolean isAnInvocationProtocol()

Returns:
true if the target protocol is an invocation protocol.