com.sun.media.jsdt
Interface Channel


public abstract interface Channel
extends Manageable

JSDT Channel interface.

Since:
JSDT 1.0
Version:
1.5 - 7th January 1999
Author:
Rich Burridge

Field Summary
static int HIGH_PRIORITY
          Channel Data high priority value.
static int LOW_PRIORITY
          Channel Data top priority value.
static int MAX_PRIORITIES
          The maximum number of Data priorities.
static int MEDIUM_PRIORITY
          Channel Data medium priority value.
static int READONLY
          The Channel read-only value.
static int READWRITE
          The Channel read/write value.
static int TOP_PRIORITY
          Channel Data top priority value.
static int WRITEONLY
          The Channel write-only value.
 
Fields inherited from class java.io.Serializable
serialVersionUID
 
Method Summary
 void addChannelListener(ChannelListener listener)
           add the specified Channel listener to receive Channel events for this Channel.
 void addConsumer(Client client, ChannelConsumer consumer)
           add a new ChannelConsumer for this Client.
 boolean dataAvailable(Client client)
           tests whether there is Data available to read on this Channel.
 boolean isOrdered()
           returns whether this is an ordered channel.
 boolean isReliable()
           test whether this is a reliable channel.
 void join(Client client, int mode)
           join a Client to a Channel in the given mode.
 java.lang.String[] listConsumerNames()
           list the names of the Clients who are currently consuming this Channel.
 Data receive(Client client)
           is used to receive Data from other Clients joined to this Channel.
 Data receive(Client client, long timeout)
           is used to receive Data from other Clients joined to this Channel.
 void removeChannelListener(ChannelListener listener)
           removes the specified Channel listener so that it no longer receives Channel events for this Channel.
 void removeConsumer(Client client, ChannelConsumer consumer)
           remove a ChannelConsumer from this Client for this Channel.
 void sendToAll(Client sendingClient, Data data)
           is used to send Data to all Clients consuming this Channel.
 void sendToClient(Client sendingClient, java.lang.String receivingClientName, Data data)
           is used to send Data to a single Client consuming this Channel.
 void sendToOthers(Client sendingClient, Data data)
           is used to send Data to other Clients consuming this Channel.
 
Methods inherited from interface com.sun.media.jsdt.Manageable
destroy, disableListenerEvents, disableManagerEvents, enableListenerEvents, enableManagerEvents, expel, getName, getSession, invite, isManaged, join, leave, listClientNames
 

Field Detail

TOP_PRIORITY

public static final int TOP_PRIORITY
Channel Data top priority value.

HIGH_PRIORITY

public static final int HIGH_PRIORITY
Channel Data high priority value.

MEDIUM_PRIORITY

public static final int MEDIUM_PRIORITY
Channel Data medium priority value.

LOW_PRIORITY

public static final int LOW_PRIORITY
Channel Data top priority value.

MAX_PRIORITIES

public static final int MAX_PRIORITIES
The maximum number of Data priorities.

READONLY

public static final int READONLY
The Channel read-only value.

WRITEONLY

public static final int WRITEONLY
The Channel write-only value.

READWRITE

public static final int READWRITE
The Channel read/write value.
Method Detail

addChannelListener

public void addChannelListener(ChannelListener listener)
                        throws ConnectionException,
                               NoSuchChannelException,
                               NoSuchSessionException,
                               TimedOutException
add the specified Channel listener to receive Channel events for this Channel.
Parameters:
listener - the Channel listener.
Throws:
ConnectionException - if a connection error occured.
NoSuchChannelException - if this Channel doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
TimedOutException - if no reply was received for this operation in the given timeout period.

removeChannelListener

public void removeChannelListener(ChannelListener listener)
                           throws ConnectionException,
                                  NoSuchChannelException,
                                  NoSuchListenerException,
                                  NoSuchSessionException,
                                  TimedOutException
