stella.net
Class ReceiverServer

java.lang.Object
  util.PropertyContainer
      util.PropertyResources
          util.PropertyBundles
              util.rmi.RmiPropertyContainer
                  util.rmi.AbstractRmiCaster
                      stella.CastingContainer
                          stella.net.ReceiverServer

All Implemented Interfaces:

Cloneable, Runnable, Remote, ErrorProcessing, CancelRunnable, ExitCleaning, Initializable, LocalizedSupplying, PropertySupplying, ResourceSupplying, RmiCaster, RmiPropertyBearing

Direct Known Subclasses:

ErrorServer, ParameterRelay

public abstract class ReceiverServer
extends CastingContainer
implements CancelRunnable, ErrorProcessing, Initializable, ExitCleaning

The receiver server base class. This abstract class is listening to the port specified in its properties. When a connection is established the abstract method protocol(java.net.Socket) is called with the client socket as an argument which is an abstract method in the base implementation. Concrete subclasses should provide their implementations of the protocol, like CommandReceiver or ErrorReceiver.

The details of this class's functionality can be described as follows.

• On startup this class creates a server socket listening on the port specified in the properties of this receiver.
• When a connection is established a helper thread is spawned. The helper thread, normally a subclass of Handler, takes over the client socket and is responsible for the entire communication ('protocol').
• The main receiver class immediately retakes the listening state once the protocol thread is started.
• The Handler first establishes the streams to the client and reads in the command sent by the client.
• It provides a Handler.close() method that closes the streams and the socket.

For convenience, the receiver server implements the Runnable interface. During construction (exactly in the init() method), a Thread is initialized with is directly linked with this receiver server. It can be querried with getAsociatedThread(). If full thread behaviour is intended, some parts of the codes have to be updated. The run method loops forever unless cancel is called.

Nested Class Summary

Nested classes/interfaces inherited from class util.PropertyResources

PropertyResources.URLResource

Field Summary

private boolean	cancel Gets true if this thread should exit.
private static int	COUNT An internal counter for automatic naming.
private static int	DEFBUFFERSIZE The default buffer size of the I/O streams (2048).
private static int	DEFHANDLERPRIORITY The default handler thread priority (Thread.NORM_PRIORITY).
private static long	DEFLOGOUT The default log-out time granted to clients.
private static String	DEFRECEIVERNAME The default receiver (Receiver-).
static int	DEFSERVERPORT The default port number (1026).
private static int	DEFSERVERPRIORITY The default server thread priority (1).
protected ThreadGroup	handlerGroup The thread group handlers run in.
static String	KEY_BUFFERSIZE The key in the properties for the stream buffer size.
static String	KEY_HANDLERPRIORITY The key in the properties defining the priority of the server.
static String	KEY_HOSTADDRESS The key to the host running the server.
static String	KEY_LOGOUT The key for the log-out time granted to the clients.
static String	KEY_RECEIVERNAME The key in the properties defining the name of this receiver.
static String	KEY_SERVERPORT The key for the socket port to listen to.
static String	KEY_SERVERPRIORITY The key in the properties defining the priority of the server.
private ServerSocket	listen The server socket the server listens to.
private Thread	thisThread A reference to the thread constructed from this Runnable.

Fields inherited from class util.rmi.AbstractRmiCaster

ALTERNATEHOST, ALTERNATEPORT, KEY_BINDNAME, KEY_EXPORTPORT, KEY_REGISTRYHOST, KEY_REGISTRYPORT

Fields inherited from class util.PropertyBundles

KEY_LOCALECOUNTRY, KEY_LOCALELANGUAGE, KEY_RESOURCEBUNDLES

Fields inherited from class util.PropertyResources

KEY_NOINITONCREATE, localurl, locate, POSTFIX_DIR, POSTFIX_EXT, POSTFIX_FILE, POSTFIX_LIST, POSTFIX_URL, urlset

Fields inherited from class util.PropertyContainer

KEY_LISTSEPARATOR, KEY_MAPKEYVALUECHAR, KEY_MAPSEPARATOR

Fields inherited from interface util.ResourceSupplying

KEY_URLRESOURCES, KEY_URLUSECONFIG, KEY_URLUSECURRENT, KEY_URLUSEHOME

