de.infoasset.platform.documentation
Class RunTriciaDoc

java.lang.Object
  de.infoasset.platform.documentation.RunTriciaDoc

public class RunTriciaDoc
extends java.lang.Object

How to Run a Tricia Application?

Tricia can run in two quite different environments:

1. standalone in a production environment, and
2. in the Eclipse IDE as part of the development process.

The main difference between these two options is how the Java classpath is built, and how the JVM is started. In the first case, we use the Java Service Wrapper to specify the classpath and to invoke the JVM. For a more detailed description of how to run Tricia in a production environment see ProductionMode.

In the second case, we provide Eclipse run configurations as part of our repository (see http://agile.csc.ncsu.edu/SEMaterials/tutorials/eclipse/eclipse_tutorial_3.5 .html#section11_0).

Run Modes - Overview

Besides the basic classpath setup, there are some other differences in how Tricia behaves in these different modes. These differences are handled by the RunMode singleton, which can be accessed by the RunMode.INSTANCE() method.

There are three different subclasses of the abstract RunMode class, which are shown in this class diagram:

These run modes have the following characteristics.

Production Mode

As the name suggest, this run mode is used for productive Tricia instances. For details see ProductionMode.

Test Mode

Developers mostly run Tricia in this run mode. The main objective of the test mode is to make testing and debugging Tricia as easy as possible. In order to make it easy to reproduce certain system states exactly, in test mode the database is cleaned completely on startup and if a test case starts running.

Running in test mode is possible without an externally installed relational database, since Tricia comes with the lightweight in-memory database HSQLDB. The test mode can be started out-of-the-box without any local configuration necessary. See TestMode for more details.

Staging Mode

This mode is derived from the production mode, but is intended to be used by developers. Sometimes it is necesarry to reproduce the state of a productive Tricia instance for testing purposes. Therefore, in staging mode Tricia does not clean the database on startup, but runs still in the Eclipse IDE.

Starting Tricia

The entry point for starting Tricia is the class Main, which has a public static main method.

In each plugin (see PluginsDoc), there is a file called %PROJECT-NAME%-test.launch. This launch configuration can be started inside of Eclipse by right-clicking on it and then choosing Run As -> %PROJECT-NAME%-run. For developers this is the prefered way of running a Tricia instance. The same way Tricia can be started in debug mode (Debug As -> %PROJECT-NAME%-run). Doing so is a good idea since it runs nearly as fast and makes debugging and hot code swapping possible.

The run mode to be used is specified by the system property runMode. Starting Tricia in test mode is therefore specified by the VM argument -DrunMode=test. If no run mode is specified, Tricia starts in production mode.

Tricia XML Configuration

Each configuration of a Tricia instance consists of two parts:

1. configuration of the main infrastructure (e.g., database access, web server, core loggers, ...), and
2. configuration of the plugins.

All configuration information for Tricia is stored in XML files. The main configuration is stored in a file named configuration.xml.

Depending on the run mode, the configuration files are stored at different locations, as shown in this table:

	Test Mode	Production Mode	Staging Mode
Where is the main configuration.xml file loaded from?	%TRICIA_WORKSPACE%/toro/config/configuration.xml (*)	%TRICIA_WORKSPACE%/../../properties/configuration.xml (*)	%TRICIA_WORKSPACE%/properties/configuration-%PLUGIN_NAME%.xml
Which plugins are available?	all plugins on which the executed plugins depends, according to the Eclipse project dependency	as specified in configuration.xml	as specified in configuration-%PLUGIN_NAME%.xml
Where are the plugins configured?	%PLUGIN_FOLDER%/config/plugin-config.xml (*)	in configuration.xml	in configuration-%PLUGIN_NAME%.xml

As shown in the table above, in test mode the main configuration and the configuration of the plugins are separately stored, and will be combined together dynamically at runtime. The objective behind this solution is to have working plugin configurations checked in to our code repository.

Configurator

The XML configuration is changed using a tool called Configurator. The configurator is realized as a dynamic web application, which is started by executing Ant targets provided in the file /plugins/toro/build.xml . There are the following Ant targets for different configurations:

Target Name	Run Mode	Configuration File	Classes Lookup
configure test core	test	%TRICIA_WORKSPACE%/plugins/toro/config/configuration.xml	toro
configure test core - local	test	%TRICIA_WORKSPACE%/plugins/toro/config/configuration-local.xm	toro
configure test plugin	test	%TRICIA_WORKSPACE%/plugins/%PLUGIN_NAME%/config/plugin-config.xm	specific plugin
configure test plugin - local	test	%TRICIA_WORKSPACE%/plugins/%PLUGIN_NAME%/config/plugin-config-local.xm	specific plugin
configure staging	staging	%TRICIA_WORKSPACE%/properties/configuration.xm	all plugins

Each Ant target starts a web server on port 8088, and tries to start a browser on this port. If the browser cannot be started automatically, please go manually to the address printed on the console output, e.g.,

 [java] browsing URL http://localhost:8088?password=vfo036nqocww
 

The configurator shows a tree structure which corresponds to classes in the Java code, their properties, and their relationships:

The image shows a configuration with three configured plugins: toro, file, and wiki. The style property has the value jakob,jakobMenu.

If the root node Main is marked green (as in the example image), the configuration is valid. Otherwise some configuration data is missing and has to be provided to run Tricia.

After changing properties you can save your change by pressing the Save button. If you have started the configurator with an Ant target from inside your Eclipse IDE, you should terminate your configuration session by pressing the "Stop the Configurator" button in the browser window. This is necessary, since killing the process in the Eclipse console doesnt work property due to an Eclipse bug (see http://jira.codehaus.org/browse/JETTY-208).

Constructor Summary

RunTriciaDoc()

Method Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RunTriciaDoc

public RunTriciaDoc()