gumbo.net
Class NetThread

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--gumbo.net.NetThread
All Implemented Interfaces:
java.lang.Runnable
Direct Known Subclasses:
MessageThread

public abstract class NetThread
extends java.lang.Thread

Abstract base class for network application threads (for clients, servers, and the client and server sides of proxy servers). Networking is via a socket with two-way asynchronous communication. Network resources (sockets, readers, writers) are dynamic, meaning that they are set and updated at run time. As such, clients should not hold references to them; instead, the client should reference the thread and get the a resource each time it is needed.

Except for dialogs, contains no GUI or Gumbo message dependencies. All status reporting is via event listeners.

Version:
$Revision: 1.9 $
Author:
Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Field Summary
static java.lang.String DEFAULT_PROXY_HOST
           
static int DEFAULT_PROXY_PORT
           
static java.lang.String DEFAULT_SERVER_HOST
           
static int DEFAULT_SERVER_PORT
           
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
NetThread(java.lang.String appName)
           
 
Method Summary
 void addNetThreadListener(NetThreadListener listener)
          Adds a net thread event listener.
protected  boolean autoRetryDelay()
          Called by subclasses to implement auto retry delay.
protected  void closeClientSocket()
          Closes this thread's dynamic client socket.
protected  void closeServerSocket()
          Closes this thread's dynamic server socket, after first closing any client socket.
static java.lang.String connectionReport(java.lang.String local, java.lang.String remote, java.net.Socket sock)
          Utility for generating a connection report of the form " to ".
protected  void fireSocketConnect(java.lang.String msg)
           
protected  void fireSocketDisconnect(java.lang.String msg)
           
protected  void fireSocketFailure(java.lang.String msg)
           
protected  void fireThreadDone(java.lang.String msg)
           
protected  void fireThreadReady(java.lang.String msg)
           
 java.lang.String getAppName()
          Gets the thread's application name (for status messages).
 long getAutoRetryDelay()
          Gets the automatic retry delay, as set by setAutoRetry().
 java.net.Socket getClientSocket()
          Gets this thread's dynamic client socket, which is set and updated at run time.
 java.awt.Component getDialogParent()
          Returns the parent GUI component for dialogs.
 java.net.ServerSocket getServerSocket()
          Gets this thread's dynamic server socket, which is set and updated at run time.
protected abstract  void implPleaseStop()
          Called by pleaseStop() after setting the stop flag true.
abstract  boolean isServerThread()
          Returns true if this thread is a server.
 boolean isStopping()
          Returns true if pleaseStop() has been called.
 void pleaseStop()
          Gracefully stops this thread from running by setting a stop flag (see isStopping()).
 void removeNetThreadListener(NetThreadListener listener)
          Removes a net thread event listener.
protected  void requestManualRetry()
          Called by subclasses to force a manual retry next time autoRetryDelay() is called regardless of the auto delay setting.
 void setAutoRetryDelay(long delay)
          Sets (and enables) automatic retry of the server socket or client connection after a specified delay.
protected  void setClientSocket(java.net.Socket clientSocket)
          Sets this thread's dynamic client socket after closing any old one.
 void setDialogParent(java.awt.Component parent)
          Sets the parent GUI component for dialogs.
protected  void setServerSocket(java.net.ServerSocket serverSocket)
          Sets this thread's dynamic server socket after closing any old one.
protected  java.lang.String showRetryConnection(java.awt.Component parent, java.lang.String msg, java.lang.String hostport)
          Called by subclasses to show a dialog warning the user that the server connection failed, and asking if the connection should be retried.
protected  int showRetryServer(java.awt.Component parent, java.lang.String msg, int port)
          Called by subclasses to show a dialog warning the user that the server failed, and asking if the server should be retried.
static java.io.Reader socketReader(java.net.Socket socket)
          Wraps a buffered reader around a socket.
static java.io.Writer socketWriter(java.net.Socket socket)
          Wraps a buffered writer around a socket.
static java.lang.String toHost(java.lang.String hostport)
          Utility for getting the host from a hostport string.
static java.lang.String toHostport(java.lang.String hostport)
          Utility for translating a hostport string into the readable form "(none)" if it is null or empty.
static java.lang.String toHostport(java.lang.String host, int port)
          Utility for converting a host name and port number into a hostport string.
static java.lang.String toHostport(java.lang.String host, java.lang.String portString)
          Utility for converting a host name and port number into a hostport string.
