com.sun.media.jsdt.impl
Class ChannelImpl

java.lang.Object
  |
  +--com.sun.media.jsdt.impl.JSDTObject
        |
        +--com.sun.media.jsdt.impl.ManageableImpl
              |
              +--com.sun.media.jsdt.impl.ChannelImpl

public class ChannelImpl
extends ManageableImpl
implements com.sun.media.jsdt.Channel

JSDT Channel (implementation) class.

Version:
1.5 - 16th February 1999
Author:
Rich Burridge
See Also:
Serialized Form

Field Summary
static char D_All
          Send Data to all consumers (including self) of the Channel.
static char D_Client
          Send Data to a specific consumer of the Channel.
static char D_Others
          Send Data to all other consumers of the Channel.
static char M_Channel
          To signify a manageable object of type Channel.
protected  boolean ordered
          Indicates whether data sent over this channel will be ordered.
 AbstractChannelProxy po
          Handle to client-side proxy.
protected  boolean reliable
          Indicates if data sent over this channel will be reliably delivered.
protected  SessionImpl session
          The session that this channel belongs to.
 AbstractChannelServer so
          Handle to server-side object.
 
Fields inherited from class com.sun.media.jsdt.impl.ManageableImpl
mpo, name, objectType
 
Fields inherited from class com.sun.media.jsdt.impl.JSDTObject
giveTime, httpTunnelPort, maxQueueSize, maxThreadPoolSize, pingPeriod, registryAddress, registryPort, registryTime, showMessage, showStack, socketFactoryClass, SSLCipher, timeoutPeriod, TTL, versionString
 
Constructor Summary
ChannelImpl(boolean isServer, java.lang.String name, SessionImpl session, boolean reliable, boolean ordered)
           Channel the constructor for the Channel class.
 
Method Summary
 void addChannelListener(com.sun.media.jsdt.event.ChannelListener listener)
           add the specified Channel listener to receive Channel events for this Channel.
 void addConsumer(com.sun.media.jsdt.Client client, com.sun.media.jsdt.ChannelConsumer consumer)
           add a new ChannelConsumer for this Client.
 boolean dataAvailable(com.sun.media.jsdt.Client client)
           tests whether there is Data available to read on this Channel.
 boolean isOrdered()
           isOrdered returns whether this is an ordered channel.
 boolean isReliable()
           isReliable test whether this is a reliable channel.
 void join(com.sun.media.jsdt.Client client)
           join is used by a client to join an appropriate channel whose use is defined by the application.
 void join(com.sun.media.jsdt.Client client, int mode)
           join is used by a client to join an appropriate channel whose use is defined by the application.
 void leave(com.sun.media.jsdt.Client client)
           leave removes a Client from this Channel.
 java.lang.String[] listConsumerNames()
           list the names of the Clients who are currently consuming this Channel.
 com.sun.media.jsdt.Data receive(com.sun.media.jsdt.Client client)
           is used to receive Data from other Clients joined to this Channel.
 com.sun.media.jsdt.Data receive(com.sun.media.jsdt.Client client, long timeout)
           is used to receive Data from other Clients joined to this Channel.
 void removeChannelListener(com.sun.media.jsdt.event.ChannelListener listener)
           removes the specified Channel listener so that it no longer receives Channel events for this Channel.
 void removeConsumer(com.sun.media.jsdt.Client client, com.sun.media.jsdt.ChannelConsumer consumer)
           remove a ChannelConsumer from this Client for this Channel.
 void sendToAll(com.sun.media.jsdt.Client sendingClient, com.sun.media.jsdt.Data data)
           sendToAll is used to send data to all clients joined to this channel.
 void sendToClient(com.sun.media.jsdt.Client sendingClient, java.lang.String receivingClientName, com.sun.media.jsdt.Data data)
           sendToClient is used to send data to a single client joined to this channel.
 void sendToOthers(com.sun.media.jsdt.Client sendingClient, com.sun.media.jsdt.Data data)
           sendToOthers is used to send data to other clients joined to this channel.
 
Methods inherited from class com.sun.media.jsdt.impl.ManageableImpl
addListener, destroy, disableListenerEvents, disableManagerEvents, enableListenerEvents, enableManagerEvents, expel, getName, getSession, invite, isManaged, listClientNames
 
