com.sun.sgs.app
Interface ChannelManager


public interface ChannelManager

Manager for creating and obtaining channels. A Channel is a communication group consisting of multiple client sessions and the server.

A Channel is created with a Delivery guarantee. Messages sent on a channel are delivered in a manner that satisfies the channel's delivery guarantee. 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.

The delivery guarantee of a channel cannot be changed. If different delivery guarantees are needed, then different channels should be used for communication.

See Also:
AppContext.getChannelManager()

Method Summary
 Channel createChannel(String name, ChannelListener listener, Delivery delivery)
          Creates a new channel with the specified listener and delivery guarantee, binds it to the specified name, and returns it.
 Channel getChannel(String name)
          Returns an existing channel with the specified name.
 

Method Detail

createChannel

Channel createChannel(String name,
                      ChannelListener listener,
                      Delivery delivery)
Creates a new channel with the specified listener and delivery guarantee, binds it to the specified name, and returns it.

If the specified listener is null, then any messages sent on the returned channel by any client session will be automatically forwarded, unfiltered, to all channel members.

If the specified listener is non-null, then when any client session sends a message on the returned channel, the specified listener's receivedMessage method is invoked with the channel, client session and the message. The specified listener is not invoked for messages that the server sends on the channel via the channel's send method. If the specified listener is non-null, then it must also be Serializable.

Supplying a non-null listener (although not required) is strongly suggested. A listener's receivedMessage method provides an opportunity for an application to intervene when a client sends a channel message, to perform access control, filtering, or take other application-specific action on such channel messages.

If a non-null listener is provided, it is strongly suggested that a different listener instance be provided for each channel created, in order to reduce the possible contention on channel listeners.

Messages sent on the returned channel are delivered in a manner that satisfies the minimum requirements of the specified delivery guarantee.

Parameters:
name - a name
listener - a channel listener, or null
delivery - a delivery guarantee
Returns:
a new channel bound to the specified name
Throws:
IllegalArgumentException - if the specified listener is non-null and is not serializable
ResourceUnavailableException - if there are not enough resources to create the channel
NameExistsException - if a channel is already bound to the specified name
TransactionException - if the operation failed because of a problem with the current transaction

getChannel

Channel getChannel(String name)
Returns an existing channel with the specified name.

Parameters:
name - a channel name
Returns:
an existing channel bound to the specified name
Throws:
NameNotBoundException - if a channel is not bound to the specified name
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