removes the specified Channel listener so that it no longer receives Channel events for this Channel.
Parameters:
listener - the Channel listener.
Throws:
ConnectionException - if a connection error occured.
NoSuchChannelException - if this Channel doesn't exist.
NoSuchListenerException - if this ChannelListener doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
TimedOutException - if no reply was received for this operation in the given timeout period.

addConsumer

public void addConsumer(Client client,
                        ChannelConsumer consumer)
                 throws ConnectionException,
                        InvalidClientException,
                        NoSuchChannelException,
                        NoSuchClientException,
                        NoSuchConsumerException,
                        NoSuchSessionException,
                        PermissionDeniedException,
                        TimedOutException
add a new ChannelConsumer for this Client. The Client's ChannelConsumers gets informed when there is Data available on a Channel.
Parameters:
client - the Client to associate this ChannelConsumer with.
consumer - the new ChannelConsumer for this client.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchChannelException - if this Channel doesn't exist.
NoSuchClientException - if this Client doesn't exist.
NoSuchConsumerException - if this ChannelConsumer doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client doesn't have permission for this operation. This would occur if the Client had joined the Channel in write-only mode.
TimedOutException - if no reply was received for this operation in the given timeout period.

removeConsumer

public void removeConsumer(Client client,
                           ChannelConsumer consumer)
                    throws ConnectionException,
                           InvalidClientException,
                           NoSuchChannelException,
                           NoSuchClientException,
                           NoSuchConsumerException,
                           NoSuchSessionException,
                           PermissionDeniedException,
                           TimedOutException
remove a ChannelConsumer from this Client for this Channel. The ChannelConsumer will no longer get informed when there is Data available on this channel.
Parameters:
client - the Client to associate this ChannelConsumer with.
consumer - the ChannelConsumer to remove from this Client.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchChannelException - if this Channel doesn't exist.
NoSuchClientException - if this Client doesn't exist.
NoSuchConsumerException - if this ChannelConsumer doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client doesn't have permission for this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.

listConsumerNames

public java.lang.String[] listConsumerNames()
                                     throws ConnectionException,
                                            NoSuchChannelException,
                                            NoSuchSessionException,
                                            TimedOutException
list the names of the Clients who are currently consuming this Channel.
Returns:
a sorted array of names of Clients currently comsuming this Channel. This array will be of zero length if there are no Clients currently consuming this Channel.
Throws:
ConnectionException - if a connection error occured.
NoSuchChannelException - if this Channel doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
TimedOutException - if no reply was received for this operation in the given timeout period.
Since:
JSDT 1.3

isReliable

public boolean isReliable()
test whether this is a reliable channel.
Returns:
true if this is a reliable channel; false if not.

isOrdered

public boolean isOrdered()
returns whether this is an ordered channel.
Returns:
true if this is an ordered channel; false if not.

join

public void join(Client client,
                 int mode)
          throws ConnectionException,
                 InvalidClientException,
                 NoSuchChannelException,
                 NoSuchClientException,
                 NoSuchSessionException,
                 PermissionDeniedException,
                 NameInUseException,
                 TimedOutException
join a Client to a Channel in the given mode. This is a prerequesite for sending and receiving Data sent over the Channel.

If this is a managed Channel, then the Client is authenticated to determine if it is permitted to do this operation.

Parameters:
client - the Client wishing to join this Channel.
mode - the mode which can be one of, READONLY, WRITEONLY or READWRITE.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchChannelException - if this Channel doesn't exist.
NoSuchClientException - if this Client doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client doesn't have permission for this operation.
NameInUseException - if a Client with this name is already joined to this Manageable object.
TimedOutException - if no reply was received for this operation in the given timeout period.

receive

public Data receive(Client client)
             throws ConnectionException,
                    InvalidClientException,
                    NoSuchClientException,
                    NoSuchSessionException,
                    PermissionDeniedException,
                    TimedOutException
is used to receive Data from other Clients joined to this Channel.