Methods inherited from class com.sun.media.jsdt.impl.JSDTObject
error, getConnectionType, setConnectionType
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

M_Channel

public static final char M_Channel
To signify a manageable object of type Channel.

D_All

public static final char D_All
Send Data to all consumers (including self) of the Channel.

D_Others

public static final char D_Others
Send Data to all other consumers of the Channel.

D_Client

public static final char D_Client
Send Data to a specific consumer of the Channel.

session

protected SessionImpl session
The session that this channel belongs to.

po

public AbstractChannelProxy po
Handle to client-side proxy.

so

public AbstractChannelServer so
Handle to server-side object.

reliable

protected boolean reliable
Indicates if data sent over this channel will be reliably delivered.

ordered

protected boolean ordered
Indicates whether data sent over this channel will be ordered.
Constructor Detail

ChannelImpl

public ChannelImpl(boolean isServer,
                   java.lang.String name,
                   SessionImpl session,
                   boolean reliable,
                   boolean ordered)
Channel the constructor for the Channel class.
Parameters:
isServer - set if are we creating object on the server-side.
name - the name of the channel being constructed.
session - the session this channel belongs to.
reliable - indicates whether the channel is reliable.
ordered - indicates whether the channel is ordered.
Method Detail

addChannelListener

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

removeChannelListener

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

addConsumer

public void addConsumer(com.sun.media.jsdt.Client client,
                        com.sun.media.jsdt.ChannelConsumer consumer)
                 throws com.sun.media.jsdt.ConnectionException,
                        com.sun.media.jsdt.InvalidClientException,
                        com.sun.media.jsdt.NoSuchChannelException,
                        com.sun.media.jsdt.NoSuchClientException,
                        com.sun.media.jsdt.NoSuchConsumerException,
                        com.sun.media.jsdt.NoSuchSessionException,
                        com.sun.media.jsdt.PermissionDeniedException,
                        com.sun.media.jsdt.TimedOutException
add a new ChannelConsumer for this Client. The Client's ChannelConsumers gets informed when there is Data available on a Channel.
Specified by:
addConsumer in interface com.sun.media.jsdt.Channel
Parameters:
client - the Client to associate this ChannelConsumer with.
consumer - the new ChannelConsumer for this client.
Throws:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchChannelException - if this Channel doesn't exist.
com.sun.media.jsdt.NoSuchClientException - if this Client doesn't exist.
com.sun.media.jsdt.NoSuchConsumerException - if this ChannelConsumer doesn't exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.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.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

removeConsumer

public void removeConsumer(com.sun.media.jsdt.Client client,
                           com.sun.media.jsdt.ChannelConsumer consumer)
                    throws com.sun.media.jsdt.ConnectionException,
                           com.sun.media.jsdt.InvalidClientException,
                           com.sun.media.jsdt.NoSuchChannelException,
                           com.sun.media.jsdt.NoSuchClientException,
                           com.sun.media.jsdt.NoSuchConsumerException,
                           com.sun.media.jsdt.NoSuchSessionException,
                           com.sun.media.jsdt.PermissionDeniedException,
                           com.sun.media.jsdt.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.
Specified by:
removeConsumer in interface com.sun.media.jsdt.Channel
Parameters:
client - the Client to associate this ChannelConsumer with.
consumer - the ChannelConsumer to remove from this Client.
Throws:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchChannelException - if this Channel doesn't exist.
com.sun.media.jsdt.NoSuchClientException - if this Client doesn't exist.
com.sun.media.jsdt.NoSuchConsumerException - if this ChannelConsumer doesn't exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.PermissionDeniedException - if this Client doesn't have permission for this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

listConsumerNames

public java.lang.String[] listConsumerNames()
                                     throws com.sun.media.jsdt.ConnectionException,
                                            com.sun.media.jsdt.NoSuchChannelException,
                                            com.sun.media.jsdt.NoSuchSessionException,
                                            com.sun.media.jsdt.TimedOutException
list the names of the Clients who are currently consuming this Channel.
Specified by:
listConsumerNames in interface com.sun.media.jsdt.Channel
Returns:
a sorted array of names of Clients currently comsuming this Channel.
Throws:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.NoSuchChannelException - if this Channel doesn't exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

isReliable

public boolean isReliable()
isReliable test whether this is a reliable channel.
Specified by:
isReliable in interface com.sun.media.jsdt.Channel
Returns:
true if this is a reliable channel; false if not.

isOrdered

public boolean isOrdered()
isOrdered returns whether this is an ordered channel.
Specified by:
isOrdered in interface com.sun.media.jsdt.Channel
Returns:
true if this is an ordered channel; false if not.

join

public void join(com.sun.media.jsdt.Client client)
          throws com.sun.media.jsdt.ConnectionException,
                 com.sun.media.jsdt.InvalidClientException,
                 com.sun.media.jsdt.NoSuchChannelException,
                 com.sun.media.jsdt.NoSuchClientException,
                 com.sun.media.jsdt.NoSuchSessionException,
                 com.sun.media.jsdt.PermissionDeniedException,
                 com.sun.media.jsdt.NameInUseException,
                 com.sun.media.jsdt.TimedOutException
join is used by a client to join an appropriate channel whose use is defined by the application. This is a prerequesite for sending and receiving data sent to the channel.
Parameters:
client - identifies the client wishing to join this channel.
Throws:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchChannelException - if the channel given does not exist,
com.sun.media.jsdt.NoSuchClientException - if the client given does not exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.PermissionDeniedException - if you do not have permission for this operation.
com.sun.media.jsdt.NameInUseException - if a Client with this name is already joined to this Manageable object.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.
Overrides:
join in class ManageableImpl

join

public void join(com.sun.media.jsdt.Client client,
                 int mode)
          throws com.sun.media.jsdt.ConnectionException,
                 com.sun.media.jsdt.InvalidClientException,
                 com.sun.media.jsdt.NoSuchChannelException,
                 com.sun.media.jsdt.NoSuchClientException,
                 com.sun.media.jsdt.NoSuchSessionException,
                 com.sun.media.jsdt.PermissionDeniedException,
                 com.sun.media.jsdt.NameInUseException,
                 com.sun.media.jsdt.TimedOutException
join is used by a client to join an appropriate channel whose use is defined by the application. This is a prerequesite for sending and receiving data sent to the channel.
Specified by:
join in interface com.sun.media.jsdt.Channel
Parameters:
client - identifies the client wishing to join this channel.
mode - the mode which can be one of, READONLY, WRITEONLY or READWRITE.
Throws:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchChannelException - if the channel given does not exist,
com.sun.media.jsdt.NoSuchClientException - if the client given does not exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.PermissionDeniedException - if you do not have permission for this operation.
com.sun.media.jsdt.NameInUseException - if a Client with this name is already joined to this Manageable object.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

leave

public void leave(com.sun.media.jsdt.Client client)
           throws com.sun.media.jsdt.ConnectionException,
                  com.sun.media.jsdt.InvalidClientException,
                  com.sun.media.jsdt.NoSuchChannelException,
                  com.sun.media.jsdt.NoSuchClientException,
                  com.sun.media.jsdt.NoSuchSessionException,
                  com.sun.media.jsdt.TimedOutException
leave removes a Client from this Channel. This Client will no longer be known to this Channel. Listeners of this Channel will be sent an indication when this happens.
Parameters:
client - the Client in question.
Throws:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchChannelException - if this Channel doesn't exist.
com.sun.media.jsdt.NoSuchClientException - if this Client doesn't exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.
Overrides:
leave in class ManageableImpl

receive

public com.sun.media.jsdt.Data receive(com.sun.media.jsdt.Client client)
                                throws com.sun.media.jsdt.ConnectionException,
                                       com.sun.media.jsdt.InvalidClientException,
                                       com.sun.media.jsdt.NoSuchClientException,
                                       com.sun.media.jsdt.NoSuchSessionException,
                                       com.sun.media.jsdt.PermissionDeniedException,
                                       com.sun.media.jsdt.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.

Specified by:
receive in interface com.sun.media.jsdt.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:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchClientException - if the client given doesn't exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.PermissionDeniedException - if this Client doesn't have permission for this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

receive

public com.sun.media.jsdt.Data receive(com.sun.media.jsdt.Client client,
                                       long timeout)
                                throws com.sun.media.jsdt.ConnectionException,
                                       com.sun.media.jsdt.InvalidClientException,
                                       com.sun.media.jsdt.NoSuchClientException,
                                       com.sun.media.jsdt.NoSuchSessionException,
                                       com.sun.media.jsdt.PermissionDeniedException,
                                       com.sun.media.jsdt.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.

