org.hsqldb

Class Server

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()   |
 | -remote_open   | true|false  | false    | can open databases remotely  |
 +----------------+-------------+----------+------------------------------+
 
The database.i and dbname.i options need further explanation: 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.

Replaces original Hypersonic source of the same name.

Since: 1.7.2

Author: fredt@users

UNKNOWN: description="HSQLDB Server" extends="org.hsqldb.mx.mbean.RegistrationSupportBaseMBean"

Constructor Summary
Server()
Creates a new Server instance handling HSQL protocol connections.
Method Summary
voidcheckRunning(boolean running)
Checks if this Server object is or is not running and throws if the current state does not match the specified value.
StringgetAddress()
Retrieves, in string form, this server's host address.
StringgetDatabaseName(int index, boolean asconfigured)
Retrieves the url alias (network name) of the i'th database that this Server hosts.
StringgetDatabasePath(int index, boolean asconfigured)
Retrieves the HSQLDB path descriptor (uri) of the i'th Database that this Server hosts.
StringgetDatabaseType(int index)
StringgetDefaultWebPage()
Retrieves the name of the web page served when no page is specified.
PrintWritergetErrWriter()
Retrieves the PrintWriter to which server errors are printed.
StringgetHelpString()
Retrieves a String object describing the command line and properties options for this Server.
PrintWritergetLogWriter()
Retrieves the PrintWriter to which server messages are printed.
intgetPort()
Retrieves this server's host port.
StringgetProductName()
Retrieves this server's product name.
StringgetProductVersion()
Retrieves the server's product version, as a String.
StringgetProtocol()
Retrieves a string respresentaion of the network protocol this server offers, typically one of 'HTTP', HTTPS', 'HSQL' or 'HSQLS'.
ThrowablegetServerError()
Retrieves a Throwable indicating the last server error, if any.
StringgetServerId()
Retrieves a String identifying this Server object.
intgetState()
Retrieves current state of this server in numerically coded form.
StringgetStateDescriptor()
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.
StringgetWebRoot()
Retrieves the root context (directory) from which web content is served.
voidhandleConnection(Socket s)
Assigns the specified socket to a new conection handler and starts the handler in a new Thread.
booleanisNoSystemExit()
Retrieves whether this server calls System.exit() when shutdown.
booleanisRestartOnShutdown()
Retrieves whether this server restarts on shutdown.
booleanisSilent()
Retrieves whether silent mode operation was requested in the server properties.
booleanisTls()
Retrieves whether the use of secure sockets was requested in the server properties.
booleanisTrace()
Retrieves whether JDBC trace messages are to go to System.out or the DriverManger PrintStream/PrintWriter, if any.
static voidmain(String[] args)
Creates and starts a new Server.
booleanputPropertiesFromFile(String path)
Attempts to put properties from the file with the specified path.
voidputPropertiesFromString(String s)
Puts properties from the supplied string argument.
voidsetAddress(String address)
Sets the InetAddress with which this server's ServerSocket will be constructed.
voidsetDatabaseName(int index, String name)
Sets the external name (url alias) of the i'th hosted database.
voidsetDatabasePath(int index, String path)
Sets the path of the hosted database.
voidsetDefaultWebPage(String file)
Sets the name of the web page served when no page is specified.
voidsetErrWriter(PrintWriter pw)
Sets the PrintWriter to which server errors are logged.
voidsetLogWriter(PrintWriter pw)
Sets the PrintWriter to which server messages are logged.
voidsetNoSystemExit(boolean noExit)
Sets whether this server calls System.exit() when shutdown.
voidsetPort(int port)
Sets the server listen port.
voidsetProperties(HsqlProperties p)
Sets server properties using the specified properties object
voidsetRestartOnShutdown(boolean restart)
Sets whether this server restarts on shutdown.
voidsetSilent(boolean silent)
Sets silent mode operation
voidsetTls(boolean tls)
Sets whether to use secure sockets
voidsetTrace(boolean trace)
Sets whether trace messages go to System.out or the DriverManger PrintStream/PrintWriter, if any.
voidsetWebRoot(String root)
Sets the path of the root directory from which web content is served.
voidshutdown()
External method to shut down this server.
voidsignalCloseAllServerConnections()
Closes all connections to this Server.
intstart()
Starts this server synchronously.
intstop()
Stops this server asynchronously.

Constructor Detail

Server

public Server()
Creates a new Server instance handling HSQL protocol connections.

Method Detail

checkRunning

public 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.

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

getAddress

public String getAddress()
Retrieves, in string form, this server's host address.

Returns: this server's host address

UNKNOWN: access="read-write" description="Host InetAddress"

getDatabaseName

public String getDatabaseName(int index, boolean asconfigured)
Retrieves the url alias (network name) of the i'th database that this Server hosts.

Parameters: index the index of the url alias upon which to report asconfigured if true, report the configured value, else the live value

Returns: the url alias component of the i'th database that this Server hosts, or null if no such name exists.

UNKNOWN: impact="INFO" description="url alias component of the i'th hosted Database" name="index" type="int" position="0" description="This Server's index for the hosted Database" name="asconfigured" type="boolean" position="1" description="if true, the configured value, else the live value"

getDatabasePath

public String getDatabasePath(int index, boolean asconfigured)
Retrieves the HSQLDB path descriptor (uri) of the i'th Database that this Server hosts.

