soc.server.genericServer
Class StringConnection

java.lang.Object
  soc.server.genericServer.StringConnection

Direct Known Subclasses:

Connection, LocalStringConnection

public abstract class StringConnection
extends java.lang.Object

StringConnection allows clients and servers to communicate, with no difference between local and actual networked traffic.

  1.0.0 - 2007-11-18 - initial release
  1.0.1 - 2008-06-28 - add getConnectTime
  1.0.2 - 2008-07-30 - no change in this file
  1.0.3 - 2008-08-08 - add disconnectSoft, getVersion, setVersion
  1.0.4 - 2008-09-04 - add appData
  1.0.5 - 2009-05-31 - add isVersionKnown, setVersion(int,bool),
                       setVersionTracking, isInputAvailable,
                       wantsHideTimeoutMessage, setHideTimeoutMessage
  1.0.5.1- 2009-10-26- javadoc warnings fixed; remove unused import EOFException
  1.2.0 - 2013-09-07 - for I18N, add setI18NStringManager(SOCStringManager, String) and
                       getLocalized(String). StringConnection is now a superclass, not an interface.

Version:

1.2.0

Author:

Jeremy D Monin

Field Summary

protected java.lang.Object	appData The arbitrary app-specific data associated with this connection, or null.
protected java.util.Date	connectTime Time of connection to server, or of object creation if that time's not available
protected java.lang.Object	data The arbitrary key data (client "name") associated with this connection, or null.
protected java.lang.Exception	error Any error encountered, or null
protected boolean	hideTimeoutMessage
protected java.lang.String	localeStr The server-side locale for this client connection, for app-specific message formatting, or null.
protected Server	ourServer Is set if server-side.
protected int	remoteVersion
protected boolean	remoteVersionKnown
protected boolean	remoteVersionTrack
protected SOCStringManager	stringMgr The server-side string manager for app-specific client message formatting, or null.

Constructor Summary

StringConnection()

Method Summary

abstract boolean	connect() Start ability to read from the net; called only by the server.
abstract void	disconnect() Close the socket, set EOF; called after conn is removed from server structures
abstract void	disconnectSoft() Accept no further input, allow output to drain, don't immediately close the socket.
java.lang.Object	getAppData() The optional app-specific changeable data for this connection.
java.util.Date	getConnectTime()
java.lang.Object	getData() The optional key data used to name this connection.
java.lang.Exception	getError()
java.lang.String	getI18NLocale() Get the locale for this connection, as reported to setI18NStringManager(SOCStringManager, String).
java.lang.String	getLocalized(java.lang.String key) Get a localized string (having no parameters) with the given key.
java.lang.String	getLocalized(java.lang.String key, java.lang.Object... arguments) Get and format a localized string (with parameters) with the given key.
java.lang.String	getLocalizedSpecial(SOCGame game, java.lang.String key, java.lang.Object... arguments) Get and format a localized string (with special SoC-specific parameters) with the given key.
int	getVersion() Give the version number (if known) of the remote end of this connection.
abstract java.lang.String	host()
abstract boolean	isConnected() Are we currently connected and active?
abstract boolean	isInputAvailable() Is input available now, without blocking? Same idea as FilterInputStream.available().
boolean	isVersionKnown() Is the version known of the remote end of this connection? We may have just assumed it, or taken a default.
abstract void	put(java.lang.String str) Send data over the connection.
abstract void	run() For server-side thread which reads and treats incoming messages
void	setAppData(java.lang.Object data) Set the app-specific non-key data for this connection.
void	setData(java.lang.Object data) Set the optional key data for this connection.
void	setHideTimeoutMessage(boolean wantsHide) If client connection times out at server, should the server not print a message to console? This would be desired, for instance, in automated clients, which would reconnect if they become disconnected.
void	setI18NStringManager(SOCStringManager mgr, java.lang.String loc) Set the I18N string manager and locale name for this connection, for server convenience.
void	setVersion(int version) Set the version number of the remote end of this connection.
void	setVersion(int version, boolean isKnown) Set the version number of the remote end of this connection.
void	setVersionTracking(boolean doTracking) For server-side use, should we notify the server when our version is changed by setVersion calls?
boolean	wantsHideTimeoutMessage() If client connection times out at server, should the server not print a message to console? This would be desired, for instance, in automated clients, which would reconnect if they become disconnected.

Methods inherited from class java.lang.Object

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

