|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.hsqldb.Server
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:
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:
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
.
This behaviour allows the previous database connection url format to work with essentially unchanged semantics.
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=trueStarting 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:
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.
Constructor Summary | |
Server()
Creates a new Server instance handling HSQL protocol connections. |
Method Summary | |
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 respresentaion 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. |
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 conection handler and starts the handler in a new Thread. |
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()
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. |
boolean |
putPropertiesFromFile(java.lang.String path)
Attempts to put properties from the file with the specified path. |
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 |
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 p)
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 |
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 |
public Server()
Method Detail |
public static void main(java.lang.String[] args)
Allows starting a Server via the command line interface.
args
- the command line arguments for the Server instancepublic void checkRunning(boolean running) throws java.lang.RuntimeException
running
- if true, ensure the server is running, else ensure the
server is not running
java.lang.RuntimeException
- if the supplied value does not match the
current running statuspublic void signalCloseAllServerConnections()
signalCloseAllServerConnections
in interface org.hsqldb.HsqlSocketRequestHandler
public java.lang.String getAddress()
public java.lang.String getDatabaseName(int index, boolean asconfigured)
index
- the index of the url alias upon which to reportasconfigured
- if true, report the configured value, else
the live value
public java.lang.String getDatabasePath(int index, boolean asconfigured)
index
- the index of the uri upon which to reportasconfigured
- if true, report the configured value, else
the live value
public java.lang.String getDatabaseType(int index)
public java.lang.String getDefaultWebPage()
public java.lang.String getHelpString()
public java.io.PrintWriter getErrWriter()
public java.io.PrintWriter getLogWriter()
public int getPort()
public java.lang.String getProductName()
Typically, this will be something like: "HSQLDB xxx server".
public java.lang.String getProductVersion()
Typically, this will be something like: "1.x.x" or "2.x.x" and so on.
public java.lang.String getProtocol()
public java.lang.Throwable getServerError()
public java.lang.String getServerId()
public int getState()
Typically, this will be one of:
public java.lang.String getStateDescriptor()
public java.lang.String getWebRoot()
public void handleConnection(java.net.Socket s)
handleConnection
in interface org.hsqldb.HsqlSocketRequestHandler
s
- the socket to connectpublic boolean isNoSystemExit()
public boolean isRestartOnShutdown()
public boolean isSilent()
public boolean isTls()
public boolean isTrace()
public boolean putPropertiesFromFile(java.lang.String path)
path
- the path of the desired properties file, without the
'.properties' file extension
java.lang.RuntimeException
- if this server is runningpublic void putPropertiesFromString(java.lang.String s)
s
- semicolon-delimited key=value pair string,
e.g. k1=v1;k2=v2;k3=v3...
java.lang.RuntimeException
- if this server is runningpublic void setAddress(java.lang.String address) throws java.lang.RuntimeException
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.
java.lang.RuntimeException
- if this server is runningpublic void setDatabaseName(int index, java.lang.String name) throws java.lang.RuntimeException
name
- external name (url alias) of the i'th HSQLDB database
instance this server is to host.
java.lang.RuntimeException
- if this server is runningpublic void setDatabasePath(int index, java.lang.String path) throws java.lang.RuntimeException
path
- The path of the i'th HSQLDB database instance this server
is to host.
java.lang.RuntimeException
public void setDefaultWebPage(java.lang.String file)
file
- the name of the web page served when no page is specifiedpublic void setPort(int port) throws java.lang.RuntimeException
port
- the port at which this server listens
java.lang.RuntimeException
public void setErrWriter(java.io.PrintWriter pw)
Setting this attribute to null disables server error logging
pw
- the PrintWriter to which server messages are loggedpublic void setLogWriter(java.io.PrintWriter pw)
Setting this attribute to null disables server message logging
pw
- the PrintWriter to which server messages are loggedpublic void setNoSystemExit(boolean noExit)
noExit
- if true, System.exit() will not be called.public void setRestartOnShutdown(boolean restart)
restart
- if true, this server restarts on shutdownpublic void setSilent(boolean silent)
silent
- if true, then silent mode, else trace messages
are to be printedpublic void setTls(boolean tls)
tls
- true for secure sockets, else false
java.lang.RuntimeException
- if this server is runningpublic void setTrace(boolean trace)
trace
- if true, route JDBC trace messages to System.outpublic void setWebRoot(java.lang.String root)
root
- the root (context) directory from which web content
is servedpublic void setProperties(org.hsqldb.persist.HsqlProperties p)
p
- The object containing properties to setpublic int start()
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.
public int stop()
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.
public void shutdown()
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |