com.sun.media.jsdt
Interface Token


public abstract interface Token
extends Manageable

The Token interface.

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

Field Summary
static int ALREADY_GRABBED
          Token already grabbed state.
static int ALREADY_INHIBITED
          Token already inhibited state.
static int GIVING
          Token giving state.
static int GRABBED
          Token grabbed state.
static int INHIBITED
          Token inhibited state.
static int NOT_IN_USE
          Token not in use state.
 
Fields inherited from class java.io.Serializable
serialVersionUID
 
Method Summary
 void addTokenListener(TokenListener listener)
           add the specified Token listener to receive Token events for this Token.
 int give(Client client, java.lang.String receivingClientName)
           used by a Client to surrender a Token to another Client.
 int grab(Client client, boolean exclusive)
           used by a Client to take exclusive (grab) or non-exclusive (inhibit) control of a specific Token.
 java.lang.String[] listHolderNames()
           list the names of the Clients who are currently holding (grabbing or inhibiting) this Token.
 int release(Client client)
           used to free up a previously grabbed/inhibited Token.
 void removeTokenListener(TokenListener listener)
           remove the specified Token listener so that it no longer receives Token events for this Token.
 int request(Client client)
           used by a Client to request a Token from the current possessor(s) of the Token.
 int test()
           used to check the status of a Token.
 
Methods inherited from interface com.sun.media.jsdt.Manageable
destroy, disableListenerEvents, disableManagerEvents, enableListenerEvents, enableManagerEvents, expel, getName, getSession, invite, isManaged, join, leave, listClientNames
 

Field Detail

NOT_IN_USE

public static final int NOT_IN_USE
Token not in use state.

GRABBED

public static final int GRABBED
Token grabbed state.

INHIBITED

public static final int INHIBITED
Token inhibited state.

GIVING

public static final int GIVING
Token giving state.

ALREADY_GRABBED

public static final int ALREADY_GRABBED
Token already grabbed state.

ALREADY_INHIBITED

public static final int ALREADY_INHIBITED
Token already inhibited state.
Method Detail

addTokenListener

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

removeTokenListener

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

give

public int give(Client client,
                java.lang.String receivingClientName)
         throws ConnectionException,
                InvalidClientException,
                NoSuchTokenException,
                NoSuchClientException,
                NoSuchSessionException,
                PermissionDeniedException,
                TimedOutException
used by a Client to surrender a Token to another Client. It will fail if the requestor has not grabbed the specified Token within a certain period of time.

A GIVEN TokenEvent is delivered to the Token listener of the Client that this Client would like to give the Token to.

The giving Client must be either exclusively grabbing the Token or the only Client non-exclusively inhibiting this Token for the give operation to be permissible.

A Token being passed between two Clients and whose possession is not yet resolved will appear to any Client requesting test to be giving by some other Client and not held by the requestor. grab will fail during this interval, even if requested by one of the two Clients involved. release requested by the given will succeed, with the result that the Token is released if the offer to the recipient is ultimately rejected. release by the recipient will have no effect, just like the attempted release of any other Token that the requester does not yet possess. During the interval that a Token is being passed any request indications that are generated will be delivered to both Clients involved.

Parameters:
client - the Client giving this Token.
receivingClientName - the name of the Client to receive the Token.
Returns:
the status of the token.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchTokenException - if this Token doesn't exist.
NoSuchClientException - if the giving or receiving Client doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client does not have permission to perform this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.

grab

public int grab(Client client,
                boolean exclusive)
         throws ConnectionException,
                InvalidClientException,
                NoSuchTokenException,
                NoSuchClientException,
                NoSuchSessionException,
                PermissionDeniedException,
                TimedOutException
used by a Client to take exclusive (grab) or non-exclusive (inhibit) control of a specific Token.

With an exclusive grab, the grab will succeed if the requestor is the sole inhibitor of the Token.

The non-exclusive grab is used to take non-exclusive control of a specific Token. It is used to prevent someone else from exclusively grabbing the Token. Several Clients could inhibit a Token at the same time. This operation will succeed if the requestor has grabbed the Token. The result will be that the Token is no longer grabbed exclusively and is inhibited instead. Therefore it may be inhibited by other Clients too.

Parameters:
client - the Client grabbing/inhibiting this Token.
exclusive - indicates whether the grab should be exclusive.
Returns:
the status of the token.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchTokenException - if this Token doesn't exist.
NoSuchClientException - if this Client doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
PermissionDeniedException - if this Client does not have permission to perform this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.

listHolderNames

public java.lang.String[] listHolderNames()
                                   throws ConnectionException,
                                          NoSuchSessionException,
                                          NoSuchTokenException,
                                          TimedOutException
list the names of the Clients who are currently holding (grabbing or inhibiting) this Token. This method can be used in conjunction with the test method to determine if the token is being grabbed or inhibited.
Returns:
a sorted array of names of Clients currently holding this Token. This array will be of zero length if there are no Clients currently holding this Token.
Throws:
ConnectionException - if a connection error occured.
NoSuchSessionException - if this Session doesn't exist.
NoSuchTokenException - if this Token doesn't exist.
TimedOutException - if no reply was received for this operation in the given timeout period.
Since:
JSDT 1.3
See Also:
test()

request

public int request(Client client)
            throws ConnectionException,
                   InvalidClientException,
                   NoSuchTokenException,
                   NoSuchClientException,
                   NoSuchSessionException,
                   PermissionDeniedException,
                   TimedOutException
used by a Client to request a Token from the current possessor(s) of the Token. A Token may be inhibited by several Clients, or it may be grabbed by one Client. In any case, a REQUESTED TokenEvent is delivered to all the Token listeners listening to this Token, who currently possess the Token.
Parameters:
client - the Client requesting this Token.
Returns:
the status of the token.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchSessionException - if this Session doesn't exist.
NoSuchTokenException - if this Token doesn't exist.
NoSuchClientException - if this Client doesn't exist.
PermissionDeniedException - if this Client does not have permission to perform this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.

release

public int release(Client client)
            throws ConnectionException,
                   InvalidClientException,
                   NoSuchTokenException,
                   NoSuchClientException,
                   NoSuchSessionException,
                   ClientNotGrabbingException,
                   ClientNotReleasedException,
                   PermissionDeniedException,
                   TimedOutException
used to free up a previously grabbed/inhibited Token.
Parameters:
client - the Client releasing this Token.
Returns:
the status of the token.
Throws:
ConnectionException - if a connection error occured.
InvalidClientException - if the Client is invalid is some way (ie. its getName() method returns null).
NoSuchTokenException - if this Token doesn't exist.
NoSuchClientException - if this Client doesn't exist.
NoSuchSessionException - if this Session doesn't exist.
ClientNotGrabbingException - if this Client is not grabbing this Token.
ClientNotReleasedException - if the Token was not released successfully.
PermissionDeniedException - if this Client does not have permission to perform this operation.
TimedOutException - if no reply was received for this operation in the given timeout period.

test

public int test()
         throws ConnectionException,
                NoSuchSessionException,
                NoSuchTokenException,
                TimedOutException
used to check the status of a Token.
Returns:
one of the following:
 NOT_IN_USE : not in use
 GRABBED    : grabbed
 INHIBITED  : inhibited
 GIVING     : giving
 
Throws:
ConnectionException - if a connection error occured.
NoSuchSessionException - if this Session doesn't exist.
NoSuchTokenException - if this Token doesn't exist.
TimedOutException - if no reply was received for this operation in the given timeout period.