Java Doc for Server.java in  » Database-DBMS » hsql » org » hsqldb » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

• 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 org.hsqldb.jdbc.jdbcConnection 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.

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
 

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.
author:
   fredt@users
version:
   1.8.0
since:
   1.7.2

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 whichconnection protocol to handle

Typically, this will be something like: "HSQLDB xxx server". the product name of this server

Typically, this will be something like: "1.x.x" or "2.x.x" and so on. the product version of the server

a Throwable indicating the last server error

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)

Allows starting a Server via the command line interface.

Parameters:
  args - the command line arguments for the Server instance

Uses System.out directly instead of Trace.printSystemOut() so it always prints, regardless of Trace settings.
Parameters:
  key - for message

The message is formatted similarly to print(String), additionally indicating the connection identifier.

For Server instances, cid is typically the value assigned to each ServerConnection object that is unique amongst all such identifiers in each distinct JVM session / class loader context.

For WebServer instances, a single logical connection actually spawns a new physical WebServerConnection object for each request, so the cid is typically the underlying session id, since that does not change for the duration of the logical connection.
Parameters:
  cid - the connection identifier
Parameters:
  r - the request whose description is to be printed

Parameters:
  t - the Throwable whose stack trace is to be printed

Setting this attribute to null disables server error logging
Parameters:
  pw - 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

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. the server state noted at entry to this method

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. the server state noted at entry to this method