After unpacking the ZIP file, a directory
sqlspaces should have been created. Within this folder you can find starting scripts for Linux (
startServer.sh) and Windows (
startServer.bat). However, before starting the server, you should have a look at the configuration. Most of the values are default values, that should work without changing, but some of them might be interesting for you. The values are ordered hierarchically by the well known dot notation. You can change these settings in different ways, but in all cases you change the values of the following key-value pairs (this is the current default configuration):
db.connectionpoolsize = 80 db.querylimit = 100000 db.hsql.destination = memory db.hsql.fieldsize = 4 db.host = 127.0.0.1 db.port = 3306 db.schema = sqlspaces db.password = sqlspaces db.type = HSQL db.user = sqlspaces log.filename = server.log log.level = INFO log.toconsole = false xmlconnector.connection.timeout = 0 xmlconnector.connection.protocol = XML rightsmanagement.admins = rightsmanagement.enabled = false rightsmanagement.spectators = server.versioned = true server.garbage-collector.enabled = true server.garbage-collector.interval = 600 server.remote-admin.enabled = true server.remote-admin.port = 2535 server.localmode = false server.non-ssl.port = 2525 server.non-ssl.enabled = true server.ssl.port = 2530 server.ssl.enabled = false server.shell.port = 2540 server.shell.enabled = true server.web.enabled = true server.web.port = 8080 server.web.root = . server.ws.message-size = 32 server.ws.timeout = 120 server.xmpp.host = 127.0.0.1 server.xmpp.enabled = false server.xmpp.port.external = 5275 server.xmpp.port.client = 5222 server.xmpp.service.name = sqlspaces server.xmpp.service.secret = sqlspaces
The meaning of the single lines are as follows:
- db.connectionpoolsize: The amount of JDBC connections the server is allowed to establish.
- db.querylimit: The size of the slices to fetch from the database. If you increase this value, you speed up queries with many results. You should decrease this value, if the database gets memory problems, because the slices are too big.
- db.hsql.destination: If HSQLDB is used: Either memory to store all data in a non persistent way in the working memory or the path to an arbitrary file (e.g.
file:/D:/mydata), where the data should be stored.
- db.hsql.fieldsize: If HSQLDB is used: Since HSQLDB 2.0 binary and character columns have a default length of 1 MB. To be able to store values bigger than this, you have to adapt this value. The value is a number of megabytes.
- db.host: If MySQL or PSQL is used: The host where the database server is running.
- db.port: If MySQL or PSQL used: The port the database server is running on.
- db.schema: If MySQL or PSQL is used: The name of the schema. The user should have full rights on this schema.
- db.password: The password for the database connection. If you use HSQLDB this is irrelevant.
- db.type: At the moment either
- db.user: The username for the database connection. If you use HSQLDB this is irrelevant.
- log.filename: The path to the logfile. The server process needs read and write access to this file, of course.
- log.level: Following loglevels are available:
- log.toconsole: Either
trueif you want the logging lines also appear on the console, otherwise
xmlconnector.connection.timeout: The timeout in milliseconds of the XML/JSON socket. A zero means the OS default.
- xmlconnector.connection.protocol: Either
JSONor@ XML@. This is only the default configuration for the client. The server always supports both.
- rightsmanagement.admins: If rightsmanagement is enabled: A comma-separated list of names of the users that should have all rights.
- rightsmanagement.enabled: true if the rightsmanagement should be enabled. In this case it is checked if the user has the right to do an action before it is executed.
- rightsmanagement.spectators: If rightsmanagement is enabled: A comma-separated list of names of the users that only have guest accounts. They have only read access.
- server.versioned: If set to
true, the versioning is enabled (c.f. chapter "Advanced Features" --> "Versioning").
- server.garbage-collector.enabled = If
truethe garbage collector is activated, i.e. it gets active in regular intervals and cleans the database. Enabled by default and should only be deactivated for good reasons (e.g. for doing benchmarks without "noise").
- server.garbage-collector.interval = The interval between two runs of the garbage-collector.
- server.remote-admin.enabled: If
truethe remote-admin channel will be opened. This is important for external tools like the Investigator or the Vizard.
- server.remote-admin.port: The port of the remote-admin channel.
- server.localmode: If
truethe server first tries to establish a connection within the Java virtual machine (without sockets), that is faster than the normal one. However, this can only be used if the server and the client were started in the same process (not only the same machine!).
- server.non-ssl.port: The standard port of the SQLSpaces server. On this port clients will connect, so it might be clever to check the firewall settings if connection problems occur. This is the port for the unencrypted communication.
- server.non-ssl.enabled: By setting this to
false, the non-ssl port can be disabled, if you only want to allow secure connections.
- server.ssl.port: The ssl standard port of the SQLSpaces server. Same as server.non-ssl.port but encrypted. If both ports are set, they need to be different, of course.
- server.ssl.enabled: Compare server.non-ssl.enabled.
- server.shell.port: The port of the shell channel.
- server.shell.enabled: If
truea shell server will be started so sssh clients can connect (see chapter "Shell").
- server.web.enabled: If
truea webserver will be started so that Investigator and Vizard (see chapter "Web based Investigation") or the Web Service component can be made available.
- server.web.port: The port of the webserver (if server.web.enabled is
- server.web.root: This is the path where the webserver will look for WAR files. By default it is the folder, in which also the start scripts are located.
- server.ws.message-size = The maximum message size of the websocket connector in MB.
- server.ws.timeout = The timeout of the websocket connector in minutes.
- server.xmpp.host: If the XMPP tunneling is being used, then this entry must point to the host of the XMPP server.
- server.xmpp.enabled: If
truethe XMPP tunneling will be used.
- server.xmpp.port.external: This is the external components port of the XMPP server.
- server.xmpp.port.client: The port for normal XMPP connections to the server.
server.xmpp.service.name: The name of the service, with which the SQLSpaces server should register itself on the XMPP server.
- server.xmpp.service.secret: The password that has been configured in the XMPP server for the SQLSpaces component.
Setting the values¶
There are the following three ways of setting the values:
The configuration file is called
sqlsconfig.properties and is parsed once during startup, so later changes will not effect running servers. The file is a simple properties file, i.e. it contains plain text and has in each line a name-value-pair that is connected with a ``=''.
If you want to change the name or location of the config file, you can do that by setting the system property "sqlsconfig". You can do that either in Java by
System.setProperty("sqlsconfig", "/home/stefan/default-sqlsconfig.properties"); or (and that is actually intended) by passing it as a command-line argument, i.e.
java myPackage.myApplication -Dsqlsconfig=/home/stefan/default-sqlsconfig.properties . Please be aware that the programmatic approach (with
System.setProperty(...)) only works, if you set the property before the first invocation of any SQLSpaces code. Otherwise the configuration has already been initiated.
Global OS Variables¶
You can also override the default settings by defining global variables. This is either done on an OS level or by adding them to the commandline call of the server. In both cases, you have to put "sqlspaces." before the keys. If you for instance want to set the database type for your application (that is in contained in an executable jar) via commandline parameter, you have to start your program like that:
java -Dsqlspaces.db.type=PSQL -jar MyApplicationsJar.jar
Java-VM internal Call¶
Especially if you start the server from within a Java process (and not by simply using the startup script), you can change all settings by calling methods on the internal configuration class (
info.collide.sqlspaces.commons.Configuration). This class has a static
getInstance() method, that returns the configuration singleton. As long as these values are changed before the start of the server (
Server.startServer()), they are used.