static java.lang.String toLocalHostport(java.net.Socket sock)
          Utility for obtaining the local hostport from a socket.
static int toPort(java.lang.String hostport)
          Utility for getting the port from a hostport string.
static java.lang.String toRemoteHostport(java.net.Socket sock)
          Utility for obtaining the remote hostport from a socket.
static java.lang.String toServerHostport(java.net.ServerSocket sock)
          Utility for obtaining the server hostport from a server socket.
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, run, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_SERVER_HOST

public static final java.lang.String DEFAULT_SERVER_HOST
See Also:
Constant Field Values

DEFAULT_SERVER_PORT

public static final int DEFAULT_SERVER_PORT
See Also:
Constant Field Values

DEFAULT_PROXY_HOST

public static final java.lang.String DEFAULT_PROXY_HOST
See Also:
Constant Field Values

DEFAULT_PROXY_PORT

public static final int DEFAULT_PROXY_PORT
See Also:
Constant Field Values
Constructor Detail

NetThread

public NetThread(java.lang.String appName)
Parameters:
appName - Name of the app associated with this thread (for status messages). If null, a default is used.
Method Detail

setDialogParent

public void setDialogParent(java.awt.Component parent)
Sets the parent GUI component for dialogs. Null if none.


getDialogParent

public java.awt.Component getDialogParent()
Returns the parent GUI component for dialogs. Null if none.


setAutoRetryDelay

public final void setAutoRetryDelay(long delay)
Sets (and enables) automatic retry of the server socket or client connection after a specified delay. The default is manual retry, with the user being prompted for a retry.

Parameters:
delay - The time delay between automatic retries, in milliseconds. If negative, automatic retry is disabled and manual retry is enabled.

getAutoRetryDelay

public final long getAutoRetryDelay()
Gets the automatic retry delay, as set by setAutoRetry().

Returns:
The delay, in milliseconds. Returns -1 if automatic retry is disabled (and manual retry is enabled).

autoRetryDelay

protected boolean autoRetryDelay()
Called by subclasses to implement auto retry delay. If auto retry is disabled or requestManualRetry() has been called since this method was last called, returns false; otherwise, sleeps for the delay time and returns true.

Returns:
True if an auto retry should be performed, false if a manual retry should be performed.

requestManualRetry

protected void requestManualRetry()
Called by subclasses to force a manual retry next time autoRetryDelay() is called regardless of the auto delay setting.


getAppName

public java.lang.String getAppName()
Gets the thread's application name (for status messages). Never null.


isServerThread

public abstract boolean isServerThread()
Returns true if this thread is a server.


setServerSocket

protected final void setServerSocket(java.net.ServerSocket serverSocket)
Sets this thread's dynamic server socket after closing any old one. Null if none.


getServerSocket

public final java.net.ServerSocket getServerSocket()
Gets this thread's dynamic server socket, which is set and updated at run time.

Returns:
The socket. Null if not a server thread or uninitialized.

closeServerSocket

protected final void closeServerSocket()
Closes this thread's dynamic server socket, after first closing any client socket. If null or closed does nothing.


setClientSocket

protected final void setClientSocket(java.net.Socket clientSocket)
Sets this thread's dynamic client socket after closing any old one. Null if none.


getClientSocket

public final java.net.Socket getClientSocket()
Gets this thread's dynamic client socket, which is set and updated at run time.

Returns:
The socket. Null if undefined or uninitialized.

closeClientSocket

protected final void closeClientSocket()
Closes this thread's dynamic client socket. If null or closed does nothing.


pleaseStop

public final void pleaseStop()
Gracefully stops this thread from running by setting a stop flag (see isStopping()).


implPleaseStop

protected abstract void implPleaseStop()
Called by pleaseStop() after setting the stop flag true. Since the thread may be blocking on a read, subclasses should use this opportunity to close any open readers.


isStopping

public final boolean isStopping()
Returns true if pleaseStop() has been called. Used by thread implementors to determine when they should stop this thread.


addNetThreadListener

public final void addNetThreadListener(NetThreadListener listener)
Adds a net thread event listener.


removeNetThreadListener

public final void removeNetThreadListener(NetThreadListener listener)
Removes a net thread event listener.


fireSocketConnect

protected final void fireSocketConnect(java.lang.String msg)

fireSocketDisconnect

protected final void fireSocketDisconnect(java.lang.String msg)

