Keys

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               = localhost
db.port               = 3306
db.schema             = sqlspaces
db.user               = sqlspaces
db.password           = sqlspaces
db.type               = HSQL

log.filename  = server.log
log.level     = OFF
log.toconsole = true

rightsmanagement.admins     = 
rightsmanagement.enabled    = false
rightsmanagement.spectators = 

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        = false
server.web.enabled          = true
server.web.port             = 8080
server.web.root             = .
server.remote-admin.enabled = true
server.remote-admin.port    = 2535
server.xmpp.host            = localhost
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 MYSQL, HSQL or PSQL.
• 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: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL
• log.toconsole: Either true if you want the logging lines also appear on the console, otherwise false.
• 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.localmode: If true the 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.web.enabled: If true a webserver will be started so that Investigator and Vizard (see chapter "Web based Investigation") or the Web Service component can be made available.
• server.shell.port: The port of the shell channel.
• server.shell.enabled: If true a shell server will be started so sssh clients can connect (see chapter "Shell").
• server.web.port: The port of the webserver (if server.web.enabled is true).
• 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.remote-admin.enabled: If true the 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.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 true the 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:

• Config File

  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.