Specified by:
receive in interface com.sun.media.jsdt.Channel
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 there is currently no Data available and the timeout period has expired.
Throws:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchClientException - if the client given doesn't exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.PermissionDeniedException - if this Client doesn't have permission for this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

dataAvailable

public boolean dataAvailable(com.sun.media.jsdt.Client client)
                      throws com.sun.media.jsdt.ConnectionException,
                             com.sun.media.jsdt.InvalidClientException,
                             com.sun.media.jsdt.NoSuchClientException,
                             com.sun.media.jsdt.NoSuchSessionException,
                             com.sun.media.jsdt.PermissionDeniedException,
                             com.sun.media.jsdt.TimedOutException
tests whether there is Data available to read on this Channel.
Specified by:
dataAvailable in interface com.sun.media.jsdt.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:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchClientException - if the client given doesn't exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.PermissionDeniedException - if this Client doesn't have permission for this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

sendToAll

public void sendToAll(com.sun.media.jsdt.Client sendingClient,
                      com.sun.media.jsdt.Data data)
               throws com.sun.media.jsdt.ConnectionException,
                      com.sun.media.jsdt.InvalidClientException,
                      com.sun.media.jsdt.NoSuchChannelException,
                      com.sun.media.jsdt.NoSuchClientException,
                      com.sun.media.jsdt.NoSuchSessionException,
                      com.sun.media.jsdt.PermissionDeniedException,
                      com.sun.media.jsdt.TimedOutException
sendToAll is used to send data to all clients joined to this channel. If the sender is listening on this channel, then it 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.
Specified by:
sendToAll in interface com.sun.media.jsdt.Channel
Parameters:
sendingClient - the client sending the data.
data - the data being sent over this channel.
Throws:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchChannelException - if the channel given does not exist.
com.sun.media.jsdt.NoSuchClientException - if the client given does not exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.PermissionDeniedException - if you do not have permission for this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

sendToOthers

public void sendToOthers(com.sun.media.jsdt.Client sendingClient,
                         com.sun.media.jsdt.Data data)
                  throws com.sun.media.jsdt.ConnectionException,
                         com.sun.media.jsdt.InvalidClientException,
                         com.sun.media.jsdt.NoSuchChannelException,
                         com.sun.media.jsdt.NoSuchClientException,
                         com.sun.media.jsdt.NoSuchSessionException,
                         com.sun.media.jsdt.PermissionDeniedException,
                         com.sun.media.jsdt.TimedOutException
sendToOthers is used to send data to other clients joined to this channel. The sender (irrespective of whether it's listening on 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.
Specified by:
sendToOthers in interface com.sun.media.jsdt.Channel
Parameters:
sendingClient - the client sending the data.
data - the data being sent over this channel.
Throws:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchChannelException - if the channel given does not exist.
com.sun.media.jsdt.NoSuchClientException - if the client given does not exist.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.PermissionDeniedException - if you do not have permission for this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

sendToClient

public void sendToClient(com.sun.media.jsdt.Client sendingClient,
                         java.lang.String receivingClientName,
                         com.sun.media.jsdt.Data data)
                  throws com.sun.media.jsdt.ConnectionException,
                         com.sun.media.jsdt.InvalidClientException,
                         com.sun.media.jsdt.NoSuchChannelException,
                         com.sun.media.jsdt.NoSuchClientException,
                         com.sun.media.jsdt.NoSuchConsumerException,
                         com.sun.media.jsdt.NoSuchSessionException,
                         com.sun.media.jsdt.PermissionDeniedException,
                         com.sun.media.jsdt.TimedOutException
sendToClient is used to send data to a single client joined to this channel.
Specified by:
sendToClient in interface com.sun.media.jsdt.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:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
com.sun.media.jsdt.NoSuchChannelException - if the channel given does not exist.
com.sun.media.jsdt.NoSuchClientException - if the client given does not exist.
com.sun.media.jsdt.NoSuchConsumerException - if this Client doesn't have a ChannelConsumer associated with it.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.PermissionDeniedException - if you do not have permission for this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.