stella.net

Class Handler

java.lang.Object

java.lang.Thread

stella.net.Handler

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

CommandReceiver.CommandHandler, ErrorReceiver.ErrorHandler, ParameterRelay.ParameterHandler, ParameterServer.ParameterHandler

public abstract class Handler
extends Thread

The base class for protocol providers. On construct a client socket is accepted and the input and output streams associated with the socket are created. A reference to the spawning ReceiverServer is stored to pipe error messages to its ReceiverServer.processError(stella.ErrorEvent) method.

A handler always runs as a thread because it handles the whole communication between server and client which is normally a time-consuming process. It does not start automatically. After the communication is complete the close() method should be called to allow necessary cleanup, i.e. closing of the streams and the client socket.

To avoid cpu-starvation due to low priority, the priority of the handler thread can be specified after construct using the Thread's setPriority method. Otherwise the default priority is used.

This class is defined abstract due to its (protected) runProtocol() method. Concrete implementations should follow these prescriptions.

• Do not rely on defined input or output streams. They are opened during the initialization of the handler, but if this step fails they may still be null in the run phase.
• Use the spawner's ReceiverServer.processError(stella.ErrorEvent) for reporting any errors.
• Calling the close() method should terminate the protocol.
• Closing of the streams and the client socket is not done before the run method exits, i.e. when runProtocol() returns. It must be performed by explicetly calling close().

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field and Description
private Socket	client The client socket this handler is connected to.
private static long	ID A session ID.
protected InputStream	in The input stream associated with this handler's client socket.
protected OutputStream	out The output stream associated with this handler's client socket.
protected ErrorProcessing	spawner The reference to the spawning server.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Handler(ErrorProcessing spawn, Socket connect, ThreadGroup group, String name) Constructs a new handler.

Method Summary

Modifier and Type	Method and Description
protected void	close() Closes the input and output streams and the associated socket.
void	init() Initializes this handler.
private static long	nextID() Returns the next session ID.
void	run() The rudimentary run method.
protected abstract void	runProtocol() The protocol implementation.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

client

private Socket client

The client socket this handler is connected to.

in

protected InputStream in

The input stream associated with this handler's client socket.

out

protected OutputStream out

The output stream associated with this handler's client socket.

spawner

protected ErrorProcessing spawner

The reference to the spawning server.

ID

private static long ID

A session ID.

Constructor Detail

Handler

protected Handler(ErrorProcessing spawn,
                  Socket connect,
                  ThreadGroup group,
                  String name)

Constructs a new handler. The spawning thread and the client socket must be specified.

Parameters:

spawn - The spawning server used for error processing.

connect - The socket this handler is conneted to.

group - The thread group the handler should run in.

name - The handlers thread-name.

Method Detail

nextID

private static long nextID()

Returns the next session ID.

init

public void init()

Initializes this handler. This method is called immediately after the construction phase. It opens the stream associated with the socket.

close

protected void close()

Closes the input and output streams and the associated socket.

run

public void run()

The rudimentary run method. Calls the abstract runProtocol() method. Protocolls that want automatic closing of the socket must call the close() method explicetly.

Specified by:

run in interface Runnable

Overrides:

run in class Thread

runProtocol

protected abstract void runProtocol()

The protocol implementation. Please keep the following hints in mind if providing a body to this method.

• Do not rely on defined input or output streams. They are opened during the initialization of the handler, but if this step fails they may still be null in the run phase.
• Use the spawner's ReceiverServer.processError(stella.ErrorEvent) for reporting any errors.
• Calling the close() method should terminate the protocol.
• Closing of the streams and the client socket is not done before the run method exits, i.e. when runProtocol() returns.