z2-Environment

h2. Running a Java DB Network Server

In samples we use the Java DB, i.e. the SQL database implementation that comes with the Java SE Development Kit (JDK) by Oracle (except for Mac OS in which case you have to use Apache Derby). Java DB is the same as the "Apache Derby DB":http://db.apache.org/derby - see also the "installation how-to":http://db.apache.org/derby/papers/DerbyTut/install_software.html.

The instructions below apply to both, there is only a difference in the installation path. 

For general information on Java DB go to http://docs.oracle.com/javadb/10.8.2.2/getstart/index.html

To run the Java DB in server mode, which is what we want to do, run

<pre><code class="ruby">

mkdir derby

cd derby

java -jar $JAVA_HOME/db/lib/derbyrun.jar server start

</code></pre>

assuming you want to run it in the folder *derby*. At a second time you can omit the "mkdir" command of course. The environment variable JAVA_HOME is expected to point to your JDK installation folder. When you installed Apache Derby and followed the instructions mentioned above, you have to replace $JAVA_HOME by $DERBY_HOME.

On Windows run

<pre><code class="ruby">

mkdir derby

cd derby

java -jar "%JAVA_HOME%\db\lib\derbyrun.jar" server start

</code></pre>

In order to interactively query Java DB, we recommend to use the Data Source Explorer view in Eclipse. But any SQL client that can make use of JDBC drivers should be fine. The driver for Java DB can be found (at the time of this writing) in *$JAVA_HOME/db/lib/derbyclient.jar* (and similarly on Windows).

*Note:* If you have problems running Derby due to Security Exceptions, it may be necessary to update your security profile as described in http://stackoverflow.com/questions/21154400/unable-to-start-derby-database-from-netbeans-7-4 (and please make sure you have a good JAVA_HOME and PATH setting).

h2. Alternative: Using the DB-Worker Node Add-on (no separate RDBMS installation required)

you can also use the [[DB_Worker_Node_Add-on|DB Worker Node Add-on]] which runs Apache Derby RDBM as a regular z2 worker process, so you don't need to install any extra database software.

*How to augment the samples to use the DB Worker node?*

You have to add the DB Worker Node Add-on to your samples environment and tell the server to start the DB worker node beside the web worker. 

For this you can use the two files attached to this page:

* *"dbWorkerAddon.properties":http://redmine.z2-environment.net/attachments/download/62/dbWorkerAddon.properties* - points to the z2 component repository containing the DB Worker Node Add-on

* *"home.properties":http://redmine.z2-environment.net/attachments/download/63/home.properties* - a slightly changed _home layout_ that launches the DB worker in addition to the web worker

Just download these two files and put them under @.../install/z2-samples.XYZ/environment/@ - where @z2.samples.XYZ@ must be replaced by the concrete sample name like @z2-samples.spring-hibernate@