com.sun.media.jsdt.impl
Class TokenImpl

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

public class TokenImpl
extends ManageableImpl
implements com.sun.media.jsdt.Token

JSDT Token (implementation) class.

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

Field Summary
 boolean isExclusive
          Indicates whether the token is being grabbed exclusively.
static char M_Token
          To signify a manageable object of type Token.
 AbstractTokenProxy po
          Handle to client-side proxy.
 AbstractTokenServer so
          Handle to server-side object.
 java.lang.Integer status
          The status of this token.
protected  com.sun.media.jsdt.TokenManager tokenManager
          The token manager associated with this token (if any).
 
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
TokenImpl(boolean isServer, java.lang.String name, SessionImpl session)
           TokenImpl the constructor for the Token (implementation) class.
 
Method Summary
 void addTokenListener(com.sun.media.jsdt.event.TokenListener listener)
           add the specified Token listener to receive Token events for this Token.
 int give(com.sun.media.jsdt.Client client, java.lang.String receivingClientName)
           used by a Client to surrender a Token to another Client.
 int grab(com.sun.media.jsdt.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(com.sun.media.jsdt.Client client)
           used to free up a previously grabbed/inhibited Token.
 void removeTokenListener(com.sun.media.jsdt.event.TokenListener listener)
           remove the specified Token listener so that it no longer receives Token events for this Token.
 int request(com.sun.media.jsdt.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 class com.sun.media.jsdt.impl.ManageableImpl
addListener, destroy, disableListenerEvents, disableManagerEvents, enableListenerEvents, enableManagerEvents, expel, getName, getSession, invite, isManaged, join, leave, 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_Token

public static final char M_Token
To signify a manageable object of type Token.

tokenManager

protected com.sun.media.jsdt.TokenManager tokenManager
The token manager associated with this token (if any).

po

public AbstractTokenProxy po
Handle to client-side proxy.

so

public AbstractTokenServer so
Handle to server-side object.

isExclusive

public boolean isExclusive
Indicates whether the token is being grabbed exclusively.

status

public java.lang.Integer status
The status of this token.
Constructor Detail

TokenImpl

public TokenImpl(boolean isServer,
                 java.lang.String name,
                 SessionImpl session)
TokenImpl the constructor for the Token (implementation) class.
Parameters:
isServer - set if are we creating object on the server-side.
name - the name of the token being constructed.
session - the session this token belongs to.
Method Detail

addTokenListener

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

removeTokenListener

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

give

public int give(com.sun.media.jsdt.Client client,
                java.lang.String receivingClientName)
         throws com.sun.media.jsdt.ConnectionException,
                com.sun.media.jsdt.InvalidClientException,
                com.sun.media.jsdt.NoSuchTokenException,
                com.sun.media.jsdt.NoSuchClientException,
                com.sun.media.jsdt.NoSuchSessionException,
                com.sun.media.jsdt.PermissionDeniedException,
                com.sun.media.jsdt.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.

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.

Specified by:
give in interface com.sun.media.jsdt.Token
Parameters:
client - the Client giving this Token.
receivingClientName - the name of the Client to receive the Token.
Returns:
the status of the token.
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.NoSuchTokenException - if this Token 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.PermissionDeniedException - if this Client does not have permission to perform this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

grab

public int grab(com.sun.media.jsdt.Client client,
                boolean exclusive)
         throws com.sun.media.jsdt.ConnectionException,
                com.sun.media.jsdt.InvalidClientException,
                com.sun.media.jsdt.NoSuchTokenException,
                com.sun.media.jsdt.NoSuchClientException,
                com.sun.media.jsdt.NoSuchSessionException,
                com.sun.media.jsdt.PermissionDeniedException,
                com.sun.media.jsdt.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.

Specified by:
grab in interface com.sun.media.jsdt.Token
Parameters:
client - the Client grabbing/inhibiting this Token.
exclusive - indicates whether the grab should be exclusive.
Returns:
the status of the token.
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.NoSuchTokenException - if this Token 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.PermissionDeniedException - if this Client does not have permission to perform this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

listHolderNames

public java.lang.String[] listHolderNames()
                                   throws com.sun.media.jsdt.ConnectionException,
                                          com.sun.media.jsdt.NoSuchSessionException,
                                          com.sun.media.jsdt.NoSuchTokenException,
                                          com.sun.media.jsdt.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.
Specified by:
listHolderNames in interface com.sun.media.jsdt.Token
Returns:
a sorted array of names of Clients currently holding this Token.
Throws:
com.sun.media.jsdt.ConnectionException - if a connection error occured.
com.sun.media.jsdt.NoSuchSessionException - if this Session doesn't exist.
com.sun.media.jsdt.NoSuchTokenException - if this Token doesn't exist.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.
See Also:
Token.test()

request

public int request(com.sun.media.jsdt.Client client)
            throws com.sun.media.jsdt.ConnectionException,
                   com.sun.media.jsdt.InvalidClientException,
                   com.sun.media.jsdt.NoSuchTokenException,
                   com.sun.media.jsdt.NoSuchClientException,
                   com.sun.media.jsdt.NoSuchSessionException,
                   com.sun.media.jsdt.PermissionDeniedException,
                   com.sun.media.jsdt.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.
Specified by:
request in interface com.sun.media.jsdt.Token
Parameters:
client - the Client requesting this Token.
Returns:
the status of the token.
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.NoSuchTokenException - if this Token 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.PermissionDeniedException - if this Client does not have permission to perform this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

release

public int release(com.sun.media.jsdt.Client client)
            throws com.sun.media.jsdt.ConnectionException,
                   com.sun.media.jsdt.InvalidClientException,
                   com.sun.media.jsdt.NoSuchTokenException,
                   com.sun.media.jsdt.NoSuchClientException,
                   com.sun.media.jsdt.NoSuchSessionException,
                   com.sun.media.jsdt.ClientNotGrabbingException,
                   com.sun.media.jsdt.ClientNotReleasedException,
                   com.sun.media.jsdt.PermissionDeniedException,
                   com.sun.media.jsdt.TimedOutException
used to free up a previously grabbed/inhibited Token.
Specified by:
release in interface com.sun.media.jsdt.Token
Parameters:
client - the Client releasing this Token.
Returns:
the status of the token.
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.NoSuchTokenException - if this Token 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.ClientNotGrabbingException - if this Client is not grabbing this Token.
com.sun.media.jsdt.ClientNotReleasedException - if the Token was not released successfully.
com.sun.media.jsdt.PermissionDeniedException - if this Client does not have permission to perform this operation.
com.sun.media.jsdt.TimedOutException - if no reply was received for this operation in the given timeout period.

test

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