Parsing Engine

danbikel.switchboard
Class Switchboard

java.lang.Object
  extended byjava.rmi.server.RemoteObject
      extended byjava.rmi.server.RemoteServer
          extended bydanbikel.switchboard.Switchboard
All Implemented Interfaces:
Remote, Serializable, SwitchboardRemote

public class Switchboard
extends RemoteServer
implements SwitchboardRemote

The switchboard serves as the central "hub" in a distributed RMI object-processing run, accepting registrations of clients and servers, and assigning clients to servers. Also, the switchboard is an "object server", doling out objects to clients when requested. When clients are assigned servers via the getServer(int) method, the switchboard will always return the most lightly-loaded server, as determined by the load ratio of that server (the number of its clients divided by the maximum number of clients it is willing to accept). The switchboard may be used either for its primary switchboard facilities (doling out servers to clients), its object server facilities, or both.

N.B.: Unlike UnicastRemoteObject RMI servers, a Switchboard object needs to be explicitly exported, via its export() method.

See Also:
SwitchboardUser, ObjectReader, NumberedObject, Serialized Form

Field Summary
static String defaultBindingName
          The default rmiregistry binding name, "/Switchboard", which indicates to bind the switchboard under the specified name on localhost using the default rmiregistry port (1099).
protected static int defaultBufSize
          The default buffer size for all streams created by the switchboard.
static int defaultKeepAliveInterval
          The default interval, in milliseconds, between calls to a switchboard user's alive method.
static int defaultKeepAliveMaxRetries
          The default maximum number of retries the switchboard should make to determine whether a user is alive in the face of failure of that user's alive method.
static String defaultMessagesFilename
          The default filename to use for printing out messages.
static int defaultPort
          The default port on which to receive RMI calls, which is 0, indicating an anonymous port.
static boolean defaultReProcess
          The default re-processing option, which is false.
static boolean defaultServerDeathKillClients
          The default as to whether clients should be killed upon the death of their server.
static boolean defaultSortOutput
          The default sorting behavior for creating the output file from the log file, which is to perform a sort.
protected  String encoding
          The current file encoding.
static UnicastRemoteObject javadocHack
          Allows external links to UnicastRemoteObject and its members not to break when generating javadoc API documentation.
static String logFilenameSuffix
          The default suffix to add to input file names to form a log file name when none is explicitly specified.
static String outFilenameSuffix
          The default suffix to add to input file names to form an output file when none is explicitly specified.
 
Fields inherited from class java.rmi.server.RemoteObject
ref
 
Fields inherited from interface danbikel.switchboard.SwitchboardRemote
clientDisableHttp, clientNextObjectInterval, clientPolicyFile, serverDisableHttp, serverPolicyFile, socketTimeout, switchboardDisableHttp, switchboardPolicyFile
 
Constructor Summary
Switchboard()
          Constructs a Switchboard with all default settings.
Switchboard(PrintWriter msgs)
          Constructs a Switchboard with the specified message file writer.
Switchboard(PrintWriter msgs, int port)
          Constructs a Switchboard object with the specified message file writer and the specified port on which to receive RMI calls.
Switchboard(PrintWriter msgs, int port, boolean reProcess)
          Constructs a Switchboard object with the specified message file writer, port and re-process option.
Switchboard(PrintWriter msgs, int port, boolean reProcess, ObjectReaderFactory objReaderFactory, ObjectReaderFactory numObjReaderFactory, ObjectWriterFactory objWriterFactory, ObjectWriterFactory numObjWriterFactory)
          Constructs a Switchboard with the specified message file writer, port, re-process option and object reader/writer factories.
Switchboard(PrintWriter msgs, int port, boolean reProcess, ObjectReaderFactory objReaderFactory, ObjectReaderFactory numObjReaderFactory, ObjectWriterFactory objWriterFactory, ObjectWriterFactory numObjWriterFactory, String bindingName)
          Constructs a Switchboard object with the specified message file writer, port on which to receive RMI calls, re-process option, object reader factories (one for un-numbered objects, another for numbered objects) and registry binding name.
Switchboard(String msgsFilename)
          Constructs a Switchboard object using the specified filename for the messages file.
