org.hsqldb
Class Server

java.lang.Object
  org.hsqldb.Server

All Implemented Interfaces:

HsqlSocketRequestHandler

Direct Known Subclasses:

WebServer

public class Server

extends Object

implements HsqlSocketRequestHandler

The HSQLDB HSQL protocol network database server.

A Server object acts as a network database server and is one way of using the client-server mode of HSQLDB Database Engine. Instances of this class handle native HSQL protocol connections exclusively, allowing database queries to be performed efficienly across the network. Server's direct descendent, WebServer, handles HTTP protocol connections exclusively, allowing HSQL protocol to be tunneled over HTTP to avoid sandbox and firewall issues, albeit less efficiently.

There are a number of ways to configure and start a Server instance.

When started from the command line or programatically via the main(String[]) method, configuration occurs in three phases, with later phases overriding properties set by previous phases:

1. Upon construction, a Server object is assigned a set of default properties.

2. If it exists, properties are loaded from a file named 'server.properties' in the present working directory.

3. The command line arguments (alternatively, the String[] passed to main()) are parsed and used to further configure the Server's properties.

From the command line, the options are as follows:

 +----------------+-------------+----------+------------------------------+
 |    OPTION      |    TYPE     | DEFAULT  |         DESCRIPTION          |
 +----------------+-------------+----------+------------------------------|
 | -?             | --          | --       | prints this message          |
 | -address       | name|number | any      | server inet address          |
 | -port          | number      | 9001/544 | port at which server listens |
 | -database.i    | [type]spec  | 0=test   | path of database i           |
 | -dbname.i      | alias       | --       | url alias for database i     |
 | -silent        | true|false  | true     | false => display all queries |
 | -trace         | true|false  | false    | display JDBC trace messages  |
 | -tls           | true|false  | false    | TLS/SSL (secure) sockets     |
 | -no_system_exit| true|false  | false    | do not issue System.exit()   |
 +----------------+-------------+----------+------------------------------+
 

The database.i and dbname.i options need further explanation:

• Multiple databases can be served by each instance of the Server. The value of i is currently limited to the range 0..9, allowing up to 10 different databases. Any number is this range can be used.

• The value assigned to database.i is interpreted using the format '[type]spec', where the optional type component is one of 'file:', 'res:' or 'mem:' and the spec component is interpreted in the context of the type component.

  If omitted, the type component is taken to be 'file:'.

  A full description of how '[type]spec' values are interpreted appears in the overview for jdbcConnection.

• The value assigned to dbname.i is taken to be the key used to look up the desired database instance and thus corresponds to the <alias> component of the HSQLDB HSQL protocol database connection url: 'jdbc:hsqldb:hsql[s]://host[port][/<alias>]'.

• The value of database.0 is special. If dbname.0 is not specified, then this defaults to an empty string and a connection is made to database.0 path when the <alias> component of an HSQLDB HSQL protocol database connection url is omitted. If a database key/value pair is found in the properties when the main method is called, this pair is supersedes the database.0 setting

  This behaviour allows the previous database connection url format to work with essentially unchanged semantics.

From the 'server.properties' file, options can be set similarly, using a slightly different format.

Here is an example 'server.properties' file:

 server.port=9001
 server.database.0=test
 server.dbname.0=...
 ...
 server.database.n=...
 server.dbname.n=...
 server.silent=true
 

Starting with 1.7.2, Server has been refactored to become a simple JavaBean with non-blocking start() and stop() service methods. It is possible to configure a Server instance through the JavaBean API as well, but this part of the public interface is still under review and will not be finalized or documented fully until the final 1.7.2 release.

Note:

The 'no_system_exit' property is of particular interest.

If a Server instance is to run embedded in, say, an application server, such as when the jdbcDataSource or HsqlServerFactory classes are used, it is typically necessary to avoid calling System.exit() when the Server instance shuts down.

By default, 'no_system_exit' is set:

1. true when a Server is started directly from the start() method.

2. false when a Server is started from the main(String[]) method.

These values are natural to their context because the first case allows the JVM to exit by default on Server shutdown when a Server instance is started from a command line environment, whereas the second case prevents a typically unwanted JVM exit on Server shutdown when a Server intance is started as part of a larger framework.

Version:

1.7.2

Field Summary

protected static int	serverBundleHandle
protected ThreadGroup	serverConnectionThreadGroup
protected String	serverId
protected int	serverProtocol
protected ServerSocket	socket
protected HsqlSocketFactory	socketFactory

Constructor Summary

	Server() Creates a new Server instance handling HSQL protocol connections.
