Parsing Engine

danbikel.switchboard
Class AbstractSwitchboardUser

java.lang.Object
  extended by java.rmi.server.RemoteObject
      extended by java.rmi.server.RemoteServer
          extended by danbikel.switchboard.AbstractSwitchboardUser
All Implemented Interfaces:
SwitchboardUser, Serializable, Remote
Direct Known Subclasses:
AbstractClient, AbstractServer

public abstract class AbstractSwitchboardUser
extends RemoteServer
implements SwitchboardUser

Provides a convenient default implementation of the interface SwitchboardUser, so that subclasses that need to implement the Client and Server interfaces need only implement the methods introduced in those subinterfaces, as is the case with the AbstractClient and AbstractServer implementations provided by this package.

Put another way, the interface hierarchy of SwitchboardUser, Client and Server is mirrored by the implementation hierarchy of AbstractSwitchboardUser, AbstractClient and AbstractServer:

   Interface Hierarchy          Implementation Hierarchy
   -------------------          ------------------------
     SwitchboardUser             AbstractSwitchboardUser
       /        \                  /             \
      /          \                /               \
   Client      Server       AbstractClient   AbstractServer
 

See Also:
AbstractClient, AbstractServer, Serialized Form

Nested Class Summary
protected  class AbstractSwitchboardUser.Alive
          Class to implement a thread that detects whether the switchboard has gone down, by noticing when it has been too long since its last call to alive().
protected static class AbstractSwitchboardUser.SBUserRetry
          Provides an appropriate overridden definition of Retry.keepTrying() that checks the value of timeToDie.
 
Field Summary
protected  Object aliveSynch
           
protected  int aliveTimeout
           
protected  String className
          The name of the runtime type of the subclass, cached here in this abstract class' constructor for convenience.
protected static int defaultMaxSwitchboardTries
          The fallback-default maximum number of times to try contacting the switchboard after it goes down or when registering for the first time.
protected static int defaultTimeout
          The fallback-default timeout value for client- (switchboard-) side sockets.
protected  Object dieSynch
          The object on which to synchronize death.
protected  int id
          The unique ID of this switchboard user, assigned by the switchboard.
protected static int infiniteTries
          The value to specify for switchboard users to try indefinitely to re-acquire the switchboard when first starting up or in the event of a switchboard crash.
protected  int maxSwitchboardTries
          The maximum number of times the getSwitchboard(java.lang.String) method will try to get a new Switchboard when the current instance has gone down or when registering for the first time.
protected  boolean registered
          Flag that indicates whether this client is currently registered.
protected  SwitchboardRemote switchboard
          A handle onto the switchboard.
protected  String switchboardName
          The bootstrap registry name of the switchboard.
protected  int timeout
          The value for which switchboard-side (RMI client-side) sockets will timeout (a value of 0 indicates infinite timeout).
protected  boolean timeToDie
          The boolean indicating that this object is ready to die, and will wait for the length of the timeout value before actually committing suicide (by unexporting itself via the unexportWhenDead() method).
 
Fields inherited from class java.rmi.server.RemoteObject
ref
 
Constructor Summary
protected AbstractSwitchboardUser()
          A no-arg constructor for concrete subclasses that wish to have stand-alone (non-exported) constructors.
protected AbstractSwitchboardUser(int timeout)
          Constructs a switchboard user whose switchboard-side (RMI client-side) sockets will have the specified timeout.
protected AbstractSwitchboardUser(int timeout, int port)
          Constructs a switchboard user accepting RMI calls on the specified port, and whose switchboard-side (RMI client-side) sockets will have the specified timeout.
protected AbstractSwitchboardUser(int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf)
          Constructs a switchboard user receiving RMI calls on the specified port, constructing client- and server-side sockets from the specified socket factories.
 
Method Summary
 boolean alive()
          A simple "ping" method for the switchboard to continually make sure its users are alive.
protected  void cleanup()
          Does nothing; called by the default implementation of unexportWhenDead().
 void die(boolean now)
          Tells the switchboard user to commit suicide.
protected static void disableHttp(String property)
           
protected  void getAliveTimeout()
          Sets aliveTimeout to be a reasonable value.