It will block if there is no Data to read. The dataAvailable method can be used to check if there is Data that can be received on this channel.

Parameters:
client - identifies the client wishing to receive data from this channel. This client must already be successfully joined to this channel.
Returns:
the next Data object available on this channel.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchClientException - if the client given doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client doesn't have permission for this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.

receive

public Data receive(Client client,
                    long timeout)
             throws ConnectionException,
                    InvalidClientException,
                    NoSuchClientException,
                    NoSuchSessionException,
                    PermissionDeniedException,
                    TimedOutException
is used to receive Data from other Clients joined to this Channel.

If Data is immediately available then it will return with it, else it will wait until the timeout period, specified by the timeout argument in milliseconds, has elapsed. If no Data is available at this time, it will return null. Note that if Data becomes available during the timeout period, this method will be woken up and that Data is immediately returned.

Parameters:
client - identifies the client wishing to receive data from this channel. This client must already be successfully joined to this channel.
timeout - the maximum time to wait in milliseconds.
Returns:
the next Data object available on this channel, or null if the timeout period has expired, and there is currently no Data available.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchClientException - if the client given doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client doesn't have permission for this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.

dataAvailable

public boolean dataAvailable(Client client)
                      throws ConnectionException,
                             InvalidClientException,
                             NoSuchClientException,
                             NoSuchSessionException,
                             PermissionDeniedException,
                             TimedOutException
tests whether there is Data available to read on this Channel.
Parameters:
client - identifies the client wishing to check if there is data available to receive on this channel. This client must already be successfully joined to this channel.
Returns:
true if Data is available; false if not.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchClientException - if the client given doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client doesn't have permission for this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.

sendToAll

public void sendToAll(Client sendingClient,
                      Data data)
               throws ConnectionException,
                      InvalidClientException,
                      NoSuchChannelException,
                      NoSuchClientException,
                      NoSuchSessionException,
                      PermissionDeniedException,
                      TimedOutException
is used to send Data to all Clients consuming this Channel. If the sender is a consumer of this Channel, then it too will receive the Data.

Data from each sender sent at the same priority on the same Channel arrives at a given receiver in the same order it was sent but may have other sender Data interleaved differently.

Parameters:
sendingClient - the Client sending the Data.
data - the Data being sent over this Channel.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchChannelException - if this Channel doesn't exist.
NoSuchClientException - if this Client doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client doesn't have permission for this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.

sendToOthers

public void sendToOthers(Client sendingClient,
                         Data data)
                  throws ConnectionException,
                         InvalidClientException,
                         NoSuchChannelException,
                         NoSuchClientException,
                         NoSuchSessionException,
                         PermissionDeniedException,
                         TimedOutException
is used to send Data to other Clients consuming this Channel. The sender (irrespective of whether it's a consumer of this channel) will not receive the Data.

Data from each sender sent at the same priority on the same Channel arrives at a given receiver in the same order it was sent but may have other sender Data interleaved differently.

Parameters:
sendingClient - the Client sending the Data.
data - the Data being sent over this Channel.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchChannelException - if this Channel doesn't exist.
NoSuchClientException - if this Client doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client doesn't have permission for this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.

sendToClient

public void sendToClient(Client sendingClient,
                         java.lang.String receivingClientName,
                         Data data)
                  throws ConnectionException,
                         InvalidClientException,
                         NoSuchChannelException,
                         NoSuchClientException,
                         NoSuchConsumerException,
                         NoSuchSessionException,
                         PermissionDeniedException,
                         TimedOutException
is used to send Data to a single Client consuming this Channel.
Parameters:
sendingClient - the Client sending the Data.
receivingClient - the name of the Client receiving the Data.
data - the Data being sent over this Channel.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchChannelException - if this Channel doesn't exist.
NoSuchClientException - if this Client doesn't exist.
NoSuchConsumerException - if this Client doesn't have a ChannelConsumer associated with it.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client doesn't have permission for this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.