Fields inherited from interface util.PropertySupplying

CONFIG, KEY_CLASS

Constructor Summary

protected

ReceiverServer(Map qualify) Constructs a new receiver with the specified properties.

Method Summary

void	cancel() Cancels the server thread.
void	exit() Closes the receiver socket.
Thread	getAsociatedThread() Returns the thread asociated with this server.
int	getBufferSize() Returns the buffer size used for buffering the socket streams.
int	getHandlerPriority() Returns the priority at which the connection handler thread should run.
String	getReceiverName() Returns the name used for binding this receiver.
int	getServerPort() Returns the port number the clients should connect to on this receiver.
int	getServerPriority() Returns the priority at which this thread (the server) should run.
void	init() Initializes the receiver server.
protected void	initReceiverServer() An escape pod for subclasses.
long	maxTimeToCancel() Returns the maximum time-out for this thread.
private static int	nextCount() Gets the next available number at automatic naming.
void	processError(ErrorEvent ee) An escape pod for subclasses that want to do anything special with errors or exceptions thrown during the lifecycle of this thread.
protected abstract void	protocol(Socket client) The method called as soon as a connection is established.
void	run() The run method of the receiver server.

Methods inherited from class stella.CastingContainer

addErrorListener, addRmiErrorListener, isValid, notifyErrorListener, removeErrorListener, removeRmiErrorListener, sendError, sendError, sendError, sendStatus, sendStatus, sendStatus

Methods inherited from class util.rmi.AbstractRmiCaster

bindAlternate, bindToRegistry, bindToRegistry, bindToRegistry, casterExit, casterExit, getBindName, getBindName, unbindFromRegistry, unbindFromRegistry

Methods inherited from class util.rmi.RmiPropertyContainer

containsRemoteProperty, getRemoteProperties, getRemoteProperty, setRemoteProperty

Methods inherited from class util.PropertyBundles

clone, getLocalized, getLocalized, getLocalizedString, getLocalizedString, loadResource

Methods inherited from class util.PropertyResources

createFrom, createFrom, createFrom, getApplet, getAsResources, getLocalClassLoader, getPropertiesToKey, getPropertiesToKey, getResource, getResourceAsStream, getResourceFromKey, getResources, keyCreate, keyCreate, reload, setApplet

Methods inherited from class util.PropertyContainer

augment, augment, augment, defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsEnums, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, isNew, parseObject, reload, removeProperty, rescanned, setObject, setProperties, setProperty, stringProperties, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface util.ResourceSupplying

getResource, getResourceAsStream, getResources

Methods inherited from interface util.PropertySupplying

defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, parseObject, removeProperty, setObject, setProperty, stringProperties

Field Detail

KEY_RECEIVERNAME

public static final String KEY_RECEIVERNAME

The key in the properties defining the name of this receiver.

See Also:

Constant Field Values

KEY_HOSTADDRESS

public static final String KEY_HOSTADDRESS

The key to the host running the server. Null defers to local host.

See Also:

Constant Field Values

KEY_SERVERPORT

public static final String KEY_SERVERPORT

The key for the socket port to listen to.

See Also:

Constant Field Values

KEY_BUFFERSIZE

public static final String KEY_BUFFERSIZE

The key in the properties for the stream buffer size.

See Also:

Constant Field Values

KEY_SERVERPRIORITY

public static final String KEY_SERVERPRIORITY

The key in the properties defining the priority of the server.

See Also:

Constant Field Values

KEY_HANDLERPRIORITY

public static final String KEY_HANDLERPRIORITY

The key in the properties defining the priority of the server.

See Also:

Constant Field Values

KEY_LOGOUT

public static final String KEY_LOGOUT

The key for the log-out time granted to the clients.

See Also:

Constant Field Values

DEFRECEIVERNAME

private static final String DEFRECEIVERNAME

The default receiver (Receiver-).

See Also:

Constant Field Values

DEFSERVERPORT

public static final int DEFSERVERPORT

The default port number (1026).

See Also:

Constant Field Values

DEFBUFFERSIZE

private static final int DEFBUFFERSIZE

The default buffer size of the I/O streams (2048).

See Also:

Constant Field Values