protected	Server(int protocol) Creates a new Server instance handling the specified connection protocol.

Method Summary

protected boolean	allowConnection(Socket socket) Retrieves whether the specified socket should be allowed to make a connection.
void	checkRunning(boolean running) Checks if this Server object is or is not running and throws if the current state does not match the specified value.
protected void	finalize()
String	getAddress() Retrieves, in string form, this server's host address.
String	getDatabaseName(int index) Retrieves the url alias (external name) of the i'th database that this Server hosts.
String	getDatabasePath(int index) Retrieves the HSQLDB path descriptor (uri) of the i'th Database that this Server hosts.
static int	getDefaultPort(boolean isTls) Retrieves the default port that this Server will try to use in the abscence of an explicitly specified one, given the specified value for whether or not to use secure sockets.
String	getDefaultPropertiesPath() Retrieves the path that will be used by default if a null or zero-length path is specified to putPropertiesFromFile().
String	getDefaultWebPage() Retrieves the name of the web page served when no page is specified.
PrintWriter	getErrWriter() Retrieves the PrintWriter to which server errors are printed.
String	getHelpString() Retrieves a String object describing the command line and properties options for this Server.
PrintWriter	getLogWriter() Retrieves the PrintWriter to which server messages are printed.
int	getPort() Retrieves this server's host port.
String	getProductName() Retrieves this server's product name.
String	getProductVersion() Retrieves the server's product version, as a String.
protected static HsqlProperties	getPropertiesFromFile(String path)
String	getProtocol() Retrieves a string respresentaion of the network protocol this server offers, typically one of 'HTTP', HTTPS', 'HSQL' or 'HSQLS'.
Throwable	getServerError() Retrieves a Throwable indicating the last server error, if any.
String	getServerId() Retrieves a String identifying this Server object.
int	getState() Retrieves current state of this server in numerically coded form.
String	getStateDescriptor() Retrieves a character sequence describing this server's current state, including the message of the last exception, if there is one and it is still in context.
String	getWebRoot() Retrieves the root context (directory) from which web content is served.
void	handleConnection(Socket s) Assigns the specified socket to a new conection handler and starts the handler in a new Thread.
protected void	init(int protocol) Initializes this server, setting the accepted connection protocol.
boolean	isNoSystemExit() Retrieves whether this server calls System.exit() when shutdown.
boolean	isRestartOnShutdown() Retrieves whether this server restarts on shutdown.
boolean	isSilent() Retrieves whether silent mode operation was requested in the server properties.
boolean	isTls() Retreives whether the use of secure sockets was requested in the server properties.
boolean	isTrace() Retrieves whether JDBC trace messages are to go to System.out or the DriverManger PrintStream/PrintWriter, if any.
static Vector	listLocalInetAddressNames() Retrieves a list of Strings naming the distinct, known to be valid local InetAddress names for this machine.
static void	main(String[] args) Creates and starts a new Server.
protected void	print(String msg) Prints the specified message, s, formatted to identify that the print operation is against this server instance.
protected void	printError(String msg) Prints an error message to this Server object's errWriter.
protected static void	printHelp(String key) Prints message for the specified key, without any special formatting.
protected void	printStackTrace(Throwable t) Prints the stack trace of the Throwable, t, to this Server object's errWriter.
protected void	printWithThread(String msg) Prints a message formatted similarly to print(String), additionally identifying the current (calling) thread.
boolean	putPropertiesFromFile(String path) Attempts to put properties from the file with the specified path.
void	putPropertiesFromString(String s) Puts properties from the supplied string argument.
void	setAddress(String address) Sets the InetAddress with which this server's ServerSocket will be constructed.
void	setDatabaseName(int index, String name) Sets the external name (url alias) of the i'th hosted database.
void	setDatabasePath(int index, String path) Sets the path of the hosted database.
void	setDefaultWebPage(String file) Sets the name of the web page served when no page is specified.
void	setErrWriter(PrintWriter pw) Sets the PrintWriter to which server errors are logged.
void	setLogWriter(PrintWriter pw) Sets the PrintWriter to which server messages are logged.
void	setNoSystemExit(boolean noExit) Sets whether this server calls System.exit() when shutdown.
void	setPort(int port) Sets the server listen port.
void	setProperties(HsqlProperties p) Sets server properties using the specified properties object
void	setRestartOnShutdown(boolean restart) Sets whether this server restarts on shutdown.
protected void	setServerError(Throwable t) Sets this Server's last encountered error state.
void	setSilent(boolean silent) Sets silent mode operation
protected void	setState(int state) Sets the server state value.
void	setTls(boolean tls) Sets whether to use secure sockets
void	setTrace(boolean trace) Sets whether trace messages go to System.out or the DriverManger PrintStream/PrintWriter, if any.
void	setWebRoot(String root) Sets the path of the root directory from which web content is served.
void	signalCloseAllServerConnections() Closes all connections to this Server.
int	start() Starts this server synchronously.
int	stop() Stops this server asynchronously.

