com.sun.sgs.protocol
Interface SessionProtocolHandler

public interface SessionProtocolHandler

A handler for session and channel protocol messages for an associated client session.

Each operation takes a RequestCompletionHandler argument to be notified when the associated request has been processed. A caller may need to know when an operation has completed so that it can throttle incoming messages (for example only resuming reading when the handler completes processing a request), and/or can control the number of clients connected at any given time.

When a SessionProtocolHandler instance finishes processing a request (corresponding to one of its methods), it invokes the completed method (on completionHandler specified in the request) with a Future that contains the result of the request. This Future can be checked (by invoking the Future.get method) to see if processing the request failed.

If the request failed, then invoking the get method on the supplied Future will throw ExecutionException with a cause of RequestFailureException. The reason for the failure can be obtained by invoking the getReason method on the RequestFailureException. The request may fail for one of the following reasons:

• LOGIN_PENDING: the client session has not completed login
• RELOCATION_PENDING: the client session is relocating to another node
• DISCONNECT_PENDING: the client session is disconnecting
• OTHER: some other failure occurred, and invoking getCause on the RequestFailureException returns the exception that caused the failure

Method Summary

void	channelMessage(BigInteger channelId, ByteBuffer message, RequestCompletionHandler<Void> completionHandler) Processes a channel message sent by the associated client on the channel with the specified channelId, and invokes the completed method on the given completionHandler when this handler has completed processing the channel message.
void	disconnect(RequestCompletionHandler<Void> completionHandler) Notifies this handler that a non-graceful client disconnection has occurred, and invokes the completed method on the given completionHandler when this handler has completed processing the disconnection.
void	logoutRequest(RequestCompletionHandler<Void> completionHandler) Processes a logout request from the associated client, and invokes the completed method on the given completionHandler when this handler has completed processing the logout request.
void	sessionMessage(ByteBuffer message, RequestCompletionHandler<Void> completionHandler) Processes a message sent by the associated client, and invokes the completed method on the given completionHandler when this handler has completed processing the message.

Method Detail

sessionMessage

void sessionMessage(ByteBuffer message,
                    RequestCompletionHandler<Void> completionHandler)

Processes a message sent by the associated client, and invokes the completed method on the given completionHandler when this handler has completed processing the message. The message starts at the buffer's current position and ends at the buffer's limit. The buffer's position is not modified by this operation.

The ByteBuffer may be reused immediately after this method returns. Changes made to the buffer after this method returns will have no effect on the message supplied to this method.

Parameters:

message - a message

completionHandler - a completion handler

channelMessage

void channelMessage(BigInteger channelId,
                    ByteBuffer message,
                    RequestCompletionHandler<Void> completionHandler)

Processes a channel message sent by the associated client on the channel with the specified channelId, and invokes the completed method on the given completionHandler when this handler has completed processing the channel message. The message starts at the buffer's current position and ends at the buffer's limit. The buffer's position is not modified by this operation.

The ByteBuffer may be reused immediately after this method returns. Changes made to the buffer after this method returns will have no effect on the message supplied to this method.

Parameters:

channelId - a channel ID

message - a message

completionHandler - a completion handler

logoutRequest

void logoutRequest(RequestCompletionHandler<Void> completionHandler)

Processes a logout request from the associated client, and invokes the completed method on the given completionHandler when this handler has completed processing the logout request.

Parameters:

completionHandler - a completion handler

disconnect

void disconnect(RequestCompletionHandler<Void> completionHandler)

Notifies this handler that a non-graceful client disconnection has occurred, and invokes the completed method on the given completionHandler when this handler has completed processing the disconnection.

Parameters:

completionHandler - a completion handler