edu.wpi.prc.server
Class ServerRPCHandler

java.lang.Object
  extended by edu.wpi.prc.server.ServerRPCHandler

public class ServerRPCHandler
extends java.lang.Object

Processes all client XML-RPC requests by delegating to the appropriate classes.

Author:
James Baldassari

Field Summary
private  int numTransactions
           
 
Constructor Summary
ServerRPCHandler()
           
 
Method Summary
 boolean addUser(java.lang.String userID, java.lang.String eMailAddress)
          Adds a new user to the system.
 int addWorkUnit(byte[] data)
          Adds an ingress work unit to the transitioner using all default values.
 int addWorkUnit(byte[] data, int priority, int points)
          Adds an ingress work unit to the transitioner.
 int addWorkUnit(byte[] data, int priority, int points, double expirationTime)
          Adds an ingress work unit to the transitioner.
 int addWorkUnit(java.lang.String taskID, byte[] data, int priority, int points)
          Adds an ingress work unit to the transitioner.
 int addWorkUnit(java.lang.String taskID, byte[] data, int priority, int points, double expirationTime)
          Adds an ingress work unit to the transitioner.
private  void beginTransaction()
          Begins a transaction.
private  void endTransaction()
          Ends a transaction.
private  Result findResult(java.lang.String resultID)
          Searches the database for a result with the given ID.
private  Volunteer findUser(java.lang.String userID, java.lang.String eMailAddress)
          Finds the volunteer in the database with the given user ID.
private  WorkUnit findWorkUnit(java.lang.String workUnitID)
          Searches the database for a work unit with the given ID.
 java.util.Vector getAssociatedWorkUnit(java.lang.String resultID)
          Gets work unit data associated with the given result.
 java.util.Vector getLastWorkUnit()
          Searches the database for the last work unit that was added (by creation date).
 int getNumTransactions()
           
 int getNumWorkUnits()
           
 java.util.Vector getResultForValidation()
          Gets the next result to be validated, or a set of results for which a canonical result must be selected.
 java.util.Vector getValidResultQueue(java.lang.String password)
          Returns the valid result queue.
 java.util.Vector getWorkUnit(java.lang.String userID, java.lang.String eMailAddress)
          Gets the next available work unit to be computed by the given user.
 boolean kill(java.lang.String password)
          Shuts down the server without waiting for all transitioner transactions to complete.
 boolean markResultInvalid(java.lang.String resultID)
          Informs the transitioner that the specified ingress result is NOT valid.
 boolean markResultValid(java.lang.String resultID)
          Informs the transitioner that the specified ingress result is valid.
 boolean returnResult(java.lang.String userID, java.lang.String eMailAddress, java.lang.String workUnitID, byte[] resultData)
          Adds an ingress result to the transitioner.
 boolean selectCanonicalResult(java.lang.String resultID)
          Designates a result as the canonical result for a work unit.
 boolean shutdown(java.lang.String password)
          Shuts down the server if given the correct password.
 boolean verifyUser(java.lang.String userID, java.lang.String eMailAddress)
          Determines whether a given user is a member of the project.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

numTransactions

private volatile int numTransactions
Constructor Detail

ServerRPCHandler

public ServerRPCHandler()
Method Detail

getNumTransactions

public int getNumTransactions()
Returns:
Returns the number of outstanding transactions that can cause changes in data and/or state.

beginTransaction

private void beginTransaction()
Begins a transaction. This method will cause the calling thread to block if the transitioner is not running.


endTransaction

private void endTransaction()
Ends a transaction.


getWorkUnit

public java.util.Vector getWorkUnit(java.lang.String userID,
                                    java.lang.String eMailAddress)
                             throws EmptyQueueException,
                                    InvalidUserException
Gets the next available work unit to be computed by the given user.

Parameters:
userID - The volunteer's user ID.
eMailAddress - The user's e-mail address.
Returns:
Returns a new WorkUnit.
Throws:
EmptyQueueException
InvalidUserException

getLastWorkUnit

public java.util.Vector getLastWorkUnit()
                                 throws EmptyQueueException
Searches the database for the last work unit that was added (by creation date).

Returns:
Returns the last work unit that was added.
Throws:
EmptyQueueException

getAssociatedWorkUnit

public java.util.Vector getAssociatedWorkUnit(java.lang.String resultID)
                                       throws InvalidTaskException
Gets work unit data associated with the given result. This can be used by the result validator if it is necessary to examine the work unit from which the result was computed.

Parameters:
resultID - The result for which to find the associated work unit data.
Returns:
Returns the work unit data associated with the given result.
Throws:
InvalidTaskException

returnResult

public boolean returnResult(java.lang.String userID,
                            java.lang.String eMailAddress,
                            java.lang.String workUnitID,
                            byte[] resultData)
                     throws InvalidUserException,
                            InvalidTaskException,
                            UnassignedUserException
Adds an ingress result to the transitioner.

Parameters:
userID - The user who computed the result.
eMailAddress - The user's e-mail address.
resultData - The data contained in the result.
Returns:
True if the result was added to the database/transitioner, false if it was not added due to null resultData.
Throws:
InvalidUserException
InvalidTaskException
UnassignedUserException

findUser

private Volunteer findUser(java.lang.String userID,
                           java.lang.String eMailAddress)
                    throws InvalidUserException
Finds the volunteer in the database with the given user ID.