Methods inherited from class java.lang.Object

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

Field Detail

serverBundleHandle

protected static final int serverBundleHandle

serverId

protected String serverId

serverProtocol

protected int serverProtocol

serverConnectionThreadGroup

protected ThreadGroup serverConnectionThreadGroup

socketFactory

protected HsqlSocketFactory socketFactory

socket

protected ServerSocket socket

Constructor Detail

Server

public Server()

Creates a new Server instance handling HSQL protocol connections.

Server

protected Server(int protocol)

Creates a new Server instance handling the specified connection protocol.

For example, the no-args WebServer constructor invokes this constructor with ServerConstants.SC_PROTOCOL_HTTP, while the Server() no args contructor invokes this constructor with ServerConstants.SC_PROTOCOL_HSQL.

Parameters:

protocol - the ServerConstants code indicating which connection protocol to handle

Method Detail

main

public static void main(String[] args)

Creates and starts a new Server.

Allows starting a Server via the command line interface.

Parameters:

args - the command line arguments for the Server instance

checkRunning

public void checkRunning(boolean running)
                  throws RuntimeException

Checks if this Server object is or is not running and throws if the current state does not match the specified value.

Parameters:

running - if true, ensure the server is running, else ensure the server is not running

Throws:

RuntimeException - if the supplied value does not match the current running status

signalCloseAllServerConnections

public void signalCloseAllServerConnections()

Closes all connections to this Server.

Specified by:

signalCloseAllServerConnections in interface HsqlSocketRequestHandler

finalize

protected void finalize()
                 throws Throwable

Throws:

Throwable

getAddress

public String getAddress()

Retrieves, in string form, this server's host address.

Returns:

this server's host address

getDatabaseName

public String getDatabaseName(int index)

Retrieves the url alias (external name) of the i'th database that this Server hosts. NB Campbell - this shouldn't be used externally when ONLINE as names without path strings can be returned. Use the validated dbPath and dbType arrays.

Returns:

the url alias component of the i'th database that this Server hosts.

getDatabasePath

public String getDatabasePath(int index)

Retrieves the HSQLDB path descriptor (uri) of the i'th Database that this Server hosts. NB Campbell - this shouldn't be used externally when ONLINE as orphan path strings are returned. Use the validated dbPath and dbType arrays.

Returns:

the HSQLDB database path descriptor of the i'th database that this Server hosts

getDefaultPort

public static int getDefaultPort(boolean isTls)

Retrieves the default port that this Server will try to use in the abscence of an explicitly specified one, given the specified value for whether or not to use secure sockets.

Parameters:

isTls - if true, retrieve the default port when using secure sockets, else the default port when using plain sockets

Returns:

the default port used in the abscence of an explicit specification.

getDefaultPropertiesPath

public String getDefaultPropertiesPath()

Retrieves the path that will be used by default if a null or zero-length path is specified to putPropertiesFromFile(). This path does not include the '.properties' file extention, which is implicit. NB Campbell - this method is misleading and should be removed - default properties path is for the main() method only.

Returns:

The path that will be used by default if null is specified to putPropertiesFromFile()

getDefaultWebPage

public String getDefaultWebPage()

Retrieves the name of the web page served when no page is specified. This attribute is relevant only when server protocol is HTTP(S).

Returns:

the name of the web page served when no page is specified

getHelpString

public String getHelpString()

Retrieves a String object describing the command line and properties options for this Server.

Returns:

the command line and properties options help for this Server

getErrWriter

public PrintWriter getErrWriter()

Retrieves the PrintWriter to which server errors are printed.

Returns:

the PrintWriter to which server errors are printed.

getLogWriter

public PrintWriter getLogWriter()

Retrieves the PrintWriter to which server messages are printed.

Returns:

the PrintWriter to which server messages are printed.

getPort

public int getPort()

Retrieves this server's host port.

Returns:

this server's host port

getProductName

public String getProductName()

Retrieves this server's product name.

Typically, this will be something like: "HSQLDB xxx server".

Returns:

the product name of this server

getProductVersion

public String getProductVersion()

Retrieves the server's product version, as a String.

Typically, this will be something like: "1.x.x" or "2.x.x" and so on.

