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

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

Throws:

JonathanException - if something goes wrong.

direct

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

ReplyInterface prepareInvocation(Marshaller m)
                                 throws JonathanException

Throws:

JonathanException

send

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;

Throws:

JonathanException - if something goes wrong.

See Also:

prepareInvocation(Marshaller), prepare(Marshaller)

close

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.