com.sun.sgs.impl.service.channel
Class ChannelWrapper

java.lang.Object
  com.sun.sgs.impl.service.channel.ChannelWrapper

All Implemented Interfaces:

Channel, ManagedObject, ManagedObjectRemoval, Serializable

 class ChannelWrapper
extends Object
implements Channel, Serializable, ManagedObjectRemoval

A wrapper for a ChannelImpl object that is returned to the application when a channel is created. A ChannelWrapper is handed back to the application instead of a direct reference to a ChannelImpl instance to avoid the possibility of the application removing the ChannelImpl instance from the data service and interfering with the channel service's persistent data.

When a ChannelWrapper instance is removed from the data service, the underlying channel is closed.

Constructor Summary

ChannelWrapper(ManagedReference<ChannelImpl> channelRef)
Constructs an instance with the specified channelRef.

Method Summary

boolean	equals(Object object)
BigInteger	getChannelId() Returns this channel's ID as a BigInteger.
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.
int	hashCode()
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<? extends ClientSession> sessions) Adds the specified client sessions to this channel.
Channel	leave(ClientSession session) Removes a client session from this channel.
Channel	leave(Set<? extends 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.
void	removingObject() Performs additional operations that are needed when this object is removed.
Channel	send(ByteBuffer message) Sends the message contained in the specified buffer to all client sessions joined to this channel.
Channel	send(ClientSession sender, ByteBuffer message) Sends the message contained in the specified buffer to all client sessions joined to this channel.
(package private) void	setChannelRef(ManagedReference<ChannelImpl> channelRef) Set the channel reference for this wrapper to the specified channelRef.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ChannelWrapper

ChannelWrapper(ManagedReference<ChannelImpl> channelRef)

Constructs an instance with the specified channelRef.

Parameters:

channelRef - a reference to a channel to wrap

Method Detail

getName

public String getName()

Returns the name bound to this channel.

Specified by:

getName in interface Channel

Returns:

the name bound to this channel

getDelivery

public Delivery getDelivery()

Returns the delivery guarantee of this channel.

Specified by:

getDelivery in interface Channel

Returns:

the delivery guarantee

hasSessions

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

Specified by:

hasSessions in interface Channel

Returns:

true if this channel has sessions joined to it, otherwise returns false

getSessions

public 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 recent changes (in the current transaction or another recent transaction) to the channel's membership. 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.

Specified by:

getSessions in interface Channel

Returns:

an iterator for the sessions joined to this channel

join

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

Specified by:

join in interface Channel

Parameters:

session - a client session

Returns:

this channel

join

public Channel join(Set<? extends 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.

Specified by:

join in interface Channel

Parameters:

sessions - a set of client sessions

Returns:

this channel

leave

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

Specified by:

leave in interface Channel

Parameters:

session - a client session

Returns:

this channel

leave

public Channel leave(Set<? extends 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.

Specified by:

leave in interface Channel

Parameters:

sessions - a set of client sessions

Returns:

this channel

leaveAll

public Channel leaveAll()

Removes all client sessions from this channel.

Specified by:

leaveAll in interface Channel

Returns:

this channel

send

public Channel send(ByteBuffer message)

Sends the message contained in the specified buffer to all client sessions joined to this channel. 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.

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())

Specified by:

send in interface Channel

Parameters:

message - a message

Returns:

this channel

send

public Channel send(ClientSession sender,
                    ByteBuffer message)

Sends the message contained in the specified buffer to all client sessions joined to this channel. 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.

This send method, which has a sender argument, is used to forward a message to a channel from the channel's ChannelListener. When the channel's listener receives a message via its receivedMessage method, the listener can perform access control operations on the sender, alter the message content, and/or perform other operations before (optionally) using this method, specifying the given sender, to forward the message to the channel.

If sender specified to this method is non-null, it must be the sender supplied to the ChannelListener's receivedMessage method. If 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. If the sender specified to this method is non-null and is not the sender supplied to the ChannelListener, then the channel message may not get delivered to the channel.

If the sender is null, the message will be forwarded to the channel.

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().

Specified by:

send in interface Channel

Parameters:

sender - the sending client session, or null

message - a message

Returns:

this channel

removingObject

public void removingObject()

Performs additional operations that are needed when this object is removed. The application removed the wrapper, so close the channel, indicating that the the channel name mapping should be removed as well.

Specified by:

removingObject in interface ManagedObjectRemoval

getChannelId

public BigInteger getChannelId()

Returns this channel's ID as a BigInteger.

Returns:

this channel's ID as a BigInteger

equals

public boolean equals(Object object)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

setChannelRef

void setChannelRef(ManagedReference<ChannelImpl> channelRef)

Set the channel reference for this wrapper to the specified channelRef. The underlying channel reference changes when the application invokes leaveAll on the channel, which closes and removes the old channel (except for the channel's name binding) and reuses the existing wrapper, replacing the previous channel reference with a reference to the "next generation" channel of the same name.

Parameters:

channelRef - the new channel reference