Returns:

the product version of the server

getProtocol

public String getProtocol()

Retrieves a string respresentaion of the network protocol this server offers, typically one of 'HTTP', HTTPS', 'HSQL' or 'HSQLS'.

Returns:

string respresentation of this server's protocol

getServerError

public Throwable getServerError()

Retrieves a Throwable indicating the last server error, if any.

Returns:

a Throwable indicating the last server error

getServerId

public String getServerId()

Retrieves a String identifying this Server object.

Returns:

a String identifying this Server object

getState

public int getState()

Retrieves current state of this server in numerically coded form.

Typically, this will be one of:

1. SERVER_ONLINE
2. SERVER_OPENING
3. SERVER_CLOSING
4. SERVER_SHUTDOWN

Returns:

this server's state code.

getStateDescriptor

public String getStateDescriptor()

Retrieves a character sequence describing this server's current state, including the message of the last exception, if there is one and it is still in context.

Returns:

this server's state represented as a character sequence.

getWebRoot

public String getWebRoot()

Retrieves the root context (directory) from which web content is served. This property is relevant only when the server protocol is HTTP(S). Although unlikely, it may be that in the future other contexts, such as jar urls may be supported, so that pages can be served from the contents of a jar or from the JVM class path.

Returns:

the root context (directory) from which web content is served

handleConnection

public void handleConnection(Socket s)

Assigns the specified socket to a new conection handler and starts the handler in a new Thread.

Specified by:

handleConnection in interface HsqlSocketRequestHandler

Parameters:

s - the socket to connect

isNoSystemExit

public boolean isNoSystemExit()

Retrieves whether this server calls System.exit() when shutdown.

Returns:

true if this server does not call System.exit()

isRestartOnShutdown

public boolean isRestartOnShutdown()

Retrieves whether this server restarts on shutdown.

Returns:

true this server restarts on shutdown

isSilent

public boolean isSilent()

Retrieves whether silent mode operation was requested in the server properties.

Returns:

if true, silent mode was requested, else trace messages are to be printed

isTls

public boolean isTls()

Retreives whether the use of secure sockets was requested in the server properties.

Returns:

if true, secure sockets are requested, else not

isTrace

public boolean isTrace()

Retrieves whether JDBC trace messages are to go to System.out or the DriverManger PrintStream/PrintWriter, if any.

Returns:

true if tracing is on (JDBC trace messages to system out)

putPropertiesFromFile

public boolean putPropertiesFromFile(String path)
                              throws RuntimeException

Attempts to put properties from the file with the specified path. The file extension '.properties' is implicit and should not be included in the path specification.

Parameters:

path - the path of the desired properties file, without the '.properties' file extension

Returns:

true if the indicated file was read sucessfully, else false

Throws:

RuntimeException - if this server is running

getPropertiesFromFile

protected static HsqlProperties getPropertiesFromFile(String path)

putPropertiesFromString

public void putPropertiesFromString(String s)
                             throws RuntimeException

Puts properties from the supplied string argument. The relevant key value pairs are the same as those for the (web)server.properties file format, except that the 'server.' prefix should not be specified.

Parameters:

s - semicolon-delimited key=value pair string, e.g. k1=v1;k2=v2;k3=v3...

Throws:

RuntimeException - if this server is running

setAddress

public void setAddress(String address)
                throws RuntimeException

Sets the InetAddress with which this server's ServerSocket will be constructed. A null or empty string or the special value "0.0.0.0" can be used to bypass explicit selection, causing the ServerSocket to be constructed without specifying an InetAddress.

Parameters:

address - A string representing the desired InetAddress as would be retrieved by InetAddres.getByName(), or a null or empty string or "0.0.0.0" to signify that the server socket should be constructed using the signature that does not specify the InetAddress.

Throws:

RuntimeException - if this server is running

setDatabaseName

public void setDatabaseName(int index,
                            String name)
                     throws RuntimeException

Sets the external name (url alias) of the i'th hosted database.

Parameters:

name - external name (url alias) of the i'th HSQLDB database instance this server is to host.

Throws:

RuntimeException - if this server is running

setDatabasePath

public void setDatabasePath(int index,
                            String path)
                     throws RuntimeException

Sets the path of the hosted database.

Parameters:

path - The path of the i'th HSQLDB database instance this server is to host.

Throws:

RuntimeException

setDefaultWebPage

public void setDefaultWebPage(String file)

Sets the name of the web page served when no page is specified.

Parameters:

file - the name of the web page served when no page is specified

setPort

public void setPort(int port)
             throws RuntimeException

Sets the server listen port.

