com.sun.media.jsdt.template
Class TokenProxy

java.lang.Object
  |
  +--com.sun.media.jsdt.template.templateJSDTObject
        |
        +--com.sun.media.jsdt.template.ManageableProxy
              |
              +--com.sun.media.jsdt.template.TokenProxy

public final class TokenProxy
extends com.sun.media.jsdt.template.ManageableProxy
implements AbstractTokenProxy

JSDT Token proxy class.

Version:
1.5 - 7th January 1999
Author:
Rich Burridge

Constructor Summary
TokenProxy()
           
 
Method Summary
 java.lang.Object getProxy()
           getProxy get a handle to the "client-side" proxy 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.
 void initProxy(java.lang.String name, SessionImpl session, java.lang.Object object)
           initProxy initialise the "client-side" proxy for this 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.
 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.template.ManageableProxy
addListener, changeListenerMask, changeManagerMask, destroy, expel, getSession, invite, isManaged, join, leave, listClientNames, removeListener
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TokenProxy

public TokenProxy()
Method Detail

initProxy

public void initProxy(java.lang.String name,
                      SessionImpl session,
                      java.lang.Object object)
initProxy initialise the "client-side" proxy for this Token.
Specified by:
initProxy in interface AbstractTokenProxy
Parameters:
name - the name of the Token proxy being constructed.
session - the client-side session the Token belongs to.
object - the client-side Token.
Overrides:
initProxy in class com.sun.media.jsdt.template.ManageableProxy

getProxy

public java.lang.Object getProxy()
getProxy get a handle to the "client-side" proxy for this Token.
Specified by:
getProxy in interface AbstractTokenProxy
Returns:
a handle to the "client-side" proxy for this Token.
Overrides:
getProxy in class com.sun.media.jsdt.template.ManageableProxy

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 AbstractTokenProxy
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 AbstractTokenProxy
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 AbstractTokenProxy
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.NoSuchTokenException - if this Token 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.

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 AbstractTokenProxy
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 AbstractTokenProxy
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 AbstractTokenProxy
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.NoSuchTokenException - if this Token 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.