public interface Protocol
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.
Modifier and Type | Method and Description |
---|---|
ProtocolGraph |
createProtocolGraph(ProtocolGraph[] subgraphs,
org.objectweb.jonathan.apis.kernel.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.
|
boolean isAnInvocationProtocol()
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.
ProtocolGraph createProtocolGraph(ProtocolGraph[] subgraphs, org.objectweb.jonathan.apis.kernel.Context hints) throws org.objectweb.jonathan.apis.kernel.JonathanException
subgraphs
- the lower-level graphshints
- the information req'd to build the graphorg.objectweb.jonathan.apis.kernel.JonathanException
- if the hints or the subgraphs are
invalid for this protocolSessionIdentifier createSessionIdentifier(Properties info, SessionIdentifier[] next) throws org.objectweb.jonathan.apis.kernel.JonathanException
org.objectweb.jonathan.apis.kernel.JonathanException