com.sun.sgs.protocol
Interface SessionProtocol

All Superinterfaces:

Channel, Closeable

All Known Subinterfaces:

SessionRelocationProtocol

All Known Implementing Classes:

SimpleSgsProtocolImpl, SimpleSgsRelocationProtocolImpl

public interface SessionProtocol
extends Channel

A protocol for sending session messages and channel messages to a client.

The implementation of the protocol is only responsible for the formating and sending of messages to the client. Unless otherwise noted, the implementation is not required to perform validity checks on method arguments. For calls that result in messages sent to a client, is up to the caller to make sure arguments contain valid information. It is up to the client to decide what it wants to do if it receives messages that seem nonsensical.

If a protocol specification requires that a login acknowledgment be delivered to a client before any other protocol messages, the protocol must implement this requirement. It is possible that a caller may request that other messages be sent before a login acknowledgment, and if the protocol requires, these messages should be enqueued until the login acknowledgment has been sent to the client.

Nested Class Summary

static class

SessionProtocol.DisconnectReason Reasons why a server disconnects a session.

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.
void	disconnect(SessionProtocol.DisconnectReason reason) Disconnects the associated session for the specified reason.
Set<Delivery>	getDeliveries() Returns a set containing the delivery guarantees supported by this protocol.
int	getMaxMessageLength() Returns the maximum length, in bytes, of the buffers passed as the message parameters to the sessionMessage and channelMessage methods.
void	sessionMessage(ByteBuffer message, Delivery delivery) Sends the associated client the specified message in a manner that satisfies the specified delivery guarantee.

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Method Detail

getDeliveries

Set<Delivery> getDeliveries()

Returns a set containing the delivery guarantees supported by this protocol. The returned set is serializable.

Returns:

a set containing the supported delivery guarantees

getMaxMessageLength

int getMaxMessageLength()

Returns the maximum length, in bytes, of the buffers passed as the message parameters to the sessionMessage and channelMessage methods.

Returns:

the maximum message length

sessionMessage

void sessionMessage(ByteBuffer message,
                    Delivery delivery)
                    throws IOException

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.

Parameters:

message - a message

delivery - the delivery guarantee

Throws:

IllegalArgumentException - if the message size is greater than getMaxMessageLength()

IllegalStateException - if the associated session was requested to suspend messages

DeliveryNotSupportedException - if the specified delivery guarantee cannot be satisfied by this protocol

IOException - if an I/O error occurs

channelJoin

void channelJoin(String name,
                 BigInteger channelId,
                 Delivery delivery)
                 throws IOException

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.

Parameters:

name - a channel name

channelId - the channel's ID

delivery - the channel's delivery guarantee

Throws:

IllegalStateException - if the associated session was requested to suspend messages (explicitly or due to relocation)

DeliveryNotSupportedException - if the specified delivery guarantee cannot be satisfied by this protocol

IOException - if an I/O error occurs

channelLeave

void channelLeave(BigInteger channelId)
                  throws IOException

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.

Parameters:

channelId - a channel ID

Throws:

IllegalStateException - if the associated session was requested to suspend messages (explicitly or due to relocation)

IOException - if an I/O error occurs

channelMessage

void channelMessage(BigInteger channelId,
                    ByteBuffer message,
                    Delivery delivery)
                    throws IOException

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.

Parameters:

channelId - a channel ID

message - a channel message

delivery - the channel's delivery guarantee

Throws:

IllegalArgumentException - if the message size is greater than getMaxMessageLength()

IllegalStateException - if the associated session was requested to suspend messages (explicitly or due to relocation)

DeliveryNotSupportedException - if the specified delivery guarantee cannot be satisfied by this protocol

IOException - if an I/O error occurs

disconnect

void disconnect(SessionProtocol.DisconnectReason reason)
                throws IOException

Disconnects the associated session for the specified reason. The protocol may send a message to the associated client indicating the reason for the disconnection, or the protocol may close the connection immediately. Any underlying connection(s) should be closed in a timely fashion.

Parameters:

reason - the reason for disconnection

Throws:

IOException - if an I/O error occurs