Parsing Engine

danbikel.switchboard
Interface SwitchboardRemote

All Superinterfaces:
Remote
All Known Implementing Classes:
Switchboard

public interface SwitchboardRemote
extends Remote

The methods by which both clients and servers register with a single RMI-accessible Switchboard object. Clients and servers both get their settings from the switchboard, and then, upon a client's request, the switchboard assigns the client to a server. Implementations are encouraged to load-balance when assigning clients to servers, typically via assigning a client to the server with the least number of clients. The switchboard also serves as a "object server" for clients.

See Also:
SwitchboardUser

Field Summary
static String clientDisableHttp
           
static String clientNextObjectInterval
          The property to specify the interval, in milliseconds, between client requests for an object to process, after nextObject(int) returns null.
static String clientPolicyFile
           
static String keepAliveInterval
          The property to specify how often clients and servers should ping the "keep-alive" socket connected to the switchboard.
static String keepAliveMaxRetries
          The property to specify at most how many times the switchboard attempts to contact clients and servers before considering them dead (after an initial failure, thus making 0 a legal value for this property).
static String serverDeathKillClients
          The property to specify whether the switchboard should kill all of a server's clients when it detects that the server has died.
static String serverDisableHttp
           
static String serverPolicyFile
           
static String socketTimeout
          The property to specify how long, in milliseconds, the SO_TIMEOUT value should be for the switchboard's RMI-client (caller) sockets.
static String sortOutput
          The property to specify whether the switchboard should sort the log file entries when creating its final output file.
static String switchboardDisableHttp
           
static String switchboardPolicyFile
           
 
Method Summary
 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 setting (property) from the internal settings (Properties) object of the switchboard.
 Properties getSettings()
          Gets the settings contained within this switchboard, so that clients and servers all have the same settings.
 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 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.
 

Field Detail

socketTimeout

static final String socketTimeout
The property to specify how long, in milliseconds, the SO_TIMEOUT value should be for the switchboard's RMI-client (caller) sockets.

The value of this constant is "switchboard.socketTimeout".

See Also:
Switchboard.setSettings(Properties), Constant Field Values

keepAliveInterval

static final String keepAliveInterval
The property to specify how often clients and servers should ping the "keep-alive" socket connected to the switchboard. The value of this property should be (the string representation of) an integer, representing milliseconds between pings.

The value of this constant is "switchboard.keepAliveInterval".

See Also:
Switchboard.setSettings(Properties), Constant Field Values

keepAliveMaxRetries

static final String keepAliveMaxRetries
The property to specify at most how many times the switchboard attempts to contact clients and servers before considering them dead (after an initial failure, thus making 0 a legal value for this property).

The value of this constant is "switchboard.keepAliveMaxRetries".

See Also:
Switchboard.setSettings(Properties), Constant Field Values

serverDeathKillClients

static final String serverDeathKillClients
The property to specify whether the switchboard should kill all of a server's clients when it detects that the server has died. This property should have the value "false" when servers are stateless. The value of this property should be (the string representation of) a boolean (conversion is performed by the method Boolean.valueOf).

The value of this constant is "switchboard.serverDeathKillClients".

See Also:
Switchboard.setSettings(Properties), Constant Field Values

sortOutput

static final String sortOutput
The property to specify whether the switchboard should sort the log file entries when creating its final output file. The default behavior is to sort.

See Also:
Switchboard.setSettings(Properties), Constant Field Values

switchboardPolicyFile

static final String switchboardPolicyFile
See Also:
Constant Field Values

switchboardDisableHttp

static final String switchboardDisableHttp
See Also:
Constant Field Values

clientNextObjectInterval

static final String clientNextObjectInterval
The property to specify the interval, in milliseconds, between client requests for an object to process, after nextObject(int) returns null. This value of this property should be used by all implementations of the Client interface when complying with the general contract of the nextObject(int) method.

Note that this property does not apply to the switchboard itself, but only to clients, and therefore its value is not set internally by Switchboard.setSettings(Properties).

The value of this constant is "switchboard.client.nextObjectInterval".

See Also:
nextObject(int), Constant Field Values

clientPolicyFile

static final String clientPolicyFile
See Also:
Constant Field Values

clientDisableHttp

static final String clientDisableHttp
See Also:
Constant Field Values

serverPolicyFile

static final String serverPolicyFile
See Also:
Constant Field Values

serverDisableHttp

static final String serverDisableHttp
See Also:
Constant Field Values
Method Detail

getSetting

String getSetting(String settingName)
                  throws RemoteException
Gets the value for the specified setting (property) from the internal settings (Properties) object of the switchboard.

Throws:
RemoteException

getSettings

Properties getSettings()
                       throws RemoteException
Gets the settings contained within this switchboard, so that clients and servers all have the same settings.

Throws:
RemoteException

register

int register(Client client)
             throws RemoteException
Registers a client with the switchboard. The switchboard may optionally output a message about the registration to a log file.

Parameters:
client - the client that is registering
Returns:
a unique ID for the registering client that is greater than or equal to 0
Throws:
RegistrationException - if there is a problem during registration
RemoteException

register

int register(Server server)
             throws RemoteException
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 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.

Parameters:
server - the server being registered
Returns:
a unique ID for the registering server that is greater than or equal to 0
Throws:
RegistrationException - if there is a problem during registration, including if the Server.maxClients method does not return either a non-zero positive integer or Server.acceptUnlimitedClients.
RemoteException
See Also:
Server.maxClients(), getServer(int,int)

getServer

Server getServer(int clientId)
                 throws RemoteException
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.

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:
UnrecognizedClientException - if the specified client ID is not valid
RemoteException
See Also:
Server.maxClients(), Server.acceptClientsOnlyByRequest()

getServer

Server getServer(int clientId,
                 int serverId)
                 throws RemoteException
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.

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:
UnrecognizedClientException - if the specified client ID is not valid
UnrecognizedServerException - if the specified server ID is not valid
RemoteException
See Also:
Server.maxClients(), Server.acceptClientsOnlyByRequest()

registerConsumer

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.

Parameters:
consumer - the consumer to be registered
Throws:
RemoteException
See Also:
Consumer.newFile(String,String)

nextObject

NumberedObject nextObject(int clientId)
                          throws RemoteException
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 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 putObject(int,NumberedObject,long) method.

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:
UnrecognizedClientException - if the specified client ID is not valid
RemoteException
See Also:
clientNextObjectInterval

putObject

void putObject(int clientId,
               NumberedObject obj,
               long millis)
               throws RemoteException
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 nextObject(int) method as the second argument to the this method.

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:
UnrecognizedClientException - if the specified client ID is not valid
RemoteException

getKeepAliveInterval

int getKeepAliveInterval()
                         throws RemoteException
Throws:
RemoteException

getKeepAliveMaxRetries

int getKeepAliveMaxRetries()
                           throws RemoteException
Throws:
RemoteException

Parsing Engine

Author: Dan Bikel.