fireSocketFailure

protected final void fireSocketFailure(java.lang.String msg)

fireThreadReady

protected final void fireThreadReady(java.lang.String msg)

fireThreadDone

protected final void fireThreadDone(java.lang.String msg)

showRetryConnection

protected java.lang.String showRetryConnection(java.awt.Component parent,
                                               java.lang.String msg,
                                               java.lang.String hostport)
Called by subclasses to show a dialog warning the user that the server connection failed, and asking if the connection should be retried. If retry, the user will be prompted to enter the hostport. The application exits if the user chooses to quit.

Parameters:
parent - Dialog parent component. Null if none.
msg - Explanatory message. If null, default message used.
hostport - Old "host:port". Ignored if null.
Returns:
Possibly new "host:port". Never null but possibly ill-formed.

showRetryServer

protected int showRetryServer(java.awt.Component parent,
                              java.lang.String msg,
                              int port)
Called by subclasses to show a dialog warning the user that the server failed, and asking if the server should be retried. If retry, the user will be prompted to enter the port. The application exits if if the user chooses to quit.

Parameters:
parent - Dialog parent component. Null if none.
msg - Explanatory message. If null, default message used.
port - Old server port number.
Returns:
Possibly new port number.

toHostport

public static java.lang.String toHostport(java.lang.String host,
                                          int port)
Utility for converting a host name and port number into a hostport string. Any whitespace will be trimmed from the host name.

Parameters:
host - Host name. Empty if null.
port - Port number. Empty if negative.
Returns:
New String of the form "[host][:port]". Possibly empty but never null.

toHostport

public static java.lang.String toHostport(java.lang.String host,
                                          java.lang.String portString)
Utility for converting a host name and port number into a hostport string. Any whitespace will be trimmed from the host name and port.

Parameters:
host - Host name. Empty if null.
portString - Port number. Empty if null, empty, ill-formed, or negative.
Returns:
New String of the form "[host][:port]". Possibly empty but never null.

toHostport

public static java.lang.String toHostport(java.lang.String hostport)
Utility for translating a hostport string into the readable form "(none)" if it is null or empty.

Parameters:
hostport - Hostport string of the form "[host][:port]". Empty if null.
Returns:
New String with the original hostport or "(none)" if it was empty. Never null.

toServerHostport

public static java.lang.String toServerHostport(java.net.ServerSocket sock)
Utility for obtaining the server hostport from a server socket.

Returns:
New String of the form "host:port". Empty if socket is null.

toLocalHostport

public static java.lang.String toLocalHostport(java.net.Socket sock)
Utility for obtaining the local hostport from a socket.

Returns:
New String of the form "host:port". Empty if socket is null.

toRemoteHostport

public static java.lang.String toRemoteHostport(java.net.Socket sock)
Utility for obtaining the remote hostport from a socket.

Returns:
New String of the form "host:port". Empty if socket is null.

toHost

public static java.lang.String toHost(java.lang.String hostport)
Utility for getting the host from a hostport string. Any whitespace will be trimmed from the hostport.

Parameters:
hostport - Hostport string of the form "[host][:port]". Empty if null.
Returns:
New String with the host name. Empty if hostport is ill-formed.

toPort

public static int toPort(java.lang.String hostport)
Utility for getting the port from a hostport string. Any whitespace will be trimmed from the hostport.

Parameters:
hostport - Hostport string of the form "[host][:port]". Empty if null.
Returns:
Port number. -1 if hostport is ill-formed or there is no port.

connectionReport

public static java.lang.String connectionReport(java.lang.String local,
                                                java.lang.String remote,
                                                java.net.Socket sock)
Utility for generating a connection report of the form " to ".

Parameters:
local - Local name (e.g. "client"). If null, defaults to "local".
remote - Remote name (e.g. "server"). If null, defaults to "remote".
Returns:
New String with the report.

socketReader

public static java.io.Reader socketReader(java.net.Socket socket)
                                   throws java.io.IOException
Wraps a buffered reader around a socket.

Parameters:
socket - Open socket. Never null.
Returns:
Socket reader. never null.
java.io.IOException

socketWriter

public static java.io.Writer socketWriter(java.net.Socket socket)
                                   throws java.io.IOException
Wraps a buffered writer around a socket.

Parameters:
socket - Open socket. Never null.
Returns:
Socket writer. Never null.
java.io.IOException