org.objectweb.jonathan.protocols.api

Interface Session_High

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 Details

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.


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.


prepare

public void prepare(Marshaller m)
            throws 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


prepareInvocation

public ReplyInterface prepareInvocation(Marshaller m)
            throws JonathanException


send

public void send(Marshaller m)
            throws 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;

See Also:
prepareInvocation(Marshaller), prepare(Marshaller)