org.hsqldb.server

## Class Server

- java.lang.Object
- - org.hsqldb.server.Server

- All Implemented Interfaces:
    org.hsqldb.lib.Notified, org.hsqldb.server.HsqlSocketRequestHandler
  Direct Known Subclasses:
    WebServer

      public class Server
      extends java.lang.Object
      implements org.hsqldb.server.HsqlSocketRequestHandler, org.hsqldb.lib.Notified

  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 efficiently across the network. Server's direct descendant, WebServer, handles HTTP protocol connections exclusively, allowing HSQL protocol to be tunnelled 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          |
       +-----------------+-------------+----------+------------------------------|
       | --help          |             |          | 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  |
       | --props         | filepath    |          | file path of properties file |
       +-----------------+-------------+----------+------------------------------+

  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.

  - When the remote_open property is true, a connection attempt to an unopened database results in the database being opened. The URL for connection should include the property filepath to specify the path. 'jdbc:hsqldb:hsql[s]://host[port]/<alias>;filepath=hsqldb:file:<database path>'. the given alias and filepath value will be associated together. The database user and password to start this connection must be valid. If this form of connection is used again, after the database has been opened, the filepath property is ignored.
  - Once an alias such as "mydb" has been associated with a path, it cannot be reassigned to a different path.
  - If a database is closed with the SHUTDOWN command, its alias is removed. It is then possible to connect to this database again with a different (or the same) alias.
  - If the same database is connected to via two different aliases, and then one of the is closed with the SHUTDOWN command, the other is also closed.

  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 instance is started as part of a larger framework.

  Since:
    1.7.2
  Author:
    Fred Toussi (fredt@users dot sourceforge.net)

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Server()` Creates a new Server instance handling HSQL protocol connections.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `java.lang.String` | `getAddress()` Retrieves, in string form, this server's host address.
    `java.lang.String` | `getDatabaseName(int index, boolean asconfigured)` Retrieves the url alias (network name) of the i'th database that this Server hosts.
    `java.lang.String` | `getDatabasePath(int index, boolean asconfigured)` Retrieves the HSQLDB path descriptor (uri) of the i'th Database that this Server hosts.
    `java.lang.String` | `getDatabaseType(int index)`
    `java.lang.String` | `getDefaultWebPage()` Retrieves the name of the web page served when no page is specified.
    `java.io.PrintWriter` | `getErrWriter()` Retrieves the PrintWriter to which server errors are printed.
    `java.lang.String` | `getHelpString()` Retrieves a String object describing the command line and properties options for this Server.
    `java.io.PrintWriter` | `getLogWriter()` Retrieves the PrintWriter to which server messages are printed.
    `int` | `getPort()` Retrieves this server's host port.
    `java.lang.String` | `getProductName()` Retrieves this server's product name.
    `java.lang.String` | `getProductVersion()` Retrieves the server's product version, as a String.
    `java.lang.String` | `getProtocol()` Retrieves a string resresentaion of the network protocol this server offers, typically one of 'HTTP', HTTPS', 'HSQL' or 'HSQLS'.
    `java.lang.Throwable` | `getServerError()` Retrieves a Throwable indicating the last server error, if any.
    `java.lang.String` | `getServerId()` Retrieves a String identifying this Server object.
    `java.lang.Thread` | `getServerThread()` Returns thread object for "HSQLDB Server" thread
    `int` | `getState()` Retrieves current state of this server in numerically coded form.
    `java.lang.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.
    `java.lang.String` | `getWebRoot()` Retrieves the root context (directory) from which web content is served.
    `void` | `handleConnection(java.net.Socket s)` Assigns the specified socket to a new connection handler and starts the handler in a new Thread.
    `boolean` | `isNoSystemExit()` Retrieves whether this server calls System.exit() when shutdown.
    `boolean` | `isNotRunning()` Returns true if this server is not running
    `boolean` | `isRestartOnShutdown()` Retrieves whether this server restarts on shutdown.
    `boolean` | `isSilent()` Retrieves whether silent mode operation was requested in the server properties.
    `boolean` | `isTls()` Retrieves 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 void` | `main(java.lang.String[] args)` Creates and starts a new Server.
    `void` | `notify(int id)` This is called from org.hsqldb.DatabaseManager when a database is shutdown.
    `boolean` | `putPropertiesFromFile(java.lang.String path)` Attempts to put properties from the file with the specified path.
    `boolean` | `putPropertiesFromFile(java.lang.String path, java.lang.String extension)` Attempts to put properties from the file with given extension.
    `void` | `putPropertiesFromString(java.lang.String s)` Puts properties from the supplied string argument.
    `void` | `setAddress(java.lang.String address)` Sets the InetAddress with which this server's ServerSocket will be constructed.
    `void` | `setDaemon(boolean daemon)` Sets whether server thread is a daemon.
    `void` | `setDatabaseName(int index, java.lang.String name)` Sets the external name (url alias) of the i'th hosted database.
    `void` | `setDatabasePath(int index, java.lang.String path)` Sets the path of the hosted database.
    `void` | `setDefaultWebPage(java.lang.String file)` Sets the name of the web page served when no page is specified.
    `void` | `setErrWriter(java.io.PrintWriter pw)` Sets the PrintWriter to which server errors are logged.
    `void` | `setLogWriter(java.io.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(org.hsqldb.persist.HsqlProperties props)` Sets server properties using the specified properties object
    `void` | `setRestartOnShutdown(boolean restart)` Sets whether this server restarts on shutdown.
    `void` | `setSilent(boolean silent)` Sets silent mode operation
    `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(java.lang.String root)` Sets the path of the root directory from which web content is served.
    `void` | `shutdown()` External method to shut down this server.
    `void` | `shutdownCatalogs(int shutdownMode)` Shuts down all the database served by this server.
    `void` | `shutdownWithCatalogs(int shutdownMode)` Shuts down this server and all the database served by this server.
    `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

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

- - ### Constructor Detail

    - #### Server

          public Server()

      Creates a new Server instance handling HSQL protocol connections.

  - ### Method Detail

    - #### getServerThread

          public java.lang.Thread getServerThread()

      Returns thread object for "HSQLDB Server" thread
      Returns:
        thread

    - #### 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:
        `org.hsqldb.HsqlException` - if the supplied value does not match the current running status

    - #### isNotRunning

          public boolean isNotRunning()

      Returns true if this server is not running
      Returns:
        boolean

    - #### signalCloseAllServerConnections

          public void signalCloseAllServerConnections()

      Closes all connections to this Server.
      Specified by:
        `signalCloseAllServerConnections` in interface `org.hsqldb.server.HsqlSocketRequestHandler`

    - #### getAddress

          public java.lang.String getAddress()

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

    - #### getDatabaseName

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

    - #### getDatabasePath

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

    - #### getDatabaseType

          public java.lang.String getDatabaseType(int index)

    - #### getDefaultWebPage

          public java.lang.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 java.lang.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 java.io.PrintWriter getErrWriter()

      Retrieves the PrintWriter to which server errors are printed.
      Returns:
        the PrintWriter to which server errors are printed.

    - #### getLogWriter

          public java.io.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 java.lang.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 java.lang.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 java.lang.String getProtocol()

      Retrieves a string resresentaion of the network protocol this server offers, typically one of 'HTTP', HTTPS', 'HSQL' or 'HSQLS'.
      Returns:
        string representation of this server's protocol

    - #### getServerError

          public java.lang.Throwable getServerError()

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

      Returns:
        a Throwable indicating the last server error

    - #### getServerId

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

    - #### getStateDescriptor

          public java.lang.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 java.lang.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(java.net.Socket s)

      Assigns the specified socket to a new connection handler and starts the handler in a new Thread.
      Specified by:
        `handleConnection` in interface `org.hsqldb.server.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()

      Retrieves 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(java.lang.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 successfully, else false
      Throws:
        `org.hsqldb.HsqlException` - if this server is running

    - #### putPropertiesFromFile

          public boolean putPropertiesFromFile(java.lang.String path,
                                               java.lang.String extension)

      Attempts to put properties from the file with given extension.
      Parameters:
        `path` - the path of the desired properties file.
        `extension` - extension to add to path
      Returns:
        true if the indicated file was read successfully, else false
      Throws:
        `org.hsqldb.HsqlException` - if this server is running

    - #### putPropertiesFromString

          public void putPropertiesFromString(java.lang.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. silent=false;port=8080;...
      Throws:
        `org.hsqldb.HsqlException` - if this server is running

    - #### setAddress

          public void setAddress(java.lang.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:
        `org.hsqldb.HsqlException` - if this server is running

    - #### setDatabaseName

          public void setDatabaseName(int index,
                                      java.lang.String name)

      Sets the external name (url alias) of the i'th hosted database.
      Parameters:
        `index` - int
        `name` - external name (url alias) of the i'th HSQLDB database instance this server is to host.

    - #### setDatabasePath

          public void setDatabasePath(int index,
                                      java.lang.String path)

      Sets the path of the hosted database. The path always starts with the catalog type. Examples of the path include: "file:mydir/mydb", "mem:mymemdb", "res:org/mydomain/mydbs/settingsdb".
      Parameters:
        `index` - int
        `path` - The path of the i'th HSQLDB database instance this server is to host.

    - #### setDefaultWebPage

          public void setDefaultWebPage(java.lang.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)

      Sets the server listen port.
      Parameters:
        `port` - the port at which this server listens

    - #### setErrWriter

          public void setErrWriter(java.io.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(java.io.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:
        `org.hsqldb.HsqlException` - 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

    - #### setDaemon

          public void setDaemon(boolean daemon)

      Sets whether server thread is a daemon. Used before starting. The default is false.
      Parameters:
        `daemon` - if true, start the thread as a daemon thread

    - #### setWebRoot

          public void setWebRoot(java.lang.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(org.hsqldb.persist.HsqlProperties props)
                             throws java.io.IOException,
                                    ServerAcl.AclFormatException

      Sets server properties using the specified properties object
      Parameters:
        `props` - The object containing properties to set
      Throws:
        `ServerAcl.AclFormatException` - ACL list was requested but problem loading ACL.
        `java.io.IOException` - ACL list was requested but I/O problem loading ACL.

    - #### 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

    - #### notify

          public final void notify(int id)

      This is called from org.hsqldb.DatabaseManager when a database is shutdown. This shuts the server down if it is the last database
      Specified by:
        `notify` in interface `org.hsqldb.lib.Notified`
      Parameters:
        `id` - database id

    - #### shutdownCatalogs

          public void shutdownCatalogs(int shutdownMode)

      Shuts down all the database served by this server. As a consequence, this server and any other server that is serving a subset of the databases will be shutdown, unless the server was started with server.remote_open property. The shutdownMode must be one of:
      - org.hsqldb.Database.CLOSEMODE_IMMEDIATELY
      - org.hsqldb.Database.CLOSEMODE_NORMAL
      - org.hsqldb.Database.CLOSEMODE_COMPACT
      - org.hsqldb.Database.CLOSEMODE_SCRIPT
      Parameters:
        `shutdownMode` - a value between 0-4, usually 0 or 1.

    - #### shutdownWithCatalogs

          public void shutdownWithCatalogs(int shutdownMode)

      Shuts down this server and all the database served by this server. As a consequence, any other server that is serving a subset of the databases will be shutdown, unless the server was started with server.remote_open property. The shutdownMode must be one of:
      - org.hsqldb.Database.CLOSEMODE_IMMEDIATELY
      - org.hsqldb.Database.CLOSEMODE_NORMAL
      - org.hsqldb.Database.CLOSEMODE_COMPACT
      - org.hsqldb.Database.CLOSEMODE_SCRIPT
      Parameters:
        `shutdownMode` - a value between 0-4, usually 0 or 1.

    - #### shutdown

          public void shutdown()

      External method to shut down this server.

    - #### main

          public static void main(java.lang.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

Copyright © 2001 - 2018 HSQL Development Group.