protected  void getSwitchboard(String name)
          Repeatedly tries to get the switchboard stub from the bootstrap registry.
protected  void getSwitchboard(String name, boolean verbose)
          Repeatedly tries to get the switchboard stub from the bootstrap registry.
protected  void getSwitchboard(String name, boolean verbose, PrintWriter err)
          Repeatedly tries to get the switchboard stub from the bootstrap registry.
static SwitchboardRemote getSwitchboard(String name, int tries)
          Repeatedly tries the specified number of times to get the switchboard stub from the bootstrap registry.
static SwitchboardRemote getSwitchboard(String name, int tries, boolean verbose)
          Repeatedly tries the specified number of times to get the switchboard stub from the bootstrap registry.
static SwitchboardRemote getSwitchboard(String name, int tries, boolean verbose, PrintWriter err)
          Repeatedly tries the specified number of times to get the switchboard stub from the bootstrap registry.
 String host()
          Returns the host on which this switchboard user is running.
 int id()
          Returns the ID number for this switchboard user.
protected  int nonZeroTimeout()
          Returns the value of timeout (set at construction time), or defaultTimeout if timeout is 0.
protected abstract  void reRegister()
           
protected static void setPolicyFile(Class cl, String resource)
          Sets the system property "java.security.policy" to be the URL of the specified resource obtained from the specified class.
protected static void setPolicyFile(String resource)
          Sets the system property "java.security.policy" to be the URL of the specified resource obtained from the SwitchboardRemote class.
protected  void startAliveThread()
          Starts a thread using the AbstractSwitchboardUser.Alive class to detect when the switchboard goes down and re-register this user.
 void unexportWhenDead()
          Unexports this object when it considers itself dead.
 
Methods inherited from class java.rmi.server.RemoteServer
getClientHost, getLog, setLog
 
Methods inherited from class java.rmi.server.RemoteObject
equals, getRef, hashCode, toString, toStub
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

defaultTimeout

protected static final int defaultTimeout
The fallback-default timeout value for client- (switchboard-) side sockets. The value of this constant is 120000.

See Also:
Constant Field Values

infiniteTries

protected static final int infiniteTries
The value to specify for switchboard users to try indefinitely to re-acquire the switchboard when first starting up or in the event of a switchboard crash.

See Also:
Constant Field Values

defaultMaxSwitchboardTries

protected static final int defaultMaxSwitchboardTries
The fallback-default maximum number of times to try contacting the switchboard after it goes down or when registering for the first time. The current value of this constant is infiniteTries.

See Also:
maxSwitchboardTries, Constant Field Values

className

protected String className
The name of the runtime type of the subclass, cached here in this abstract class' constructor for convenience.


switchboard

protected SwitchboardRemote switchboard
A handle onto the switchboard.


switchboardName

protected String switchboardName
The bootstrap registry name of the switchboard.


registered

protected volatile boolean registered
Flag that indicates whether this client is currently registered.


dieSynch

protected Object dieSynch
The object on which to synchronize death. It is important that subclasses never invoke this object's notify or notifyAll method, for otherwise the semantics of certain methods of this class will be corrupted. However, subclasses may wait on this object.


timeToDie

protected volatile boolean timeToDie
The boolean indicating that this object is ready to die, and will wait for the length of the timeout value before actually committing suicide (by unexporting itself via the unexportWhenDead() method).


timeout

protected int timeout
The value for which switchboard-side (RMI client-side) sockets will timeout (a value of 0 indicates infinite timeout).


maxSwitchboardTries

protected int maxSwitchboardTries
The maximum number of times the getSwitchboard(java.lang.String) method will try to get a new Switchboard when the current instance has gone down or when registering for the first time. A value of infiniteTries indicates an infinite number of tries.


id

protected int id
The unique ID of this switchboard user, assigned by the switchboard.


aliveSynch

protected Object aliveSynch

aliveTimeout

protected int aliveTimeout
Constructor Detail

AbstractSwitchboardUser

protected AbstractSwitchboardUser()
A no-arg constructor for concrete subclasses that wish to have stand-alone (non-exported) constructors.