Parameters: index the index of the uri upon which to report asconfigured if true, report the configured value, else the live value

Returns: the HSQLDB database path descriptor of the i'th database that this Server hosts, or null if no such path descriptor exists

UNKNOWN: impact="INFO" description="For i'th hosted database" name="index" type="int" position="0" description="This Server's index for the hosted Database" name="asconfigured" type="boolean" position="1" description="if true, the configured value, else the live value"

getDatabaseType

public String getDatabaseType(int index)

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

UNKNOWN: access="read-write" description="Used when server protocol is HTTP(S)"

getErrWriter

public PrintWriter getErrWriter()
Retrieves the PrintWriter to which server errors are printed.

Returns: the PrintWriter to which server errors are printed.

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

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

UNKNOWN: access="read-write" description="At which ServerSocket listens for connections"

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

UNKNOWN: access="read-only" description="Of 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

UNKNOWN: access="read-only" description="Of 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

UNKNOWN: access="read-only" description="Used to handle connections"

getServerError

public Throwable getServerError()
Retrieves a Throwable indicating the last server error, if any.

Returns: a Throwable indicating the last server error

UNKNOWN: access="read-only" description="Indicating last exception state"

getServerId

public String getServerId()
Retrieves a String identifying this Server object.

Returns: a String identifying this Server object

UNKNOWN: access="read-only" description="Identifying Server"

getState

public int getState()
Retrieves current state of this server in numerically coded form.

Typically, this will be one of:

  1. ServerProperties.SERVER_STATE_ONLINE (1)
  2. ServerProperties.SERVER_STATE_OPENING (4)
  3. ServerProperties.SERVER_STATE_CLOSING (8)
  4. ServerProperties.SERVER_STATE_SHUTDOWN (16)

Returns: this server's state code.

UNKNOWN: access="read-only" description="1:ONLINE 4:OPENING 8:CLOSING, 16:SHUTDOWN"

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.

UNKNOWN: access="read-only" description="State as string"

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

UNKNOWN: access="read-write" description="Context (directory)"

handleConnection

public void handleConnection(Socket s)
Assigns the specified socket to a new conection handler and starts the handler in a new Thread.

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()

UNKNOWN: access="read-write" description="When Shutdown"

isRestartOnShutdown

public boolean isRestartOnShutdown()
Retrieves whether this server restarts on shutdown.

Returns: true this server restarts on shutdown

UNKNOWN: access="read-write" description="Automatically?"

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

UNKNOWN: access="read-write" description="No trace messages?"

isTls

public boolean isTls()
Retrieves whether the use of secure sockets was requested in the server properties.

Returns: if true, secure sockets are requested, else not

UNKNOWN: access="read-write" description="Use TLS/SSL sockets?"

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)

UNKNOWN: access="read-write" description="JDBC trace messages to System.out?"

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

putPropertiesFromFile

public boolean putPropertiesFromFile(String path)
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

UNKNOWN: impact="ACTION" description="Reads in properties" name="path" type="java.lang.String" position="0" description="(optional) returns false if path is empty"

putPropertiesFromString

public void putPropertiesFromString(String s)
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

UNKNOWN: impact="ACTION" description="'server.' key prefix automatically supplied" name="s" type="java.lang.String" position="0" description="semicolon-delimited key=value pairs"

setAddress

public void setAddress(String address)
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

UNKNOWN:

setDatabaseName

public void setDatabaseName(int index, String name)
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

UNKNOWN: impact="ACTION" description="Sets the url alias by which is known the i'th hosted Database" name="index" type="int" position="0" description="This Server's index for the hosted Database" name="name" type="java.lang.String" position="1" description="url alias component for the hosted Database"

setDatabasePath

public void setDatabasePath(int index, String path)
Sets the path of the hosted database.

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

UNKNOWN: impact="ACTION" description="Sets the database uri path for the i'th hosted Database" name="index" type="int" position="0" description="This Server's index for the hosted Database" name="path" type="java.lang.String" position="1" description="database uri path of the hosted Database"

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

UNKNOWN:

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.

UNKNOWN:

setPort

public void setPort(int port)
Sets the server listen port.

Parameters: port the port at which this server listens

UNKNOWN:

setProperties

public void setProperties(HsqlProperties p)
Sets server properties using the specified properties object

Parameters: p The object containing properties to set

setRestartOnShutdown

public void setRestartOnShutdown(boolean restart)
Sets whether this server restarts on shutdown.

Parameters: restart if true, this server restarts on shutdown

UNKNOWN:

setSilent

public void setSilent(boolean silent)
Sets silent mode operation

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

UNKNOWN:

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

UNKNOWN:

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

UNKNOWN:

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

UNKNOWN:

shutdown

public void shutdown()
External method to shut down this server.

signalCloseAllServerConnections

public void signalCloseAllServerConnections()
Closes all connections to this Server.

UNKNOWN: impact="ACTION" description="Closes all open connections"

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

UNKNOWN: impact="ACTION_INFO" description="Invokes asynchronous startup sequence; returns previous state"

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

UNKNOWN: impact="ACTION_INFO" description="Invokes asynchronous shutdown sequence; returns previous state"

Copyright B) 2001 - 2005 HSQL Development Group. All Rights Reserved.