com.sun.sgs.impl.service.channel
Interface ChannelServer

All Superinterfaces:

Remote

public interface ChannelServer
extends Remote

A remote interface for communicating channel events and other channel-related requests between peer channel services.

Each channel event (join, leave, send, close) is assigned a timestamp when the event is added to the channel's event queue. An event queue's current timestamp records the timestamp of the latest send event that the queue has started to process. The initial event timestamp is 1. A send event increments the next timestamp, so all future join and leave events will have a later timestamp. Because only a send event increments the next timestamp, join, leave, and send requests may share the same timestamp. If a send event at timestamp t is followed directly by a series of join and leave events, the join and leave events will all have the later timestamp t+1. The next send event for the channel will also have timestamp t+1.

If a session becomes a channel member at a given timestamp t, then it should receive all channel messages with a timestamp greater than or equal to t. If a session leaves a channel at a given timestamp t, the session should receive channel messages up to timestamp t-1, but should not receive channel messages greater than or equal to timestamp t.

A channel server that receives a channel event notification (for delivery to a client session) uses the event's timestamp to determine whether the event needs to be delivered to a local session. The timestamp is used to determine duplicate events (in the case of coordinator recovery), and if a client session relocates, the session's current timestamp for a channel can be used to determine whether the session missed any channel messages while relocating.

Nested Class Summary

static class

ChannelServer.MembershipStatus Membership status.

Method Summary

void	close(BigInteger channelRefId, long timestamp) Notifies this server that the channel with the specified channelRefId is closed.
BigInteger[]	getSessions(BigInteger channelRefId) Returns an array containing the client session ID of each client session on this node that is a member of the channel with the specified channelRefId.
ChannelServer.MembershipStatus	isMember(BigInteger channelRefId, BigInteger sessionRefId) If the session with the specified sessionRefId is connected to the local node, returns ChannelServer.MembershipStatus.MEMBER if the session is a member of the channel with the specified channelRefId and returns ChannelServer.MembershipStatus.NON_MEMBER if the session is not a member of the channel.
boolean	join(String name, BigInteger channelRefId, byte deliveryOrdinal, long timestamp, BigInteger sessionRefId) Notifies this server that the locally-connected session with the specified sessionRefId has joined the channel with the specified name and channelRefId.
boolean	leave(BigInteger channelRefId, long timestamp, BigInteger sessionRefId) Notifies this server that the locally-connected session with the specified sessionRefId has left the channel with the specified channelRefId.
void	relocateChannelMemberships(BigInteger sessionRefId, long oldNodeId, BigInteger[] channelRefIds, byte[] deliveryOrdinals, long[] msgTimestamps) Notifies this server that the client session with the specified sessionRefId is relocating from the node (specified by oldNodeId) to the new node (i.e., the local node) and that the session's channel memberships should be updated accordingly.
void	relocateChannelMembershipsCompleted(BigInteger sessionRefId, long newNodeId) Notifies this server that the channel server on the node specified by newNodeId has completed updating the channel memberships for the client session with the specified sessionRefId in preparation for the session's relocation to the new node.
void	send(BigInteger channelRefId, byte[] message, long timestamp) Sends the specified message to all locally-connected sessions that are members of the channel with the specified channelRefId.
void	serviceEventQueue(BigInteger channelRefId) Notifies this server that it should service the event queue of the channel with the specified channelRefId.

Method Detail

serviceEventQueue

void serviceEventQueue(BigInteger channelRefId)
                       throws IOException

Notifies this server that it should service the event queue of the channel with the specified channelRefId.

Parameters:

channelRefId - a channel ID

Throws:

IOException - if a communication problem occurs while invoking this method

isMember

ChannelServer.MembershipStatus isMember(BigInteger channelRefId,
                                        BigInteger sessionRefId)
                                        throws IOException

If the session with the specified sessionRefId is connected to the local node, returns ChannelServer.MembershipStatus.MEMBER if the session is a member of the channel with the specified channelRefId and returns ChannelServer.MembershipStatus.NON_MEMBER if the session is not a member of the channel. If the session is not connected to the local node, then this method returns ChannelServer.MembershipStatus.UNKNOWN.

Parameters:

channelRefId - a channel ID

sessionRefId - a session ID

Returns:

the membership status of the session with the specified sessionRefId for the channel with the specified channelRefId

Throws:

IOException - if a communication problem occurs while invoking this method

join

boolean join(String name,
             BigInteger channelRefId,
             byte deliveryOrdinal,
             long timestamp,
             BigInteger sessionRefId)
             throws IOException

Notifies this server that the locally-connected session with the specified sessionRefId has joined the channel with the specified name and channelRefId.

Parameters:

name - a channel name

channelRefId - a channel ID

deliveryOrdinal - the channel's delivery requirement, as a Delivery ordinal

timestamp - the timestamp of the last channel message sent

sessionRefId - a session ID

Returns:

true if the join succeeded (either was delivered or enqueued for a relocating session), and false if the session is not locally connected and is not known to be relocating

Throws:

IOException - if a communication problem occurs while invoking this method

leave

boolean leave(BigInteger channelRefId,
              long timestamp,
              BigInteger sessionRefId)
              throws IOException

Notifies this server that the locally-connected session with the specified sessionRefId has left the channel with the specified channelRefId.

Parameters:

channelRefId - a channel ID

timestamp - the timestamp of the last channel message sent

sessionRefId - a session ID

Returns:

true if the leave succeeded (either was delivered or enqueued for a relocating session), and false if the session is not locally connected and is not known to be relocating

Throws:

IOException - if a communication problem occurs while invoking this method

getSessions

BigInteger[] getSessions(BigInteger channelRefId)
                         throws IOException

Returns an array containing the client session ID of each client session on this node that is a member of the channel with the specified channelRefId.

Parameters:

channelRefId - a channel ID

Returns:

an array of members' session IDs

Throws:

IOException - if a communication problem occurs while invoking this method

send

void send(BigInteger channelRefId,
          byte[] message,
          long timestamp)
          throws IOException

Sends the specified message to all locally-connected sessions that are members of the channel with the specified channelRefId.

Parameters:

channelRefId - a channel ID

message - a channel message

timestamp - the message's timestamp

Throws:

IOException - if a communication problem occurs while invoking this method

relocateChannelMemberships

void relocateChannelMemberships(BigInteger sessionRefId,
                                long oldNodeId,
                                BigInteger[] channelRefIds,
                                byte[] deliveryOrdinals,
                                long[] msgTimestamps)
                                throws IOException

Notifies this server that the client session with the specified sessionRefId is relocating from the node (specified by oldNodeId) to the new node (i.e., the local node) and that the session's channel memberships should be updated accordingly. The channelRefIds array contains the channel ID of each channel that the client session belongs to. The deliveryOrdinals array contains the delivery ordinal of each corresponding channel. The msgTimestamps array contains the timestamp of the latest message received by the specified session (at the point that relocation started) for each corresponding channel.

This server must update its local channel membership cache for the specified session and add persistent membership information to indicate that the specified session on the local node is now joined to each channel. When the cache and persistent membership information is updated, the relocateChannelMembershipsCompleted method should be invoked on the old node's ChannelServer with the specified sessionRefId and the new node's ID.

Parameters:

sessionRefId - the ID of a client session relocating to the local node

oldNodeId - the ID of the node the session is relocating from

channelRefIds - an array that contains the channel ID of each channel that the client session is a member of

deliveryOrdinals - an array that contains the delivery ordinal of each channel that the client session is a member of

msgTimestamps - an array that contains the message timestamp of each channel that the client session is a member of

Throws:

IOException - if a communication problem occurs while invoking this method

relocateChannelMembershipsCompleted

void relocateChannelMembershipsCompleted(BigInteger sessionRefId,
                                         long newNodeId)
                                         throws IOException

Notifies this server that the channel server on the node specified by newNodeId has completed updating the channel memberships for the client session with the specified sessionRefId in preparation for the session's relocation to the new node. This method is invoked when the work associated with a previous invocation to relocateChannelMemberships on the new node's channel server is complete. This channel server should clean up any remaining persistent channel membership information for the session on the old node (i.e., the local node).

Parameters:

sessionRefId - the ID of a relocating client session

newNodeId - ID of the node the session is relocating to

Throws:

IOException - if a communication problem occurs while invoking this method

close

void close(BigInteger channelRefId,
           long timestamp)
           throws IOException

Notifies this server that the channel with the specified channelRefId is closed.

Parameters:

channelRefId - a channel ID

timestamp - the timestamp of the last channel message sent

Throws:

IOException - if a communication problem occurs while invoking this method