org.objectweb.jonathan.apis.protocols
Interface Protocol

All Known Implementing Classes:

RmiProtocol, TcpIpProtocol, 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(java.util.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 Detail

isAnInvocationProtocol

boolean isAnInvocationProtocol()

Returns true if the target protocol is an invocation protocol.

An invocation protocol is a protocol able to handle invocations, i.e., requests expecting a reply. In practice, this means that calls to the prepareInvocation method on sessions obtained from the target protocol will not raise an InternalException, but perform the appropriate work.

Returns:

true if the target protocol is an invocation protocol.

createProtocolGraph

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

Throws:

JonathanException - if the hints or the subgraphs are invalid for this protocol

createSessionIdentifier

SessionIdentifier createSessionIdentifier(java.util.Properties info,
                                          SessionIdentifier[] next)
                                          throws JonathanException

Creates a new session identifier with the provided info.

Parameters:

info - information to create the session identifier.

next - session identifiers of the lower sessions?

Returns:

the created session identifier.

Throws:

JonathanException - if something goes wrong.