com.sun.sgs.protocol
Interface SessionRelocationProtocol

All Superinterfaces:

Channel, Closeable, SessionProtocol

public interface SessionRelocationProtocol
extends SessionProtocol

Protocol additions for suspending and resuming messages to a client session and relocating a client session to another node.

Nested Class Summary

Nested classes/interfaces inherited from interface com.sun.sgs.protocol.SessionProtocol

SessionProtocol.DisconnectReason

Method Summary

void	relocate(Set<ProtocolDescriptor> descriptors, ByteBuffer relocationKey, RequestCompletionHandler<Void> completionHandler) Notifies the associated client to relocate its session to the node specified by the descriptors using the given relocationKey.
void	resume() Notifies the associated client to resume sending messages to the server.
void	suspend(RequestCompletionHandler<Void> completionHandler) Notifies the associated client to suspend sending messages to the server until resume is invoked.

Methods inherited from interface com.sun.sgs.protocol.SessionProtocol

channelJoin, channelLeave, channelMessage, disconnect, getDeliveries, getMaxMessageLength, sessionMessage

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Method Detail

suspend

void suspend(RequestCompletionHandler<Void> completionHandler)
             throws IOException

Notifies the associated client to suspend sending messages to the server until resume is invoked. This method must notify the completionHandler when messages have been suspended. Messages received by the SessionProtocolHandler will be received and processed until the completionHandler's completed method is invoked. If messages are not suspended in a timely fashion (i.e, the completionHandler is not notified), then the server may disconnect this session.

Only session messages that have their completion handlers notified before the specified completionHandler is notified are guaranteed to be processed by the server.

Once this method is invoked, an invocation on a method that sends a message to the client should throw IllegalStateException until messages are resumed.

Parameters:

completionHandler - a completion handler

Throws:

IOException - if an I/O error occurs

resume

void resume()
            throws IOException

Notifies the associated client to resume sending messages to the server. If messages were not previously suspended, the method is not required to take action.

Throws:

IOException - if an I/O error occurs

relocate

void relocate(Set<ProtocolDescriptor> descriptors,
              ByteBuffer relocationKey,
              RequestCompletionHandler<Void> completionHandler)
              throws IOException

Notifies the associated client to relocate its session to the node specified by the descriptors using the given relocationKey.

The associated client session can be reestablished on the new node by notifying the ProtocolListener of this protocol's corresponding ProtocolAcceptor on the new node. The ProtocolListener.relocatedSession method can be invoked on the new node with the given relocation key to reestablish the client session without having to log in again.

Once this method is invoked, an invocation on a method that sends a message to the client should throw IllegalStateException. Additionally, the client should close any underlying local connection(s) in a timely fashion.

Parameters:

descriptors - protocol descriptors for newNode

relocationKey - the key to be supplied to the new node

completionHandler - a completion handler

Throws:

IllegalStateException - if the associated session is not suspended or is already relocating

IOException - if an I/O error occurs