Field Detail

data

protected java.lang.Object data

The arbitrary key data (client "name") associated with this connection, or null.

appData

protected java.lang.Object appData

The arbitrary app-specific data associated with this connection, or null. Not used or referenced by generic server.

localeStr

protected java.lang.String localeStr

The server-side locale for this client connection, for app-specific message formatting, or null. Not used or referenced by the generic server layer.

App-specific connection data (getAppData()) can hold a full Locale object; see SOCClientData for an example.

Since:

1.2.0

stringMgr

protected SOCStringManager stringMgr

The server-side string manager for app-specific client message formatting, or null. Not used or referenced by the generic server layer.

Since:

1.2.0

remoteVersion

protected int remoteVersion

remoteVersionKnown

protected boolean remoteVersionKnown

remoteVersionTrack

protected boolean remoteVersionTrack

hideTimeoutMessage

protected boolean hideTimeoutMessage

ourServer

protected Server ourServer

Is set if server-side. Notifies at EOF (calls removeConnection).

error

protected java.lang.Exception error

Any error encountered, or null

connectTime

protected java.util.Date connectTime

Time of connection to server, or of object creation if that time's not available

Constructor Detail

StringConnection

public StringConnection()

Method Detail

host

public abstract java.lang.String host()

Returns:

Hostname of the remote end of the connection

put

public abstract void put(java.lang.String str)
                  throws java.lang.IllegalStateException

Send data over the connection.

Parameters:

str - Data to send

Throws:

java.lang.IllegalStateException - if not yet accepted by server

run

public abstract void run()

For server-side thread which reads and treats incoming messages

isConnected

public abstract boolean isConnected()

Are we currently connected and active?

connect

public abstract boolean connect()

Start ability to read from the net; called only by the server. (In a network-based subclass, another thread may be started by this method.)

Returns:

true if able to connect, false if an error occurred.

disconnect

public abstract void disconnect()

Close the socket, set EOF; called after conn is removed from server structures

disconnectSoft

public abstract void disconnectSoft()

Accept no further input, allow output to drain, don't immediately close the socket. Once called, isConnected() will return false, even if output is still being sent to the other side.

getData

public java.lang.Object getData()

The optional key data used to name this connection.

Returns:

The key data for this connection, or null.

See Also:

getAppData()

getAppData

public java.lang.Object getAppData()

The optional app-specific changeable data for this connection. Not used anywhere in the generic server, only in your app.

Returns:

The app-specific data for this connection.

See Also:

getData()

setData

public void setData(java.lang.Object data)

Set the optional key data for this connection.

This is anything your application wants to associate with the connection. The StringConnection system uses this data to name the connection, so it should not change once set.

If you call setData after Server.newConnection1(StringConnection), please call Server.nameConnection(StringConnection) afterwards to ensure the name is tracked properly at the server.

Parameters:

data - The new key data, or null

See Also:

setAppData(Object)

setAppData

public void setAppData(java.lang.Object data)

Set the app-specific non-key data for this connection.

This is anything your application wants to associate with the connection. The StringConnection system itself does not reference or use this data. You can change it as often as you'd like, or not use it.

Parameters:

data - The new data, or null

See Also:

setData(Object)

getI18NLocale

public java.lang.String getI18NLocale()

Get the locale for this connection, as reported to setI18NStringManager(SOCStringManager, String).

Returns:

the locale passed to setI18NStringManager, which may be null

Since:

1.2.0

setI18NStringManager

public void setI18NStringManager(SOCStringManager mgr,
                                 java.lang.String loc)

Set the I18N string manager and locale name for this connection, for server convenience. Used for getLocalized(String).

Parameters:

mgr - String manager, or null

loc - Locale name, used only for getI18NLocale()

Since:

1.2.0

getLocalized

public java.lang.String getLocalized(java.lang.String key)
                              throws java.util.MissingResourceException

Get a localized string (having no parameters) with the given key. Used for convenience at servers whose clients may have different locales.

Parameters:

key - Key to use for string retrieval

Returns:

the localized string from the manager's bundle or one of its parents

Throws:

java.util.MissingResourceException - if no string can be found for key; this is a RuntimeException

Since:

1.2.0

See Also:

getLocalized(String, Object...), getLocalizedSpecial(SOCGame, String, Object...)

getLocalized

public java.lang.String getLocalized(java.lang.String key,
                                     java.lang.Object... arguments)
                              throws java.util.MissingResourceException

