Parsing Engine

danbikel.switchboard
Interface SwitchboardUser

All Superinterfaces:
Remote
All Known Subinterfaces:
Client, DecoderServerRemote, ParserRemote, Server
All Known Implementing Classes:
AbstractClient, AbstractServer, AbstractSwitchboardUser, CachingDecoderServer, DecoderServer, EMParser, Parser

public interface SwitchboardUser
extends Remote

An interface that both types of users of the switchboard (clients and servers) must implement, providing useful information about the switchboard user, as well as a means to determine whether the switchboard user is alive and to tell it when it is allowed to die.

Concrete implementations of this interface must ensure that they appropriately deal with switchboard failures. An acceptable response to a switchboard failure is either simply to commit suicide, or to wait patiently for a new switchboard to become available. The latter option is preferable when developing fault-tolerant systems. Detection of a swtichboard's failure will necessarily occur as a RemoteException during an invocation of one of the switchboard's methods. Because client and server state (such as unique IDs) is not maintained by the switchboard in its log file, it is necessary for switchboard users to re-register before re-invoking the method that had failed. Another consequence of the lack of persistence of switchboard user state is that if a client is in the middle of processing an object obtained from the switchboard when the switchboard goes down, it should cease processing, re-register and get a new object via the SwitchboardRemote.nextObject(int) method. The AbstractSwitchboardUser class provides methods to make compliance with the general contract of this interface straightforward for concrete subclasses.

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
 
The purpose of the abstract implementation hierarchy is to provide convenient default implementations that comply with their respective interfaces' general contracts.

A note on fault tolerance: In order to ensure the fault-tolerance of switchboard users, concrete implementors of this interface should ensure that they use socket factories that set the SO_TIMEOUT values of their TCP/IP sockets to some integer greater than 0. This will mean that the Java Remote Method Protocol (JRMP) implementation can never hang when a remote object crashes (as is possible with Sun's JRMP implementation). TimeoutSocketFactory is one such factory for creating both client- and server-side sockets. Implementors that use sockets other than TCP/IP sockets should have similar non-infinite timeouts.

See Also:
Client, Server, AbstractSwitchboardUser

Method Summary
 boolean alive()
          A simple "ping" method for the switchboard to continually make sure its users are alive.
 void die(boolean now)
          Tells the switchboard user to commit suicide.
 String host()
          Returns the hostname on which this switchboard user is running.
 int id()
          Returns the ID number for this switchboard user.
 

Method Detail

id

int id()
       throws RemoteException
Returns the ID number for this switchboard user.

Throws:
RemoteException

host

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

Throws:
RemoteException

die

void die(boolean now)
         throws RemoteException
Tells the switchboard user to commit suicide. This method will typically be invoked by the switchboard when sentence 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.

Important synchronization note: This method should be non-blocking. That is, it shouldn't wait for some switchboard resource or information to become available before returning. If this condition is not met, then deadlock could occur.

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

boolean alive()
              throws RemoteException
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.

Throws:
RemoteException
See Also:
AbstractSwitchboardUser

Parsing Engine

Author: Dan Bikel.