AbstractSwitchboardUser

protected AbstractSwitchboardUser(int timeout)
                           throws RemoteException
Constructs a switchboard user whose switchboard-side (RMI client-side) sockets will have the specified timeout. This constructor must be called by the constructor of a subclass.

Parameters:
timeout - the timeout value for switchboard-side (RMI client-side) sockets, in milliseconds; a value of 0 indicates infinite timeout
Throws:
RemoteException

AbstractSwitchboardUser

protected AbstractSwitchboardUser(int timeout,
                                  int port)
                           throws RemoteException
Constructs a switchboard user accepting RMI calls on the specified port, and whose switchboard-side (RMI client-side) sockets will have the specified timeout. This constructor must be called by the constructor of a subclass.

Parameters:
timeout - the timeout value for switchboard-side (RMI client-side) sockets, in milliseconds; a value of 0 indicates infinite timeout
port - the port on which to receive RMI calls
Throws:
RemoteException

AbstractSwitchboardUser

protected AbstractSwitchboardUser(int port,
                                  RMIClientSocketFactory csf,
                                  RMIServerSocketFactory ssf)
                           throws RemoteException
Constructs a switchboard user receiving RMI calls on the specified port, constructing client- and server-side sockets from the specified socket factories.

Parameters:
port - the port on which this object will receive RMI calls
csf - the client-side socket factory
ssf - the server-side server socket factory
Throws:
RemoteException
Method Detail

setPolicyFile

protected static void setPolicyFile(String resource)
Sets the system property "java.security.policy" to be the URL of the specified resource obtained from the SwitchboardRemote class.

Parameters:
resource - the resource to obtain from SwitchboardRemote that will be the value of the system property "java.security.policy"

setPolicyFile

protected static void setPolicyFile(Class cl,
                                    String resource)
Sets the system property "java.security.policy" to be the URL of the specified resource obtained from the specified class.

Parameters:
resource - the resource to obtain from the specified class that will be the value of the system property "java.security.policy"

disableHttp

protected static void disableHttp(String property)

getSwitchboard

protected void getSwitchboard(String name)
                       throws MalformedURLException
Repeatedly tries to get the switchboard stub from the bootstrap registry. The number of times is determined by the value of maxSwitchboardTries. There will be no error output for the repeated attempts (no verbosity).

Throws:
MalformedURLException

getSwitchboard

protected void getSwitchboard(String name,
                              boolean verbose)
                       throws MalformedURLException
Repeatedly tries to get the switchboard stub from the bootstrap registry. The number of times is determined by the value of maxSwitchboardTries. Each attempt that results in an error will be printed out to System.err.

Throws:
MalformedURLException

getSwitchboard

protected void getSwitchboard(String name,
                              boolean verbose,
                              PrintWriter err)
                       throws MalformedURLException
Repeatedly tries to get the switchboard stub from the bootstrap registry. The number of times is determined by the value of maxSwitchboardTries. If verbose is true, each attempt that results in an error will be printed out to the specified PrintWriter.

Parameters:
name - the name of the switchboard in the bootstrap registry
verbose - if true, indicates to print out each failed attempt to get the switchboard to the specified error writer
err - the character stream to which to output error messages
Throws:
MalformedURLException

getSwitchboard

public static SwitchboardRemote getSwitchboard(String name,
                                               int tries)
                                        throws MalformedURLException
Repeatedly tries the specified number of times to get the switchboard stub from the bootstrap registry.

Parameters:
name - the name of the switchboard in the bootstrap registry
tries - the number of times to try to get the switchboard from the bootstrap registry
Returns:
a stub from which to access the switchboard
Throws:
MalformedURLException - if the specified name is a malformed URL

getSwitchboard

public static SwitchboardRemote getSwitchboard(String name,
                                               int tries,
                                               boolean verbose)
                                        throws MalformedURLException
Repeatedly tries the specified number of times to get the switchboard stub from the bootstrap registry.

Parameters:
name - the name of the switchboard in the bootstrap registry
tries - the number of times to try to get the switchboard from the bootstrap registry
verbose - if true, indicates to print error messages to System.err if an exception is raised during any of the attempts to get the switchboard
Returns:
a stub from which to access the switchboard
Throws:
MalformedURLException - if the specified name is a malformed URL