DEFSERVERPRIORITY

private static final int DEFSERVERPRIORITY

The default server thread priority (1).

See Also:

Constant Field Values

DEFHANDLERPRIORITY

private static final int DEFHANDLERPRIORITY

The default handler thread priority (Thread.NORM_PRIORITY).

See Also:

Constant Field Values

DEFLOGOUT

private static final long DEFLOGOUT

The default log-out time granted to clients.

See Also:

Constant Field Values

thisThread

private Thread thisThread

A reference to the thread constructed from this Runnable.

listen

private ServerSocket listen

The server socket the server listens to.

cancel

private boolean cancel

Gets true if this thread should exit.

handlerGroup

protected final ThreadGroup handlerGroup

The thread group handlers run in.

COUNT

private static int COUNT

An internal counter for automatic naming.

Constructor Detail

ReceiverServer

protected ReceiverServer(Map qualify)

Constructs a new receiver with the specified properties. Use of this constructor ensures that following properties are defined (values in paranthesis are default values).

• The receiver server listening port (1026).
• The I/O-streams buffer size (2048).
• The run-priority of the server (1).
• The run-priority of the handler spawned when a connection is made (Thread.NORM_PRIORITY).
• A name for the server (Receiver-<#>).

Please be aware that relying on the auto-naming capabilities will almost always introduce naming confusions and should be avoided whenever possible.

Method Detail

nextCount

private static int nextCount()

Gets the next available number at automatic naming.

init

public void init()

Initializes the receiver server. If timing is important, you can the escape pod with initReceiverServer().

Specified by:

init in interface Initializable

Overrides:

init in class PropertyResources

initReceiverServer

protected void initReceiverServer()

An escape pod for subclasses. The init method sets the priority of the this thread. It must be called between construction and starting. This method does exactly the desired thing, it is called immediately after the construction of the receiver server.

getReceiverName

public String getReceiverName()

Returns the name used for binding this receiver. The naming extensions from the caster abilities are stripped from the name.
Note that each registered receiver must have a unique URL otherwise registering will replace the previous binding.

getServerPort

public int getServerPort()

Returns the port number the clients should connect to on this receiver.

getBufferSize

public int getBufferSize()

Returns the buffer size used for buffering the socket streams.

getServerPriority

public int getServerPriority()

Returns the priority at which this thread (the server) should run.

getHandlerPriority

public int getHandlerPriority()

Returns the priority at which the connection handler thread should run.

processError

public void processError(ErrorEvent ee)

An escape pod for subclasses that want to do anything special with errors or exceptions thrown during the lifecycle of this thread. Note this is not a generic error or excaption handler. Its intention is to notify somebody of an error/exception message. The error/exception handling has to be done (prior) to this method call.

The default implementation is empty.

Specified by:

processError in interface ErrorProcessing

Parameters:

thrown - The exception/error to be reported.

run

public void run()

The run method of the receiver server. Unless cancel is called, it loops forever accepting connections. If a client connects to the listening port the server calls the abstract method protocol(java.net.Socket) that should in turn launch a dedicated helper thread and should return immediately.

Specified by:

run in interface Runnable

exit

public void exit()

Closes the receiver socket.

Specified by:

exit in interface ExitCleaning

Overrides:

exit in class CastingContainer

protocol

protected abstract void protocol(Socket client)

The method called as soon as a connection is established. Concrete subclasses should provide their own protocol here.

Parameters:

client - The client socket.

See Also:

CommandReceiver, ErrorReceiver

cancel

public void cancel()

Cancels the server thread. It does so by calling the server sockets close method. This will provoke an I/O Exception to occur in the run() loop. This I/O Exception is catched and the cancel flag is querried within the catch. If it is true this thread exits gracefully.
Note that this method blocks until the server thread is dead.

Specified by:

cancel in interface CancelRunnable

getAsociatedThread

public Thread getAsociatedThread()

Returns the thread asociated with this server. Also used by daugther classes to determine the thread the server is running in

Specified by:

getAsociatedThread in interface CancelRunnable

maxTimeToCancel

public long maxTimeToCancel()

Returns the maximum time-out for this thread. This is twice the log-out time.

Specified by:

maxTimeToCancel in interface CancelRunnable