Switchboard(String msgsFilename, int port)
          Constructs a Switchboard object with the specified messages filename and port on which to receive RMI calls.
Switchboard(String msgsFilename, int port, boolean reProcess)
          Constructs a Switchboard with the specified message filename, port and re-process option.
Switchboard(String msgsFilename, int port, boolean reProcess, ObjectReaderFactory objReaderFactory, ObjectReaderFactory numObjReaderFactory, ObjectWriterFactory objWriterFactory, ObjectWriterFactory numObjWriterFactory)
          Constructs a Switchboard with the specified message filename, port, re-process option and object reader/writer factories.
Switchboard(String msgsFilename, int port, boolean reProcess, ObjectReaderFactory objReaderFactory, ObjectReaderFactory numObjReaderFactory, ObjectWriterFactory objWriterFactory, ObjectWriterFactory numObjWriterFactory, String bindingName)
          Constructs a Switchboard with the specified message file writer, port, re-process option, object reader/writer factories and registry binding name.
 
Method Summary
 void bind(Properties settings, String encoding)
          Sets the specified settings and langauge encoding and then exports this switchboard and binds it to the bootstrap RMI registry.
 void cleanup()
          Cleans up by telling all switchboard users to die, since object processing is complete.
 void cleanupWhenAllFilesAreDone()
           
 void export()
          Exports this object using UnicastRemoteObject.exportObject.
static ObjectReaderFactory getDefaultNumberedObjectReaderFactory()
          Returns the default ObjectReaderFactory for numbered objects, which uses an ObjectInputStream from which to read objects.
static ObjectWriterFactory getDefaultNumberedObjectWriterFactory()
          Returns the default ObjectWriterFactory for numbered objects, which uses an ObjectOutputStream to write objects.
static ObjectReaderFactory getDefaultObjectReaderFactory()
          Returns the default ObjectReaderFactory for un-numbered objects, which uses an ObjectInputStream from which to read objects.