getSwitchboard

public static SwitchboardRemote getSwitchboard(String name,
                                               int tries,
                                               boolean verbose,
                                               PrintWriter err)
                                        throws MalformedURLException
Repeatedly tries the specified number of times to get the switchboard stub from the bootstrap registry.

Parameters:
name - the name of the switchboard in the bootstrap registry
tries - the number of times to try to get the switchboard from the bootstrap registry
verbose - if true, indicates to print error messages to the specified PrintWriter if an exception is raised during any of the attempts to get the switchboard
err - the writer to which error messages should be printed if verbose is true (no messages are printed if verbose is false)
Returns:
a stub from which to access the switchboard
Throws:
MalformedURLException - if the specified name is a malformed URL

host

public String host()
            throws RemoteException
Returns the host on which this switchboard user is running.

Specified by:
host in interface SwitchboardUser
Throws:
RemoteException

cleanup

protected void cleanup()
Does nothing; called by the default implementation of unexportWhenDead(). If a subclass has additional cleanup to be done prior to unexporting, this method should be overridden.


unexportWhenDead

public void unexportWhenDead()
                      throws RemoteException
Unexports this object when it considers itself dead. This method waits on dieSynch, continually checking the timeToDie flag. When this flag is true, it means the die(boolean) method has been invoked. This method then grabs the lock on dieSynch one last time, waiting a maximum of timeout, or defaultTimeout if timeout is 0.

N.B.: Concrete subclasses should either devote a separate thread to call this method immediately after construction, or ensure that it is called as the last method in the subclass' main thread.

Throws:
RemoteException

die

public void die(boolean now)
         throws RemoteException
Tells the switchboard user to commit suicide. This method will typically be invoked by the switchboard when object processing is complete, but may also be invoked by a switchboard user itself to commit suicide. Typically, if a switchboard user wishes to commit suicide gracefully, it should invoke this method on itself with a now value of false, to allow the switchboard a final successful call to alive, which will return false. The switchboard will typically invoke this method on its users with a now value of true.

Specified by:
die in interface SwitchboardUser
Parameters:
now - if false, indicates that this switchboard user should wait gracefully for a final invocation by the switchboard of its alive() method, so that it can return false; otherwise, this method should cause the switchboard user to die as soon as possible
Throws:
RemoteException

alive

public boolean alive()
              throws RemoteException
Description copied from interface: SwitchboardUser
A simple "ping" method for the switchboard to continually make sure its users are alive. Implementations are required to allow one last call returning false after invocation of die(false) to indicate to switchboard that user is dying safely. However, implementations should also not wait indefinitely for this last call, instead using an appropriate maximum timeout value (such as the timeout of the transport layer, if available) before unexporting themselves.

Specified by:
alive in interface SwitchboardUser
Throws:
RemoteException
See Also:
AbstractSwitchboardUser

nonZeroTimeout

protected final int nonZeroTimeout()
Returns the value of timeout (set at construction time), or defaultTimeout if timeout is 0.


id

public int id()
       throws RemoteException
Description copied from interface: SwitchboardUser
Returns the ID number for this switchboard user.

Specified by:
id in interface SwitchboardUser
Throws:
RemoteException

getAliveTimeout

protected void getAliveTimeout()
                        throws RemoteException
Sets aliveTimeout to be a reasonable value. This default implementation sets aliveTimeout to be twice the maximum time the switchboard will try to call a users' alive() method. That is, the value set by this method is equal to the value of the expression
 2 * ((switchboard.getKeepAliveMaxRetries() + 1) *
      switchboard.getKeepAliveInterval());
 

Throws:
RemoteException

startAliveThread

protected void startAliveThread()
                         throws RemoteException
Starts a thread using the AbstractSwitchboardUser.Alive class to detect when the switchboard goes down and re-register this user.

Throws:
RemoteException

reRegister

protected abstract void reRegister()
                            throws RemoteException
Throws:
RemoteException

Parsing Engine

Author: Dan Bikel.