org.objectweb.jonathan.apis.protocols
Interface Session_High

All Known Subinterfaces:
IpSession

public interface Session_High

Session_High is the type of sessions used to send messages down to the network; A Session_High is usually a surrogate for a session of type Session_Low exported to a protocol and represented by an session identifier.

Sessions represent handles on particular communication channels: A session object is dynamically created by a protocol, and lets messages be sent and received through the communication channel it represents, using that protocol. Sessions have higher and lower interfaces, respectively used to send messages down and up a protocol stack.

Usually, a Session_High instance is obtained using the bind operation on a session identifier representing a Session_Low interface: it is thus a surrogate, or a proxy, for that interface.


Method Summary
 void close()
          Closes the session, letting the associated resources be released or reused.
 boolean direct()
          Return false if the prepare or prepareInvocation must be used, true otherwise.
 void prepare(Marshaller m)
          Lets the target session write its own headers into the provided message (one-way case).
 ReplyInterface prepareInvocation(Marshaller m)
           
 void send(Marshaller m)
          Sends the message down the protocol stack.
 

Method Detail

prepare

public void prepare(Marshaller m)
             throws org.objectweb.jonathan.apis.kernel.JonathanException
Lets the target session write its own headers into the provided message (one-way case).

Protocols usually need to add headers in the front of messages before sending them down the net. It may be much more efficient to add these headers before the actual message is written. The prepare (and prepareInvocation methods are provided for this purpose. Therefore, an entity wishing to send a message down a protocol stack must first prepare that message by invoking the appropriate method (unless a call to direct returns true), and then write its own data to the message.

The prepare method must only be used to prepare messages with a one-way semantics (no reply expected); If a reply is expected, use prepareInvocation instead.

Parameters:
m - a marshaller representing the message
Throws:
org.objectweb.jonathan.apis.kernel.JonathanException - if something goes wrong.

direct

public boolean direct()
Return false if the prepare or prepareInvocation must be used, true otherwise.

A true return means that the target protocols headers are added when the message is sent, and not before. Invoking one of the prepare methods would in that case return without having changed anything to the provided marshaler.

Returns:
true if the prepare methods need not be used.

prepareInvocation

public ReplyInterface prepareInvocation(Marshaller m)
                                 throws org.objectweb.jonathan.apis.kernel.JonathanException
Throws:
org.objectweb.jonathan.apis.kernel.JonathanException

send

public void send(Marshaller m)
          throws org.objectweb.jonathan.apis.kernel.JonathanException
Sends the message down the protocol stack.

The sent message must have been prepared first, unless a call to direct returns true.

It is the responsibility of the recipient of the message to close it.

Parameters:
m - the message to send;
Throws:
org.objectweb.jonathan.apis.kernel.JonathanException - if something goes wrong.
See Also:
prepareInvocation(Marshaller), prepare(Marshaller)

close

public void close()
Closes the session, letting the associated resources be released or reused.

Sessions may have an exclusive access to a communication resource. It is thus very important to ensure that they are properly closed if they are no longer in use.