Parameters:

port - the port at which this server listens

Throws:

RuntimeException

setErrWriter

public void setErrWriter(PrintWriter pw)

Sets the PrintWriter to which server errors are logged.

Setting this attribute to null disables server error logging

Parameters:

pw - the PrintWriter to which server messages are logged

setLogWriter

public void setLogWriter(PrintWriter pw)

Sets the PrintWriter to which server messages are logged.

Setting this attribute to null disables server message logging

Parameters:

pw - the PrintWriter to which server messages are logged

setNoSystemExit

public void setNoSystemExit(boolean noExit)

Sets whether this server calls System.exit() when shutdown.

Parameters:

noExit - if true, System.exit() will not be called.

setRestartOnShutdown

public void setRestartOnShutdown(boolean restart)

Sets whether this server restarts on shutdown.

Parameters:

restart - if true, this server restarts on shutdown

setSilent

public void setSilent(boolean silent)

Sets silent mode operation

Parameters:

silent - if true, then silent mode, else trace messages are to be printed

setTls

public void setTls(boolean tls)

Sets whether to use secure sockets

Parameters:

tls - true for secure sockets, else false

Throws:

RuntimeException - if this server is running

setTrace

public void setTrace(boolean trace)

Sets whether trace messages go to System.out or the DriverManger PrintStream/PrintWriter, if any.

Parameters:

trace - if true, route JDBC trace messages to System.out

setWebRoot

public void setWebRoot(String root)

Sets the path of the root directory from which web content is served.

Parameters:

root - the root (context) directory from which web content is served

setProperties

public void setProperties(HsqlProperties p)

Sets server properties using the specified properties object

Parameters:

p - The object containing properties to set

start

public int start()

Starts this server synchronously.

This method waits for current state to change from SERVER_STATE_OPENNING. In order to discover the success or failure of this operation, server state must be polled or a subclass of Server must be used that overrides the setState method to provide state change notification.

Returns:

the server state noted at entry to this method

stop

public int stop()

Stops this server asynchronously.

This method returns immediately, regardless of current state. In order to discover the success or failure of this operation, server state must be polled or a subclass of Server must be used that overrides the setState method to provide state change notification.

Returns:

the server state noted at entry to this method

allowConnection

protected boolean allowConnection(Socket socket)

Retrieves whether the specified socket should be allowed to make a connection. By default, this method always returns true, but it can be overidden to implement hosts allow-deny functionality.

Parameters:

socket - the socket to test.

init

protected void init(int protocol)

Initializes this server, setting the accepted connection protocol.

Parameters:

protocol - typically either SC_PROTOCOL_HTTP or SC_PROTOCOL_HSQL

setState

protected void setState(int state)

Sets the server state value.

Parameters:

state - the new value

print

protected void print(String msg)

Prints the specified message, s, formatted to identify that the print operation is against this server instance.

Parameters:

msg - The message to print

printStackTrace

protected void printStackTrace(Throwable t)

Prints the stack trace of the Throwable, t, to this Server object's errWriter.

Parameters:

t - the Throwable whose stack trace is to be printed

printWithThread

protected void printWithThread(String msg)

Prints a message formatted similarly to print(String), additionally identifying the current (calling) thread. Replaces old method trace(String msg).

printError

protected void printError(String msg)

Prints an error message to this Server object's errWriter. The message is formatted similarly to print(String), additionally identifying the current (calling) thread.

Parameters:

msg - the message to print

setServerError

protected void setServerError(Throwable t)

Sets this Server's last encountered error state.

Parameters:

t - The new value for the server error

printHelp

protected static void printHelp(String key)

Prints message for the specified key, without any special formatting. The message content comes from the server resource bundle and thus may localized according to the default JVM locale.

Uses System.out directly instead of Trace.printSystemOut() so it always prints, regardless of Trace settings.

Parameters:

key - for message

listLocalInetAddressNames

public static Vector listLocalInetAddressNames()

Retrieves a list of Strings naming the distinct, known to be valid local InetAddress names for this machine. The process is to collect and return the union of the following sets:

1. InetAddress.getAllByName(InetAddress.getLocalHost().getHostAddress())
2. InetAddress.getAllByName(InetAddress.getLocalHost().getHostName())
3. InetAddress.getAllByName(InetAddress.getByName(null).getHostAddress())
4. InetAddress.getAllByName(InetAddress.getByName(null).getHostName())
5. InetAddress.getByName("loopback").getHostAddress()
6. InetAddress.getByName("loopback").getHostname()

Returns:

the distinct, known to be valid local InetAddress names for this machine