Parameters:
userID - The user ID to search for.
eMailAddress - The user's e-mail address.
Returns:
The first volunteer in the database with the given user ID.
Throws:
InvalidUserException

findWorkUnit

private WorkUnit findWorkUnit(java.lang.String workUnitID)
                       throws InvalidTaskException
Searches the database for a work unit with the given ID.

Parameters:
workUnitID - The ID of the work unit to find.
Returns:
Returns the work unit with the given ID.
Throws:
InvalidTaskException

findResult

private Result findResult(java.lang.String resultID)
                   throws InvalidTaskException
Searches the database for a result with the given ID.

Parameters:
resultID - The ID of the result to find.
Returns:
Returns the result with the given ID.
Throws:
InvalidTaskException

addUser

public boolean addUser(java.lang.String userID,
                       java.lang.String eMailAddress)
Adds a new user to the system.

Parameters:
userID - The user ID for the new user.
eMailAddress - The new user's e-mail address.
Returns:
Returns true if the user was successfully added, false if the user already exists in the database.

verifyUser

public boolean verifyUser(java.lang.String userID,
                          java.lang.String eMailAddress)
Determines whether a given user is a member of the project.

Parameters:
userID - The user ID to search for.
eMailAddress - The new user's e-mail address.
Returns:
Returns true if the user is a member of the project, false otherwise.

addWorkUnit

public int addWorkUnit(java.lang.String taskID,
                       byte[] data,
                       int priority,
                       int points,
                       double expirationTime)
                throws DuplicateTaskIDException
Adds an ingress work unit to the transitioner.

Parameters:
taskID - The ID of the new work unit.
data - The data contained in the work unit.
priority - The priority of the work unit.
points - The point value of the work unit.
expirationTime - The number of seconds until the work unit should expire.
Returns:
The number of users who are still waiting for a work unit.
Throws:
DuplicateTaskIDException

addWorkUnit

public int addWorkUnit(java.lang.String taskID,
                       byte[] data,
                       int priority,
                       int points)
                throws DuplicateTaskIDException
Adds an ingress work unit to the transitioner.

Parameters:
taskID - The ID of the new work unit.
data - The data contained in the work unit.
priority - The priority of the work unit.
points - The point value of the work unit.
Returns:
The number of users who are still waiting for a work unit.
Throws:
DuplicateTaskIDException

addWorkUnit

public int addWorkUnit(byte[] data,
                       int priority,
                       int points,
                       double expirationTime)
Adds an ingress work unit to the transitioner.

Parameters:
data - The data contained in the work unit.
priority - The priority of the work unit.
points - The point value of the work unit.
expirationTime - The number of seconds until the work unit should expire.
Returns:
The number of users who are still waiting for a work unit.

addWorkUnit

public int addWorkUnit(byte[] data,
                       int priority,
                       int points)
Adds an ingress work unit to the transitioner.

Parameters:
data - The data contained in the work unit.
priority - The priority of the work unit.
points - The point value of the work unit.
Returns:
The number of users who are still waiting for a work unit.

addWorkUnit

public int addWorkUnit(byte[] data)
Adds an ingress work unit to the transitioner using all default values.

Parameters:
data - The data contained in the work unit.
Returns:
The number of users who are still waiting for a work unit.

getNumWorkUnits

public int getNumWorkUnits()
Returns:
Returns the number of ingress work units in the system.

getResultForValidation

public java.util.Vector getResultForValidation()
                                        throws EmptyQueueException
Gets the next result to be validated, or a set of results for which a canonical result must be selected.

Returns:
Vector containing one or more results.
Throws:
EmptyQueueException

markResultValid

public boolean markResultValid(java.lang.String resultID)
Informs the transitioner that the specified ingress result is valid.

Parameters:
resultID - The ID of the ingress result to mark as valid.
Returns:
Returns true if the the result was successfully marked valid, false otherwise.

markResultInvalid

public boolean markResultInvalid(java.lang.String resultID)
Informs the transitioner that the specified ingress result is NOT valid.

Parameters:
resultID - The ID of the ingress result to mark as invalid.
Returns:
Returns true if the the result was successfully marked invalid, false otherwise.

selectCanonicalResult

public boolean selectCanonicalResult(java.lang.String resultID)
Designates a result as the canonical result for a work unit.

Parameters:
resultID - The task ID of the canonical result.
Returns:
Returns true if the canonical result was successfully selected, false if the result did not exist.

getValidResultQueue

public java.util.Vector getValidResultQueue(java.lang.String password)
                                     throws InvalidPasswordException
Returns the valid result queue. Builds a vector that has twice as many elements as the number of valid results. The first element for each result is the task ID of that result's associated work unit. The second element is the result data.

Parameters:
password - The project password.
Returns:
Returns a Vector containing all valid results in the format described above.
Throws:
InvalidPasswordException

shutdown

public boolean shutdown(java.lang.String password)
                 throws InvalidPasswordException
Shuts down the server if given the correct password. This RPC will cause the server to wait for all transitioner transactions to complete before shutting down.

Parameters:
password - The project password.
Returns:
Returns true.
Throws:
InvalidPasswordException

kill

public boolean kill(java.lang.String password)
             throws InvalidPasswordException
Shuts down the server without waiting for all transitioner transactions to complete. This RPC should be used only if one or more RPCs are "stuck," and the server is waiting for an indefinite time for them to complete.

Parameters:
password - The project password.
Returns:
Returns true.
Throws:
InvalidPasswordException