static ObjectWriterFactory getDefaultObjectWriterFactory()
          Returns the default ObjectWriterFactory for un-numbered objects, which uses an ObjectOutputStream to write objects.
 int getKeepAliveInterval()
           
 int getKeepAliveMaxRetries()
           
 Server getServer(int clientId)
          Returns a Server for use by a client.
 Server getServer(int clientId, int serverId)
          Returns a Server associated with the specified server ID to the requesting client.
 String getSetting(String settingName)
          Gets the value for the specified settings from the switchboard's internal Properties object.
 Properties getSettings()
          Gets the internal Properties object used for various settings of this switchboard.
 boolean getVerbose()
          Gets the verbosity status of the switchboard.
 NumberedObject nextObject(int clientId)
          Gets the next object for the specified client; returns null if there is not currently an object to be processed.
 void processFile(String inFilename)
          Processes the specified input file and creates an output file with the specified name; a log file will be used to keep track of incremental work.
 void processFile(String inFilename, String outFilename)
          Processes the specified input file and creates an output file with the specified name; a log file will be used to keep track of incremental work.
 void processFile(String inFilename, String outFilename, String logFilename)
          Processes the specified input file and creates an output file with the specified name; a log file with the specified name will be used to keep track of incremental work.
 void processFile(String inFilename, String outFilename, String logFilename, boolean wait)
          Processes the specified input file and creates an output file with the specified name; a log file with the specified name will be used to keep track of incremental work.
 void putObject(int clientId, NumberedObject obj, long millis)
          Sends a processed object back to the switchboard object.
 int register(Client client)
          Registers a client with the switchboard.
 int register(Server server)
          Register a server with the switchboard.
 void registerConsumer(Consumer consumer)
          Registers the specified consumer of processed objects with this switchboard.
 void setBufSize(int bufSize)
          Sets the buffer size to be used for all streams by the switchboard (except the messages output file, which uses the value of defaultBufSize).
 void setEncoding(String enc)
          Sets the default character encoding (applicable if any ObjectReader or ObjectWriter instances created by the switchboard's factories are character-based).
static void setPolicyFile(Class cl, Properties props)
          Calls setPolicyFile(Class,String) with the specified class and the value of the SwitchboardRemote.switchboardPolicyFile property obtained from the specified Properties object.
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.
static void setPolicyFile(Properties props)
          Calls setPolicyFile(String) with the value of the SwitchboardRemote.switchboardPolicyFile property obtained from the specified Properties object.
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.
 void setSettings(Properties settings)
          Sets the internal settings of this switchboard to the specified Properties object.
 void setVerbose(boolean verbose)
          Sets the verbosity status of the switchboard.
 void waitUntilAllFilesAreDone()
           
 
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

javadocHack

public static final UnicastRemoteObject javadocHack
Allows external links to UnicastRemoteObject and its members not to break when generating javadoc API documentation.


defaultBindingName

public static final String defaultBindingName
The default rmiregistry binding name, "/Switchboard", which indicates to bind the switchboard under the specified name on localhost using the default rmiregistry port (1099).

See Also:
Constant Field Values

outFilenameSuffix

public static final String outFilenameSuffix
The default suffix to add to input file names to form an output file when none is explicitly specified. The value of this constant is ".proc".

See Also:
Constant Field Values

logFilenameSuffix

public static final String logFilenameSuffix
The default suffix to add to input file names to form a log file name when none is explicitly specified. The value of this constant is ".log".

See Also:
Constant Field Values

defaultMessagesFilename

public static final String defaultMessagesFilename
The default filename to use for printing out messages. If this default name is used, the messages file will be created in the current working directory. The value of this constant is "switchboard.msgs".

See Also:
Constant Field Values

defaultReProcess

public static final boolean defaultReProcess
The default re-processing option, which is false. This value may be passed to various constructors that take a re-processing option.

See Also:
Constant Field Values

defaultServerDeathKillClients

public static final boolean defaultServerDeathKillClients
The default as to whether clients should be killed upon the death of their server.

The value of this constant is false.

See Also:
Constant Field Values

defaultKeepAliveMaxRetries

public static final int defaultKeepAliveMaxRetries
The default maximum number of retries the switchboard should make to determine whether a user is alive in the face of failure of that user's alive method.

The value of this constant is 0.

See Also:
Constant Field Values

defaultKeepAliveInterval

public static final int defaultKeepAliveInterval
The default interval, in milliseconds, between calls to a switchboard user's alive method.

The value of this constant is 5000.

See Also:
Constant Field Values

defaultSortOutput

public static final boolean defaultSortOutput
The default sorting behavior for creating the output file from the log file, which is to perform a sort.

See Also:
Constant Field Values

defaultPort

public static final int defaultPort
The default port on which to receive RMI calls, which is 0, indicating an anonymous port. Unlike the RMI API, we encourage the use of this constant rather than direct referral to a "magic number". This value may be passed to the Switchboard constructors that take a port.

See Also:
Constant Field Values

defaultBufSize

protected static int defaultBufSize
The default buffer size for all streams created by the switchboard. This will be the buffer size of the messages file. The setBufSize method may be used if a different buffer size is desired for all other streams created by the switchboard.

The value of this data member is 8192.

See Also:
setBufSize(int)

encoding

protected String encoding
The current file encoding.

Constructor Detail

Switchboard

public Switchboard()
            throws RemoteException
Constructs a Switchboard with all default settings. The defaults are as follows:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.


Switchboard

public Switchboard(String msgsFilename)
            throws RemoteException
Constructs a Switchboard object using the specified filename for the messages file.

The following default settings will be used:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.

Parameters:
msgsFilename - the filename of the messages output writer, to be appended to as as long as this switchboard is running

Switchboard

public Switchboard(PrintWriter msgs)
            throws RemoteException
Constructs a Switchboard with the specified message file writer.

The following default settings will be used:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.

Parameters:
msgs - the messages output writer, to be appended to as as long as this switchboard is running

Switchboard

public Switchboard(String msgsFilename,
                   int port)
            throws RemoteException
Constructs a Switchboard object with the specified messages filename and port on which to receive RMI calls.

The following default settings will be used:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.

Parameters:
msgsFilename - the filename of the messages output writer, to be appended to as as long as this switchboard is running
port - the port for this UnicastRemoteObject to listen for RMI calls

Switchboard

public Switchboard(PrintWriter msgs,
                   int port)
            throws RemoteException
Constructs a Switchboard object with the specified message file writer and the specified port on which to receive RMI calls.

The following default settings will be used:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.

Parameters:
msgs - the messages output writer, to be appended to as as long as this switchboard is running
port - the port for this UnicastRemoteObject to listen for RMI calls

Switchboard

public Switchboard(String msgsFilename,
                   int port,
                   boolean reProcess)
            throws RemoteException
Constructs a Switchboard with the specified message filename, port and re-process option.

The following default settings will be used:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.

Parameters:
msgsFilename - the filename of the messages output writer, to be appended to as as long as this switchboard is running
port - the port for this UnicastRemoteObject to listen for RMI calls
reProcess - indicates whether to attempt to re-process objects that were not processed previously, if recovering from a previous run using an existing log file

Switchboard

public Switchboard(PrintWriter msgs,
                   int port,
                   boolean reProcess)
            throws RemoteException
Constructs a Switchboard object with the specified message file writer, port and re-process option.

The following default settings will be used:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.

Parameters:
msgs - the messages output writer, to be appended to as as long as this switchboard is running
port - the port for this UnicastRemoteObject to listen for RMI calls
reProcess - indicates whether to attempt to re-process objects that were not processed previously, if recovering from a previous run using an existing log file

Switchboard

public Switchboard(String msgsFilename,
                   int port,
                   boolean reProcess,
                   ObjectReaderFactory objReaderFactory,
                   ObjectReaderFactory numObjReaderFactory,
                   ObjectWriterFactory objWriterFactory,
                   ObjectWriterFactory numObjWriterFactory)
            throws RemoteException
Constructs a Switchboard with the specified message filename, port, re-process option and object reader/writer factories.

The following default settings will be used:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.

Parameters:
msgsFilename - the filename of the messages output writer, to be appended to as as long as this switchboard is running
port - the port for this UnicastRemoteObject to listen for RMI calls
reProcess - indicates whether to attempt to re-process objects that were not processed previously, if recovering from a previous run using an existing log file
objReaderFactory - the factory from which to get objects that will be used to read objects from the specified input file
numObjReaderFactory - the factory from which to get objects that will be used to read numbered objects from the log file
N.B.: The object readers produced by this factory must only return NumberedObject instances from their underlying streams.
objWriterFactory - the factory from which to get objects that will be used to write objects to the specified output file
numObjWriterFactory - the factory from which to get objects that will be used to write numbered objects to the log file

Switchboard

public Switchboard(PrintWriter msgs,
                   int port,
                   boolean reProcess,
                   ObjectReaderFactory objReaderFactory,
                   ObjectReaderFactory numObjReaderFactory,
                   ObjectWriterFactory objWriterFactory,
                   ObjectWriterFactory numObjWriterFactory)
            throws RemoteException
Constructs a Switchboard with the specified message file writer, port, re-process option and object reader/writer factories.

The following default settings will be used:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.

Parameters:
msgs - the messages output writer, to be appended to as as long as this switchboard is running
port - the port for this UnicastRemoteObject to listen for RMI calls
reProcess - indicates whether to attempt to re-process objects that were not processed previously, if recovering from a previous run using an existing log file
objReaderFactory - the factory from which to get objects that will be used to read objects from the specified input file
numObjReaderFactory - the factory from which to get objects that will be used to read numbered objects from the log file
N.B.: The object readers produced by this factory must only return NumberedObject instances from their underlying streams.
objWriterFactory - the factory from which to get objects that will be used to write objects to the specified output file
numObjWriterFactory - the factory from which to get objects that will be used to write numbered objects to the log file

Switchboard

public Switchboard(String msgsFilename,
                   int port,
                   boolean reProcess,
                   ObjectReaderFactory objReaderFactory,
                   ObjectReaderFactory numObjReaderFactory,
                   ObjectWriterFactory objWriterFactory,
                   ObjectWriterFactory numObjWriterFactory,
                   String bindingName)
            throws RemoteException
Constructs a Switchboard with the specified message file writer, port, re-process option, object reader/writer factories and registry binding name.

The following default settings will be used:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.

Parameters:
msgsFilename - the filename of the messages output writer, to be appended to as as long as this switchboard is running
port - the port for this UnicastRemoteObject to listen for RMI calls
reProcess - indicates whether to attempt to re-process objects that were not processed previously, if recovering from a previous run using an existing log file
objReaderFactory - the factory from which to get objects that will be used to read objects from the specified input file
numObjReaderFactory - the factory from which to get objects that will be used to read numbered objects from the log file
N.B.: The object readers produced by this factory must only return NumberedObject instances from their underlying streams.
objWriterFactory - the factory from which to get objects that will be used to write objects to the specified output file
numObjWriterFactory - the factory from which to get objects that will be used to write numbered objects to the log file
bindingName - the name under which this switchboard will be bound using Naming.bind or Naming.rebind, so that this switchboard can unexport itself when it is finished

Switchboard

public Switchboard(PrintWriter msgs,
                   int port,
                   boolean reProcess,
                   ObjectReaderFactory objReaderFactory,
                   ObjectReaderFactory numObjReaderFactory,
                   ObjectWriterFactory objWriterFactory,
                   ObjectWriterFactory numObjWriterFactory,
                   String bindingName)
            throws RemoteException
Constructs a Switchboard object with the specified message file writer, port on which to receive RMI calls, re-process option, object reader factories (one for un-numbered objects, another for numbered objects) and registry binding name.

The following default settings will be used:

Additionally, the settings controlled via the setSettings(Properties) method will initially be set to their defaults: defaultKeepAliveInterval, defaultKeepAliveMaxRetries and defaultServerDeathKillClients.

Parameters:
msgs - the messages output writer, to be appended to as as long as this switchboard is running
port - the port for this UnicastRemoteObject to listen for RMI calls
reProcess - indicates whether to attempt to re-process objects that were not processed previously, if recovering from a previous run using an existing log file
objReaderFactory - the factory from which to get objects that will be used to read objects from the specified input file
numObjReaderFactory - the factory from which to get objects that will be used to read numbered objects from the log file
N.B.: The object readers produced by this factory must only return NumberedObject instances from their underlying streams.
objWriterFactory - the factory from which to get objects that will be used to write objects to the specified output file
numObjWriterFactory - the factory from which to get objects that will be used to write numbered objects to the log file
bindingName - the name under which this switchboard will be bound using Naming.bind or Naming.rebind, so that this switchboard can unexport itself when it is finished
Method Detail

getDefaultObjectReaderFactory

public static final ObjectReaderFactory getDefaultObjectReaderFactory()
Returns the default ObjectReaderFactory for un-numbered objects, which uses an ObjectInputStream from which to read objects.


getDefaultNumberedObjectReaderFactory

public static final ObjectReaderFactory getDefaultNumberedObjectReaderFactory()
Returns the default ObjectReaderFactory for numbered objects, which uses an ObjectInputStream from which to read objects.


getDefaultObjectWriterFactory

public static final ObjectWriterFactory getDefaultObjectWriterFactory()
Returns the default ObjectWriterFactory for un-numbered objects, which uses an ObjectOutputStream to write objects.


getDefaultNumberedObjectWriterFactory

public static final ObjectWriterFactory getDefaultNumberedObjectWriterFactory()
Returns the default ObjectWriterFactory for numbered objects, which uses an ObjectOutputStream to write objects.


setPolicyFile

public static void setPolicyFile(Properties props)
Calls setPolicyFile(String) with the value of the SwitchboardRemote.switchboardPolicyFile property obtained from the specified Properties object.

Parameters:
props - the Properties object from which to obtain the value of the SwitchboardRemote.switchboardPolicyFile property

setPolicyFile

public static void setPolicyFile(Class cl,
                                 Properties props)
Calls setPolicyFile(Class,String) with the specified class and the value of the SwitchboardRemote.switchboardPolicyFile property obtained from the specified Properties object.

Parameters:
props - the Properties object from which to obtain the value of the SwitchboardRemote.switchboardPolicyFile property

setPolicyFile

public 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

public 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"

bind

public void bind(Properties settings,
                 String encoding)
          throws RemoteException,
                 MalformedURLException
Sets the specified settings and langauge encoding and then exports this switchboard and binds it to the bootstrap RMI registry.

This is a convenience method that calls setSettings(Properties), setEncoding(String), export() and then Naming.rebind. By using this method, a class that kick-starts a switchboard need only construct one, call this method and then (optionally) repeatedly call processFile until there are no more files to process, finally calling cleanup, as shown in the following sample code:

 public class StartSwitchboard {
   public static void main(String args[]) {
     try {
       Switchboard sb = new Switchboard();
       sb.bind(null, System.getProperty("file.encoding"));
       // process files specified on the command line
       for (int i = 0; i < args.length; i++)
         sb.processFile(args[i]);
       sb.cleanup();
     } catch (Exception e) {
       System.err.println(e);
     }
   }
 }
 
The above code processes each file in sequence, where each call to processFile returns only when the file has been completely processed. In order to simply enqueue all files for processing and then be notified when all processing is complete, the user should call processFile(String,String,String,boolean) with a value of false for the final argument, indicating not to wait. After all files have been enqueued, the user may call to cleanupWhenAllFilesAreDone(), which will not return until all enqueued files have been processed.

Parameters:
settings - the settings that should be set before this object is exported and bound, or null if setSettings(java.util.Properties) should not be called with the specified value
encoding - the language encoding that should be set before this object is exported and bound, or null if {link #setEncoding} should not be called with the specified value
Throws:
RemoteException
MalformedURLException
See Also:
processFile(String), processFile(String,String,String,boolean), cleanup(), cleanupWhenAllFilesAreDone(), setSettings(Properties), setEncoding(String), export()

export

public void export()
            throws RemoteException
Exports this object using UnicastRemoteObject.exportObject.

Throws:
RemoteException

processFile

public void processFile(String inFilename)
Processes the specified input file and creates an output file with the specified name; a log file will be used to keep track of incremental work. The name of the output file will be inFilename + outFilenameSuffix. The name of the log file will be inFilename + logFilenameSuffix.

Objects will be read from the input file, doled out to clients upon request, and when the clients have processed all the objects, the output file will be created, putting the processed objects in the same order in which their unprocessed counterparts existed in the input file. This method will return as soon as object-processing is complete (but possibly before the output file has been created).

Parameters:
inFilename - the name of the input file to be processed
See Also:
processFile(String,String)

processFile

public void processFile(String inFilename,
                        String outFilename)
Processes the specified input file and creates an output file with the specified name; a log file will be used to keep track of incremental work. The name of the log file will be inFilename + logFilenameSuffix.

Objects will be read from the input file, doled out to clients upon request, and when the clients have processed all the objects, the output file will be created, putting the processed objects in the same order in which their unprocessed counterparts existed in the input file. This method will return as soon as object-processing is complete (but possibly before the output file has been created).

Parameters:
inFilename - the name of the input file to be processed
outFilename - the name of the output file to be created
See Also:
processFile(String,String,String)

processFile

public void processFile(String inFilename,
                        String outFilename,
                        String logFilename)
Processes the specified input file and creates an output file with the specified name; a log file with the specified name will be used to keep track of incremental work.

Objects will be read from the input file, doled out to clients upon request, and when the clients have processed all the objects, the output file will be created, putting the processed objects in the same order in which their unprocessed counterparts existed in the input file. This method will return as soon as object-processing is complete (but possibly before the output file has been created).

Parameters:
inFilename - the name of the input file to be processed
outFilename - the name of the output file to be created
logFilename - the name of the log file (which is used to keep track of incremental work during input file processing)
See Also:
processFile(String,String,String,boolean)

processFile

public void processFile(String inFilename,
                        String outFilename,
                        String logFilename,
                        boolean wait)
Processes the specified input file and creates an output file with the specified name; a log file with the specified name will be used to keep track of incremental work.

Objects will be read from the input file, doled out to clients upon request, and when the clients have processed all the objects, the output file will be created, putting the processed objects in the same order in which their unprocessed counterparts existed in the input file.

Parameters:
inFilename - the name of the input file to be processed
outFilename - the name of the output file to be created
logFilename - the name of the log file (which is used to keep track of incremental work during input file processing)
wait - if true, indicates whether this method should wait until object processing is complete or, if false, return immediately

setSettings

public void setSettings(Properties settings)
Sets the internal settings of this switchboard to the specified Properties object. This object is returned by the getSettings() method, to allow clients and servers to all have the same settings.

If the specified Properties object contains any of the switchboard-specific properties specified in SwitchboardRemote, the internal settings of this Switchboard object are set accordingly.

See Also:
getSettings(), SwitchboardRemote.socketTimeout, SwitchboardRemote.keepAliveInterval, SwitchboardRemote.keepAliveMaxRetries, SwitchboardRemote.serverDeathKillClients

setEncoding

public void setEncoding(String enc)
Sets the default character encoding (applicable if any ObjectReader or ObjectWriter instances created by the switchboard's factories are character-based).


setBufSize

public void setBufSize(int bufSize)
Sets the buffer size to be used for all streams by the switchboard (except the messages output file, which uses the value of defaultBufSize).


getSetting

public String getSetting(String settingName)
                  throws RemoteException
Gets the value for the specified settings from the switchboard's internal Properties object.

Specified by:
getSetting in interface SwitchboardRemote
Throws:
RemoteException

getSettings

public Properties getSettings()
                       throws RemoteException
Gets the internal Properties object used for various settings of this switchboard.

Specified by:
getSettings in interface SwitchboardRemote
Throws:
RemoteException

register

public int register(Client client)
             throws RemoteException
Description copied from interface: SwitchboardRemote
Registers a client with the switchboard. The switchboard may optionally output a message about the registration to a log file.

Specified by:
register in interface SwitchboardRemote
Parameters:
client - the client that is registering
Returns:
a unique ID for the registering client that is greater than or equal to 0
Throws:
RemoteException

register

public int register(Server server)
             throws RemoteException
Description copied from interface: SwitchboardRemote
Register a server with the switchboard.

The Server interface has a method allowing the server to specify a maximum number of clients it is willing to accept, Server.maxClients(). If the return value of the server's maxClients method is Server.acceptUnlimitedClients, then the server is registered to accept an essentially limitless number of clients (the default is currently 100,000).

If the server's Server.acceptClientsOnlyByRequest() method returns true, a client can gain access to the server only by requesting it directly, via the SwitchboardRemote.getServer(int,int) method. This allows a client-server pair to "arrange" to be hooked together, such as when it is desirable to have a single server per client. In such a scenario, a server whose acceptClientsOnlyByRequest method returns true would register, then pass its server ID number to a client so that the client could specifically request this server using getServer(int,int), whereby the switchboard would be informed as to their connection. If the client and server making this arrangement are both running on the same host, the client could optionally make all method calls directly to the server, instead of via RMI. In such a scheme, the switchboard becomes merely an object server.

Specified by:
register in interface SwitchboardRemote
Parameters:
server - the server being registered
Returns:
a unique ID for the registering server that is greater than or equal to 0
Throws:
RemoteException
See Also:
Server.maxClients(), SwitchboardRemote.getServer(int,int)

getServer

public Server getServer(int clientId)
                 throws RemoteException
Description copied from interface: SwitchboardRemote
Returns a Server for use by a client. If the switchboard contains multiple servers, it should try to load-balance them, typically by assigning the requesting client the server with the lowest load. This method should typically be called once per life of the client. The switchboard may optionally record the connection between the client and server to a log file.

It is guaranteed that if a valid server is found, its data will be updated by calling its maxClients and acceptClientsOnlyByRequest methods and caching their values. This method may also update other servers' data.

While a primary purpose of this method is for clients to get a server initially, or simply when their current server fails, this method may be called in the middle of a run simply to provide dynamic load-balancing. Clients may, for example, implement a policy of obtaining a new server prior to the processing of each object (if they are using the object-serving functionality of the switchboard). With such a policy, as new servers are brought up and registered, existing clients using more heavily-loaded servers will be migrated to those new, initially-lightly-loaded servers until the loads are as balanced as possible.

Specified by:
getServer in interface SwitchboardRemote
Parameters:
clientId - the ID of the client invoking this method to request a server
Returns:
a Server for use by the caller, or null if there are currently no servers registered with this switchboard, if all servers are fully loaded with their maximum number of clients or are only accepting clients by request
Throws:
RemoteException
See Also:
Server.maxClients(), Server.acceptClientsOnlyByRequest()

getServer

public Server getServer(int clientId,
                        int serverId)
                 throws RemoteException
Description copied from interface: SwitchboardRemote
Returns a Server associated with the specified server ID to the requesting client. If the server with the specified ID exists but its maximum number of clients is greater than 0 and has been reached, then null is returned.

It is guaranteed that if a valid server is found, its data will be updated by calling its maxClients and acceptClientsOnlyByRequest methods and caching their values. Other servers' data may also be updated by this method.

Specified by:
getServer in interface SwitchboardRemote
Parameters:
clientId - the ID of the client invoking this method to request a server
serverId - the ID of the server being requested by the client invoking this method
Returns:
the server associated with serverId, or null if the requested server has a non-zero number of clients equal to its maximum (that is, if it is fully loaded)
Throws:
RemoteException
See Also:
Server.maxClients(), Server.acceptClientsOnlyByRequest()

nextObject

public NumberedObject nextObject(int clientId)
                          throws RemoteException
Description copied from interface: SwitchboardRemote
Gets the next object for the specified client; returns null if there is not currently an object to be processed. Clients should continually call this method, waiting a fixed interval between calls, until they are told to die. The interval between calls should be the value of the property SwitchboardRemote.clientNextObjectInterval.
N.B.: NumberedObject instances contain two data members that are immutable: the object's unique ID number, and another unique ID number indicating the file from which the object was read, for which there is no public accessor. It is therefore crucial that clients manipulate and use the very same NumberedObject instance as the second argument to the SwitchboardRemote.putObject(int,NumberedObject,long) method.

Specified by:
nextObject in interface SwitchboardRemote
Parameters:
clientId - the ID number of the client requesting the next object
Returns:
the next object to process in the input file specified to the switchboard, or null if there are no more objects
Throws:
RemoteException
See Also:
SwitchboardRemote.clientNextObjectInterval

registerConsumer

public void registerConsumer(Consumer consumer)
                      throws RemoteException
Registers the specified consumer of processed objects with this switchboard. It is guaranteed that the consumer's Consumer.newFile(String,String) method will be invoked before this registration method returns. Note that it is possible that all objects from the current file could have been processed before this method returns. In order to guarantee that one or more consumers post-process all objects of a particular input file, the consumers should be registered, via this method, before files are processed via one of the processFile methods.

Specified by:
registerConsumer in interface SwitchboardRemote
Parameters:
consumer - the consumer to be registered
Throws:
RemoteException
See Also:
Consumer.newFile(String,String), processFile(String), processFile(String,String), processFile(String,String,String), processFile(String,String,String,boolean)

putObject

public void putObject(int clientId,
                      NumberedObject obj,
                      long millis)
               throws RemoteException
Description copied from interface: SwitchboardRemote
Sends a processed object back to the switchboard object.
N.B.: NumberedObject instances contain two data members that are immutable: the object's unique ID number, and another unique ID number indicating the file from which the object was read, for which there is no public accessor. It is therefore crucial that clients manipulate and use the very same NumberedObject instance that was retrieved using the SwitchboardRemote.nextObject(int) method as the second argument to the this method.

Specified by:
putObject in interface SwitchboardRemote
Parameters:
clientId - the ID number of the client requesting the next object
obj - the processed object and its number, or null if the client was unable to process the object
millis - the number of milliseconds the client took to process the object
Throws:
RemoteException

waitUntilAllFilesAreDone

public void waitUntilAllFilesAreDone()

cleanupWhenAllFilesAreDone

public void cleanupWhenAllFilesAreDone()

cleanup

public void cleanup()
Cleans up by telling all switchboard users to die, since object processing is complete.


getVerbose

public boolean getVerbose()
Gets the verbosity status of the switchboard.


setVerbose

public void setVerbose(boolean verbose)
Sets the verbosity status of the switchboard.


getKeepAliveInterval

public int getKeepAliveInterval()
                         throws RemoteException
Specified by:
getKeepAliveInterval in interface SwitchboardRemote
Throws:
RemoteException

getKeepAliveMaxRetries

public int getKeepAliveMaxRetries()
                           throws RemoteException
Specified by:
getKeepAliveMaxRetries in interface SwitchboardRemote
Throws:
RemoteException

Parsing Engine

Author: Dan Bikel.