Get and format a localized string (with parameters) with the given key. Used for convenience at servers whose clients may have different locales.

Parameters:

key - Key to use for string retrieval

arguments - Objects to use with {0}, {1}, etc in the localized string by calling MessageFormat.format(String, Object...).

Returns:

the localized formatted string from the manager's bundle or one of its parents

Throws:

java.util.MissingResourceException - if no string can be found for key; this is a RuntimeException

Since:

1.2.0

See Also:

getLocalized(String), getLocalizedSpecial(SOCGame, String, Object...)

getLocalizedSpecial

public java.lang.String getLocalizedSpecial(SOCGame game,
                                            java.lang.String key,
                                            java.lang.Object... arguments)
                                     throws java.util.MissingResourceException,
                                            java.lang.IllegalArgumentException

Get and format a localized string (with special SoC-specific parameters) with the given key. Used for convenience at servers whose clients may have different locales. See SOCStringManager.getSpecial(SOCGame, String, Object...) for details. Uses locale/strings from our client connection's SOCStringManager if set, SOCStringManager.getFallbackServerManagerForClient() otherwise.

Parameters:

game - Game object to pass through to SOCStringManager.getSpecial(...)

key - Key to use for string retrieval

arguments - Objects to use with {0}, {1,rsrcs}, etc in the localized string

Returns:

the localized formatted string from the manager's bundle or one of its parents

Throws:

java.util.MissingResourceException - if no string can be found for key; this is a RuntimeException

java.lang.IllegalArgumentException - if the localized pattern string has a parse error (closing '}' brace without opening '{' brace, etc)

Since:

1.2.0

See Also:

getLocalized(String), getLocalized(String, Object...)

getError

public java.lang.Exception getError()

Returns:

Any error encountered, or null

getConnectTime

public java.util.Date getConnectTime()

Returns:

Time of connection to server, or of object creation if that time's not available

See Also:

connect()

getVersion

public int getVersion()

Give the version number (if known) of the remote end of this connection. The meaning of this number is application-defined.

Returns:

Version number, or 0 if unknown.

setVersion

public void setVersion(int version)

Set the version number of the remote end of this connection. The meaning of this number is application-defined.

Locking: If we're on server side, and setVersionTracking(boolean) is true, caller should synchronize on Server.unnamedConns.

Parameters:

version - Version number, or 0 if unknown. If version is greater than 0, future calls to isVersionKnown() should return true.

setVersion

public void setVersion(int version,
                       boolean isKnown)

Set the version number of the remote end of this connection. The meaning of this number is application-defined.

Locking: If we're on server side, and setVersionTracking(boolean) is true, caller should synchronize on Server.unnamedConns.

Parameters:

version - Version number, or 0 if unknown.

isKnown - Should this version be considered confirmed/known by isVersionKnown()?

Since:

1.0.5

isVersionKnown

public boolean isVersionKnown()

Is the version known of the remote end of this connection? We may have just assumed it, or taken a default. To confirm the version and set this flag, call setVersion(int, boolean).

Returns:

True if we've confirmed the version, false if it's assumed or default.

Since:

1.0.5

setVersionTracking

public void setVersionTracking(boolean doTracking)

For server-side use, should we notify the server when our version is changed by setVersion calls?

Parameters:

doTracking - true if we should notify server, false otherwise. If true, please call both setVersion and Server.clientVersionAdd(int) before calling setVersionTracking. If false, please call Server.clientVersionRem(int) before calling setVersionTracking.

Since:

1.0.5

isInputAvailable

public abstract boolean isInputAvailable()

Is input available now, without blocking? Same idea as FilterInputStream.available().

Since:

1.0.5

wantsHideTimeoutMessage

public boolean wantsHideTimeoutMessage()

If client connection times out at server, should the server not print a message to console? This would be desired, for instance, in automated clients, which would reconnect if they become disconnected.

Since:

1.0.5

See Also:

setHideTimeoutMessage(boolean)

setHideTimeoutMessage

public void setHideTimeoutMessage(boolean wantsHide)

If client connection times out at server, should the server not print a message to console? This would be desired, for instance, in automated clients, which would reconnect if they become disconnected.

Parameters:

wantsHide - true to hide, false to print, the log message on idle-disconnect

Since:

1.0.5

See Also:

wantsHideTimeoutMessage()