com.sun.sgs.app
Interface Channel

All Superinterfaces:
ManagedObject

public interface Channel
extends ManagedObject

Interface representing a communication group, a Channel, consisting of multiple client sessions. Classes that implement Channel must also implement Serializable.

A channel is created by invoking the ChannelManager.createChannel method with a name, a ChannelListener, and a Delivery guarantee. A ClientSession can be added or removed from a channel using that Channel's join and leave methods respectively. All client sessions can be removed from a channel by invoking leaveAll on the channel. To explicitly close a Channel, remove the Channel object from the data manager using the DataManager.removeObject method.

The server can send a message to all client sessions joined to a channel by using the send method. Note that the methods of this interface are invoked within the context of an executing Task; as a result, a message sent to client sessions using the send method will not be sent until after its corresponding task completes.

Messages sent on a channel are delivered in a manner that satisfies the channel's delivery guarantee, specified at creation time. When possible, channel messages are delivered using the most efficient means to satisfy the delivery guarantee. However, a stronger delivery guarantee may be used to deliver the message if the underlying protocol only supports stronger delivery guarantees. A client session can not be joined to a channel if that client session does not support a protocol satisfying the minimum requirements of the channel's delivery guarantee.

A client session joined to one or more channels may become disconnected due to the client logging out or due to other factors such as forced disconnection or network failure. If a client session becomes disconnected, then that client session is removed from each channel that it is a member of.

When the application is finished using a channel, the application should remove the channel from the data manager, which closes the channel and releases all resources associated with the channel.

See Also:
ChannelManager.createChannel

Method Summary
 Delivery getDelivery()
          Returns the delivery guarantee of this channel.
 String getName()
          Returns the name bound to this channel.
 Iterator<ClientSession> getSessions()
          Returns an iterator for the client sessions joined to this channel.
 boolean hasSessions()
          Returns true if this channel has client sessions joined to it, otherwise returns false.
 Channel join(ClientSession session)
          Adds a client session to this channel.
 Channel join(Set<ClientSession> sessions)
          Adds the specified client sessions to this channel.
 Channel leave(ClientSession session)
          Removes a client session from this channel.
 Channel leave(Set<ClientSession> sessions)
          Removes the specified client sessions from this channel, If a session in the specified set is not joined to this channel, then no action for that session is taken.
 Channel leaveAll()
          Removes all client sessions from this channel.
 Channel send(ClientSession sender, ByteBuffer message)
          Sends the message contained in the specified buffer to all client sessions joined to this channel.
 

Method Detail

getName

String getName()
Returns the name bound to this channel.

Returns:
the name bound to this channel
Throws:
IllegalStateException - if this channel is closed
TransactionException - if the operation failed because of a problem with the current transaction

getDelivery

Delivery getDelivery()
Returns the delivery guarantee of this channel.

Returns:
the delivery guarantee
Throws:
IllegalStateException - if this channel is closed
TransactionException - if the operation failed because of a problem with the current transaction

hasSessions

boolean hasSessions()
Returns true if this channel has client sessions joined to it, otherwise returns false.

The returned result may not reflect changes to the membership that occurred in the current transaction. Such membership changes may be handled asynchronously, after the task making the changes completes.

Returns:
true if this channel has sessions joined to it, otherwise returns false
Throws:
IllegalStateException - if this channel is closed
TransactionException - if the operation failed because of a problem with the current transaction

getSessions

Iterator<ClientSession> getSessions()
Returns an iterator for the client sessions joined to this channel. The returned iterator may only be used in the task that this method was invoked from.

The returned iterator may not reflect changes to the membership that occurred in the current transaction. Such membership changes may be handled asynchronously, after the task making the changes completes. Therefore, the iterator may not include sessions that have been recently joined to the channel, or may include sessions that have recently left the channel (by being explicitly removed from the channel, or by being disconnected).

Note: This operation may be expensive, so it should be used judiciously.

Returns:
an iterator for the sessions joined to this channel
Throws:
IllegalStateException - if this channel is closed
TransactionException - if the operation failed because of a problem with the current transaction

join

Channel join(ClientSession session)
Adds a client session to this channel. If the specified session is already joined to this channel, then no action is taken. If the client session does not support a protocol that satisfies the minimum requirements of the channel's delivery guarantee, then DeliveryNotSupportedException will be thrown.

Parameters:
session - a client session
Returns:
this channel
Throws:
IllegalStateException - if this channel is closed
DeliveryNotSupportedException - if the session does not support the minimum requirements of this channel's delivery guarantee
ResourceUnavailableException - if there are not enough resources to join the channel
TransactionException - if the operation failed because of a problem with the current transaction

join

Channel join(Set<ClientSession> sessions)
Adds the specified client sessions to this channel. If any client session in the specified set does not support a protocol that satisfies the minimum requirements of the channel's delivery guarantee, then DeliveryNotSupportedException will be thrown.

Parameters:
sessions - a set of client sessions
Returns:
this channel
Throws:
IllegalStateException - if this channel is closed
DeliveryNotSupportedException - if any session does not support the minimum requirements of this channel's delivery guarantee
ResourceUnavailableException - if there are not enough resources to join the channel
TransactionException - if the operation failed because of a problem with the current transaction

leave

Channel leave(ClientSession session)
Removes a client session from this channel. If the specified session is not joined to this channel, then no action is taken.

Parameters:
session - a client session
Returns:
this channel
Throws:
IllegalStateException - if this channel is closed
TransactionException - if the operation failed because of a problem with the current transaction

leave

Channel leave(Set<ClientSession> sessions)
Removes the specified client sessions from this channel, If a session in the specified set is not joined to this channel, then no action for that session is taken.

Parameters:
sessions - a set of client sessions
Returns:
this channel
Throws:
IllegalStateException - if this channel is closed
TransactionException - if the operation failed because of a problem with the current transaction

leaveAll

Channel leaveAll()
Removes all client sessions from this channel.

Returns:
this channel
Throws:
IllegalStateException - if this channel is closed
TransactionException - if the operation failed because of a problem with the current transaction

send

Channel send(ClientSession sender,
             ByteBuffer message)
Sends the message contained in the specified buffer to all client sessions joined to this channel. If no sessions are joined to this channel, then no action is taken. 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.

If the specified sender is non-null and that sender is not a member of this channel when the message is processed to be sent, then the message will not be forwarded to the channel for delivery.

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 sent to the channel by this invocation.

The maximum length of a message that can be sent over the channel is dependent on the maximum message length supported by all joined client sessions. (See: ClientSession.getMaxMessageLength())

Parameters:
sender - the sending client session, or null
message - a message
Returns:
this channel
Throws:
IllegalStateException - if this channel is closed
IllegalArgumentException - if the channel would be unable to send the specified message because it exceeds a size limit
MessageRejectedException - if there are not enough resources to send the specified message
TransactionException - if the operation failed because of a problem with the current transaction

Project Darkstar, Version 0.9.9.6
2009-05-08 15:39:40

Copyright © 2007-2009 Sun Microsystems, Inc. All rights reserved