com.sun.sgs.impl.protocol.simple
Class SimpleSgsRelocationProtocolImpl

java.lang.Object
  com.sun.sgs.impl.protocol.simple.SimpleSgsProtocolImpl
      com.sun.sgs.impl.protocol.simple.SimpleSgsRelocationProtocolImpl

All Implemented Interfaces:

SessionProtocol, SessionRelocationProtocol, Closeable, Channel

public class SimpleSgsRelocationProtocolImpl
extends SimpleSgsProtocolImpl
implements SessionRelocationProtocol

Implements the protocol specified in SimpleSgsProtocol. The implementation uses a wrapper channel, AsynchronousMessageChannel, that reads and writes complete messages by framing messages with a 2-byte message length, and masking (and re-issuing) partial I/O operations. Also enforces a fixed buffer size when reading.

Nested Class Summary

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

SessionProtocol.DisconnectReason

Field Summary

Fields inherited from class com.sun.sgs.impl.protocol.simple.SimpleSgsProtocolImpl

acceptor, deliverySet, listener, logger, protocolHandler, reconnectKey

Constructor Summary

(package private)	SimpleSgsRelocationProtocolImpl(ProtocolListener listener, SimpleSgsProtocolAcceptor acceptor, AsynchronousByteChannel byteChannel, int readBufferSize) Creates a new instance of this class.
protected	SimpleSgsRelocationProtocolImpl(ProtocolListener listener, SimpleSgsProtocolAcceptor acceptor, AsynchronousByteChannel byteChannel, int readBufferSize, LoggerWrapper logger) Constructs a new instance of this class.

Method Summary

void	channelJoin(String name, BigInteger channelId, Delivery delivery) Notifies the associated client that it is joined to the channel with the specified name and channelId.
void	channelLeave(BigInteger channelId) Notifies the associated client that it is no longer a member of the channel with the specified channelId.
void	channelMessage(BigInteger channelId, ByteBuffer message, Delivery delivery) Sends the associated client the specified channel message for the channel with the specified channelId in a manner that satisfies the specified delivery guarantee.
protected byte	getProtocolVersion() Returns the SimpleSgsProtocol version supported by this implementation.
protected void	handleMessageReceived(byte opcode, MessageBuffer msg) Handles v5 protocol messages (relocate and suspend), and delegates to the super class to handle the v4 protocol messages.
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	sessionMessage(ByteBuffer message, Delivery delivery) Sends the associated client the specified message in a manner that satisfies the specified delivery guarantee.
void	suspend(RequestCompletionHandler<Void> completionHandler) Notifies the associated client to suspend sending messages to the server until resume is invoked.

Methods inherited from class com.sun.sgs.impl.protocol.simple.SimpleSgsProtocolImpl

close, disconnect, getDeliveries, getIdentity, getMaxMessageLength, isOpen, loginSuccess, monitorDisconnection, readNow, scheduleRead, toString, write, writeBuffer, writeNow

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

disconnect, getDeliveries, getMaxMessageLength

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Constructor Detail

SimpleSgsRelocationProtocolImpl

SimpleSgsRelocationProtocolImpl(ProtocolListener listener,
                                SimpleSgsProtocolAcceptor acceptor,
                                AsynchronousByteChannel byteChannel,
                                int readBufferSize)

Creates a new instance of this class.

Parameters:

listener - a protocol listener

acceptor - the SimpleSgsProtocol acceptor

byteChannel - a byte channel for the underlying connection

readBufferSize - the read buffer size

SimpleSgsRelocationProtocolImpl

protected SimpleSgsRelocationProtocolImpl(ProtocolListener listener,
                                          SimpleSgsProtocolAcceptor acceptor,
                                          AsynchronousByteChannel byteChannel,
                                          int readBufferSize,
                                          LoggerWrapper logger)

Constructs a new instance of this class. The subclass should invoke SimpleSgsProtocolImpl.scheduleRead() after constructing the instance to commence reading.

Parameters:

listener - a protocol listener

acceptor - the SimpleSgsProtocol acceptor

byteChannel - a byte channel for the underlying connection

readBufferSize - the read buffer size

logger - a logger for this instance

