votorola.a
Class ElectoralService

java.lang.Object
  ElectoralService

Direct Known Subclasses:

Election, MailMetaService, Register

@ThreadRestricted(value="holds lock()")
public abstract class ElectoralService
extends Object

A facility for voters to access and maintain a specific class of electoral data on a subserver.

Field Summary

protected Object	configurationContext Stored as a convenience for subclass initialization, may be nulled afterwards by subclass.
protected ReentrantLock	lock
protected String	name
protected String	serviceEmail
protected ElectoralSubserver.Run	subserverRun

Constructor Summary

protected

ElectoralService(ElectoralSubserver.Run subserverRun, String name, Object configurationContext) Partially creates an ElectoralService.

Method Summary

abstract File	configurationFile() The primary configuration file for this electoral service.
Exception	dispatch(String[] argArray, CommandResponder.Session commandSession) Looks up the responder of the specified command, and sends the command to it.
Exception	dispatch(String[] argArray, CommandResponder.Session commandSession, CommandResponder responder) Sends a command to its responder, if one is specified.
static void	ensureSchema(Database database, String name) Ensures the database has a schema for the specified electoral service, creating it if necessary.
boolean	equals(Object o) Returns true iff o is an electoral service with the same service email address.
Exception	help(String[] argv, CommandResponder.Session session) Responds to a help command on behalf of the nominal responder, per respond(argv,session).
protected void	helpA(ReplyBuilder replyB, CommandResponder.Session session)
protected void	helpB(ReplyBuilder replyB, CommandResponder.Session session)
protected void	helpC(ReplyBuilder replyB, CommandResponder.Session session)
protected void	init(ArrayList<CommandResponder> responderList)
ReentrantLock	lock() Returns the thread access lock for this service.
String	name() The name that identifies this service, uniquely among all services on the subserver.
CommandResponder	responderByClassName(String className) Returns the responder of a particular class name, or null if there is none.
CommandResponder	responderForCommand(String[] argArray, CommandResponder.Session commandSession) Returns the responder for the specified command, or null if there is none.
CommandResponder[]	responders() Returns an array of all responders.
String	serviceEmail() The email address that identifies this service.
ElectoralSubserver.Run	subserverRun() The subserver run, in which this service is provided.
abstract String	summaryDescription() A brief description of this service, in sentence form.
abstract String	title() The title of this service, in title case.
String	toString() Returns the service email address.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

lock

protected final ReentrantLock lock

name

protected final String name

serviceEmail

protected final String serviceEmail

subserverRun

protected final ElectoralSubserver.Run subserverRun

configurationContext

protected Object configurationContext

Stored as a convenience for subclass initialization, may be nulled afterwards by subclass.

Constructor Detail

ElectoralService

protected ElectoralService(ElectoralSubserver.Run subserverRun,
                           String name,
                           Object configurationContext)

Partially creates an ElectoralService. To complete it, call init(responderList).

Parameters:

configurationContext - per configurationContext

Method Detail

init

@ThreadRestricted(value="constructor")
protected final void init(ArrayList<CommandResponder> responderList)

Parameters:

responderList - listing only the service-specific responders (general responders will be added here)

configurationFile

@ThreadSafe
public abstract File configurationFile()

The primary configuration file for this electoral service. For an ordinary (non-meta) service, it is typically located at:

votorola-directory/services/service-name/service.js

The language is JavaScript. There are restrictions on the character encoding.

dispatch

public Exception dispatch(String[] argArray,
                          CommandResponder.Session commandSession)

Looks up the responder of the specified command, and sends the command to it. Or, if the look-up fails, replies that the command is unrecognized.

Parameters:

argArray - an array containing the command name and arguments, per CommandResponder.respond(argv,session)

Returns:

any soft exception, per CommandResponder.respond(argv,session); or null if none occured

See Also:

CommandResponder.respond(String[],CommandResponder.Session)

dispatch

public final Exception dispatch(String[] argArray,
                                CommandResponder.Session commandSession,
                                CommandResponder responder)

Sends a command to its responder, if one is specified. Or, if none is specified, replies that the command is unrecognized.

Parameters:

argArray - an array containing the command name and arguments, per CommandResponder.respond(argv,session)

responder - the responder for the command, or null if there is none

Returns:

any soft exception, per CommandResponder.respond(argv,session); or null if none occured

See Also:

responderForCommand(String[],CommandResponder.Session), CommandResponder.respond(String[],CommandResponder.Session)

ensureSchema

@ThreadSafe
public static void ensureSchema(Database database,
                                           String name)
                         throws SQLException

Ensures the database has a schema for the specified electoral service, creating it if necessary.

Throws:

SQLException

help

public Exception help(String[] argv,
                      CommandResponder.Session session)

Responds to a help command on behalf of the nominal responder, per respond(argv,session).

lock

public final ReentrantLock lock()

Returns the thread access lock for this service. Locking order: first lock the election, then lock the register.

See Also:

ElectoralSubserver.Run.singleServiceLock()

name

@ThreadSafe
public final String name()

The name that identifies this service, uniquely among all services on the subserver. It must be valid as the local part (before the '@') of an email address, in unquoted (dot-atom) form. It may therefore contain ASCII alpha-numeric characters (A-Z, a-z, 0-9), and most punctuation characters (!, #, $, %, &, ', *, +, -, /, =, ?, ^, _, `, {, |, }, ~ ). It may also include a period (.), but may not begin with one. However, it is recommended that all names be restricted to the common characters (A-Z, a-z, 0-9, -, _) and dot (., except no dot as the first character).

The name must not exceed 63 characters in length. This is a PostgreSQL limit. (The next limit would be to 'avoid local parts [of email addresses] longer than 64 characters', per qmail addresses(5).)

The name ought to be unique among all services of the subserver, and all other subservers that share the same server name.

See Also:

serviceEmail()

responderByClassName

public final CommandResponder responderByClassName(String className)

Returns the responder of a particular class name, or null if there is none.

responderForCommand

public final CommandResponder responderForCommand(String[] argArray,
                                                  CommandResponder.Session commandSession)

Returns the responder for the specified command, or null if there is none.

Parameters:

argArray - array of command name and arguments, per CommandResponder.respond(argv,session)

responders

public final CommandResponder[] responders()

Returns an array of all responders.

serviceEmail

@ThreadSafe
public String serviceEmail()

The email address that identifies this service. It is constructed from the service and server names, as 'service-name@server-name'.

Returns:

canonical email address (having no personal part)

subserverRun

@ThreadSafe
public final ElectoralSubserver.Run subserverRun()

The subserver run, in which this service is provided.

summaryDescription

public abstract String summaryDescription()

A brief description of this service, in sentence form. It is intended for display, for example, as an introductory paragraph.

title

public abstract String title()

The title of this service, in title case.

equals

@ThreadSafe
public final boolean equals(Object o)

Returns true iff o is an electoral service with the same service email address.

Overrides:

equals in class Object

toString

@ThreadSafe
public final String toString()

Returns the service email address.

Overrides:

toString in class Object

helpA

protected final void helpA(ReplyBuilder replyB,
                           CommandResponder.Session session)

helpB

protected final void helpB(ReplyBuilder replyB,
                           CommandResponder.Session session)

helpC

protected final void helpC(ReplyBuilder replyB,
                           CommandResponder.Session session)