ocsf.server
Class AbstractServer

java.lang.Object
  |
  +--ocsf.server.AbstractServer

All Implemented Interfaces:

java.lang.Runnable

public abstract class AbstractServer

extends java.lang.Object

implements java.lang.Runnable

The AbstractServer class maintains a thread that waits for connection attempts from clients. When a connection attempt occurs it creates a new ConnectionToClient instance which runs as a thread. When a client is thus connected to the server, the two programs can then exchange Object instances.

Method handleMessageFromClient must be defined by a concrete subclass. Several other hook methods may also be overriden.

Several public service methods are provided to applications that use this framework, and several hook methods are also available

Project Name: OCSF (Object Client-Server Framework)

See Also:

ConnectionToClient

Constructor Summary

AbstractServer(int port)
Constructs a new server.

Method Summary

protected void	clientConnected(ocsf.server.ConnectionToClient client) Hook method called each time a new client connection is accepted.
protected void	clientDisconnected(ocsf.server.ConnectionToClient client) Hook method called each time a client disconnects.
protected void	clientException(ocsf.server.ConnectionToClient client, java.lang.Throwable exception) Hook method called each time an exception is thrown in a ConnectionToClient thread.
void	close() Closes the server socket and the connections with all clients.
java.lang.Thread[]	getClientConnections() Returns an array containing the existing client connections.
int	getNumberOfClients() Counts the number of clients currently connected.
int	getPort() Returns the port number.
protected abstract void	handleMessageFromClient(java.lang.Object msg, ocsf.server.ConnectionToClient client) Handles a command sent from one client to the server.
boolean	isListening() Returns true if the server is ready to accept new clients.
void	listen() Begins the thread that waits for new clients.
protected void	listeningException(java.lang.Throwable exception) Hook method called when the server stops accepting connections because an exception has been raised.
void	run() Runs the listening thread that allows clients to connect.
void	sendToAllClients(java.lang.Object msg) Sends a message to every client connected to the server.
protected void	serverClosed() Hook method called when the server is clased.
protected void	serverStarted() Hook method called when the server starts listening for connections.
protected void	serverStopped() Hook method called when the server stops accepting connections.
void	setBacklog(int backlog) Sets the maximum number of waiting connections accepted by the operating system.
void	setPort(int port) Sets the port number for the next connection.
void	setTimeout(int timeout) Sets the timeout time when accepting connections.
void	stopListening() Causes the server to stop accepting new connections.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractServer

public AbstractServer(int port)

Constructs a new server.

Parameters:

port - the port number on which to listen.

Method Detail

listen

public final void listen()
                  throws java.io.IOException

Begins the thread that waits for new clients. If the server is already in listening mode, this call has no effect.

Throws:

java.io.IOException - if an I/O error occurs when creating the server socket.

stopListening

public final void stopListening()

Causes the server to stop accepting new connections.

close

public final void close()
                 throws java.io.IOException

Closes the server socket and the connections with all clients. Any exception thrown while closing a client is ignored. If one wishes to catch these exceptions, then clients should be individually closed before calling this method. The method also stops listening if this thread is running. If the server is already closed, this call has no effect.

Throws:

java.io.IOException - if an I/O error occurs while closing the server socket.

sendToAllClients

public void sendToAllClients(java.lang.Object msg)

Sends a message to every client connected to the server. This is merely a utility; a subclass may want to do some checks before actually sending messages to all clients. This method can be overriden, but if so it should still perform the general function of sending to all clients, perhaps after some kind of filtering is done. Any exception thrown while sending the message to a particular client is ignored.

Parameters:

msg - Object The message to be sent

isListening

public final boolean isListening()

Returns true if the server is ready to accept new clients.

Returns:

true if the server is listening.

getClientConnections

public final java.lang.Thread[] getClientConnections()

Returns an array containing the existing client connections. This can be used by concrete subclasses to implement messages that do something with each connection (e.g. kill it, send a message to it etc.). Remember that after this array is obtained, some clients in this migth disconnect. New clients can also connect, these later will not appear in the array.

Returns:

an array of Thread containing ConnectionToClient instances.

getNumberOfClients

public final int getNumberOfClients()

Counts the number of clients currently connected.

Returns:

the number of clients currently connected.

getPort

public final int getPort()

Returns the port number.

Returns:

the port number.

setPort

public final void setPort(int port)

Sets the port number for the next connection. The server must be closed and restarted for the port change to be in effect.

Parameters:

port - the port number.

setTimeout

public final void setTimeout(int timeout)

Sets the timeout time when accepting connections. The default is half a second. This means that stopping the server may take up to timeout duration to actually stop. The server must be stopped and restarted for the timeout change to be effective.

Parameters:

timeout - the timeout time in ms.

setBacklog

public final void setBacklog(int backlog)

Sets the maximum number of waiting connections accepted by the operating system. The default is 20. The server must be closed and restarted for the backlog change to be in effect.

Parameters:

backlog - the maximum number of connections.

run

public final void run()

Runs the listening thread that allows clients to connect. Not to be called.

Specified by:

run in interface java.lang.Runnable

clientConnected

protected void clientConnected(ocsf.server.ConnectionToClient client)

Hook method called each time a new client connection is accepted. The default implementation does nothing.

Parameters:

client - the connection connected to the client.

clientDisconnected

protected void clientDisconnected(ocsf.server.ConnectionToClient client)

Hook method called each time a client disconnects. The default implementation does nothing. The method may be overridden by subclasses but should remains synchronized.

Parameters:

client - the connection with the client.

clientException

protected void clientException(ocsf.server.ConnectionToClient client,
                               java.lang.Throwable exception)

Hook method called each time an exception is thrown in a ConnectionToClient thread. The method may be overridden by subclasses but should remains synchronized.

Parameters:

client - the client that raised the exception.

listeningException

protected void listeningException(java.lang.Throwable exception)

Hook method called when the server stops accepting connections because an exception has been raised. The default implementation does nothing. This method may be overriden by subclasses.

Parameters:

exception - the exception raised.

serverStarted

protected void serverStarted()

Hook method called when the server starts listening for connections. The default implementation does nothing. The method may be overridden by subclasses.

serverStopped

protected void serverStopped()

Hook method called when the server stops accepting connections. The default implementation does nothing. This method may be overriden by subclasses.

serverClosed

protected void serverClosed()

Hook method called when the server is clased. The default implementation does nothing. This method may be overriden by subclasses. When the server is closed while still listening, serverStopped() will also be called.

handleMessageFromClient

protected abstract void handleMessageFromClient(java.lang.Object msg,
                                                ocsf.server.ConnectionToClient client)

Handles a command sent from one client to the server. This MUST be implemented by subclasses, who should respond to messages. This method is called by a synchronized method so it is also implcitly synchronized.

Parameters:

msg - the message sent.

client - the connection connected to the client that sent the message.