Method Detail

getProtocolVersion

protected byte getProtocolVersion()

Returns the SimpleSgsProtocol version supported by this implementation. This implementation returns the latest SimpleSgsProtocol version.

Overrides:

getProtocolVersion in class SimpleSgsProtocolImpl

Returns:

the SimpleSgsProtocol version supported by this implementation

sessionMessage

public void sessionMessage(ByteBuffer message,
                           Delivery delivery)

Sends the associated client the specified message in a manner that satisfies the specified delivery guarantee.

When possible, the message should be delivered using the most efficient means (e.g., protocol and transport) to satisfy the delivery guarantee. However, a stronger delivery guarantee may be used to deliver the message if this protocol only supports stronger delivery guarantees. If this protocol is not able to satisfy the specified delivery guarantee (e.g., only supports weaker delivery guarantees than the one specified), then a DeliveryNotSupportedException will be thrown.

The ByteBuffer is not modified and may be reused immediately after this method returns. Changes made to the buffer after this method returns will have no effect on the message sent to the client by this invocation.

Specified by:

sessionMessage in interface SessionProtocol

Overrides:

sessionMessage in class SimpleSgsProtocolImpl

Parameters:

message - a message

delivery - the delivery guarantee

channelJoin

public void channelJoin(String name,
                        BigInteger channelId,
                        Delivery delivery)

Notifies the associated client that it is joined to the channel with the specified name and channelId. This notification to the client must be delivered reliably.

Specified by:

channelJoin in interface SessionProtocol

Overrides:

channelJoin in class SimpleSgsProtocolImpl

Parameters:

name - a channel name

channelId - the channel's ID

delivery - the channel's delivery guarantee

channelLeave

public void channelLeave(BigInteger channelId)

Notifies the associated client that it is no longer a member of the channel with the specified channelId. This notification to the client must be delivered reliably.

Specified by:

channelLeave in interface SessionProtocol

Overrides:

channelLeave in class SimpleSgsProtocolImpl

Parameters:

channelId - a channel ID

channelMessage

public void channelMessage(BigInteger channelId,
                           ByteBuffer message,
                           Delivery delivery)

Sends the associated client the specified channel message for the channel with the specified channelId in a manner that satisfies the specified delivery guarantee.

When possible, the message should be delivered using the most efficient means (e.g., protocol and transport) to satisfy the delivery guarantee. However, a stronger delivery guarantee may be used to deliver the message if this protocol only supports stronger delivery guarantees. If this protocol is not able to satisfy the specified delivery guarantee (e.g., only supports weaker delivery guarantees than the one specified), then a DeliveryNotSupportedException will be thrown.

The ByteBuffer is not modified and may be reused immediately after this method returns. Changes made to the buffer after this method returns will have no effect on the message sent to the client by this invocation.

This implementation invokes the protected method writeBuffer with the channel protocol message (a ByteBuffer) and the specified delivery requirement. A subclass can override the writeBuffer method if it supports other delivery guarantees and can make use of alternate transports for those other delivery requirements.

Specified by:

channelMessage in interface SessionProtocol

Overrides:

channelMessage in class SimpleSgsProtocolImpl

Parameters:

channelId - a channel ID

message - a channel message

delivery - the channel's delivery guarantee

suspend

public void suspend(RequestCompletionHandler<Void> completionHandler)

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.

Specified by:

suspend in interface SessionRelocationProtocol

Parameters:

completionHandler - a completion handler

resume

public void resume()

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.

Specified by:

resume in interface SessionRelocationProtocol

relocate

public 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.

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.

Specified by:

relocate in interface SessionRelocationProtocol

Parameters:

descriptors - protocol descriptors for newNode

relocationKey - the key to be supplied to the new node

completionHandler - a completion handler

handleMessageReceived

protected void handleMessageReceived(byte opcode,
                                     MessageBuffer msg)

Handles v5 protocol messages (relocate and suspend), and delegates to the super class to handle the v4 protocol messages.

Overrides:

handleMessageReceived in class SimpleSgsProtocolImpl

Parameters:

opcode - the message opcode

msg - a message buffer containing the entire message, but with the position advanced to the payload (just after the opcode)