All the relevant settings for an OGEMA system are provided in so-called run directories. The framework is also started from a run directory, using the OGEMA launcher. A typical run directory is included in the OGEMA demokit (folder default), and in order to create your own start configuration, we strongly recommend to start from the default one and modify it. If you downloaded the OGEMA sources, you will still need the demokit, in order to get a run directory with the launcher included.
This page describes the different aspects related to the run directories and explains what the different files are for and how they can be configured.
Running the OGEMA-2.0 Demokit
- Java 7 or higher
- You've downloaded the demokit
Go to the demokit rundirectory. I you're using a bash compatible shell execute the following command to start OGEMA:
In the case that you're in a windows shell execute
Typically, you will want to add some start parameters (see Section "Start options" below). For development purposes, it is often useful to do a clean start, for instance, and if you have downloaded/built all required bundles already, you may use the -offline option to accelarate the start up process. The command could then read
The scripts start_security.sh and start_security.cmd will run the demokit with security enabled (see below). Note that in a (non-secure) clean start, the OGEMA launcher will try to locate the newest version of a bundle by browsing your local Maven repository and, if you do not provide the "-o" or "--offline" option, additional online repositories (OGEMA artifactory and Maven central). This functionality can be disabled via the "-uro" or "--use-rundir-only" option.
It is also possible to start the demokit manually, the basic command is:
For a list of optional parameters execute the ogema-launcher with '-?' or '–help' parameter:
The demokit rundir comes with a set of start scripts that are configured to enable Java/OSGi/OGEMA security. If you do a clean start with security enabled, the Maven mechanism to locate the bundles will not be used. Instead, the loader will only search in the directory referenced in config/config.xml for a bundle, which is typically of the form bin/apps. For example, if your config.xml file contains an entry
then the launcher will look for the file <RUNDIR>/bin/apps/org.ogema.apps.device-configurator-2.1.1-SNAPSHOT.jar. It is possible to update the files located in the bin-folders by running the start script with the "-b" or "--build" option. This will not start the framework, but simply copies all bundle jars to their respective bin-folder.
If you want to use only the bin-files in a non-secure start, provide the "-uro" or "--use-rundir-only" option.
The start options can be added to the java command:
- -?, or --help: Print an overview of available options.
- -clean: clean start, or factory reset, of the framework; the list of bundles to be loaded is read from the config/config.xml file, all existing resources are deleted. This option is recommended for development purposes and the first start of the system, but must be switched off in operation.
- -o, or -offline: the launcher will not try to update the Maven bundles from an Internet repository, such as Maven central or the OGEMA artifactory. May accelarate the start up processs when starting in clean mode, or using -ub.
- -ub, or --update-bundles: when starting in unclean mode, the launcher will try to update the loaded bundles, if newer versions are available. (Note: starts using the -ub flag are currently unstable; it is recommended not to use this option in a productive system)
- -v, or --verbose: print additional log messages
- -b, or --build: do not actually start the framework, but create a self-contained executable version of the rundir. In particular, this copies all bundles jar-files to the subfolder of RUNDIR/bin specified in the config.xml file, and creates a .zip-file of the rundir. In the following, the framework can be started using the -uro or -security option (see below), without the need to access some Maven repository for the bundles. The zip-file can be deployed to some embedded hardware, and run there, typically again with the -uro or -security option.
- -uro, or --use-rundir-only: when used in clean mode, or with the update-bundles option, the launcher will not search for the Maven bundles in one of the Maven repositories (local, Maven central, or the OGEMA artifactory), but use the jar files provided in the bin folder of the rundir. This requires a start using the -build option first.
- -security: activate OGEMA security. This requires a start using the -build option first. Implies the use-rundir-only option, as well.
- -sl, or --startlevel: Set the maximum start level. Bundles with lower start level will not be activated. If not set, the highest start level of all bundles will be set as framework startlevel, so that all bundles are activated.
- -s, or --strict: Start in strict mode. The launcher will throw an exception when an error occurs, whereas normally it would simply log an error message and try to recover. This is meant as a development tool, do not enable in production mode.
- -dp, or --deployment-package: create a jar-file containing all bundles from the start configuration, and a corresponding manifest file, according to the OSGi DeploymentAdmin specification (see DeploymentPackage).
- -cfg, or --config: specify the path of the config file, if it is not in the default location (config/config.xml)
- -p, or --properties: specify the path of the properties file , if it is not in the default location (config/ogema.properties)
Furthermore, standard Java options can be provided, such as
- -Xmx512m (example): specify the maximum RAM for the Java process. Here: 512MB.
Contents of the Run Directory
- /config : Configuration setup for the OGEMA framework
- /bin : Target location for deployable version plus non-maven dependencies should be pretty emtpy by default.
- /scripts : Various scripts helping to do things, e.g. sending REST requests to the running framework.
- /data : System data that are collected during OGEMA runtime. This includes the database with the resource graph, log messages and log data.
Details of these directories and the files found therein are provided below.
Add and remove components from the start configuration: config/config.xml
This file contains information about the framework components and applications (OSGi bundles) that are started when running OGEMA. If you want to add or remove an application from your start configuration, simply edit this file. For instance, in order not to start the simulated freezer application, locate the row
or similar, in config.xml, and comment it out:
On the next (clean) start of the framework, the freezer will not be loaded. Note that by default the framework starts unclean, in which case changes to the config.xml are ignored. See below for an explanation.
In addition, the config file governs a set of additional configurations, such as the port of the web server to be used.
The scheme can be found at https://www.ogema-source.net/config-1.2.1.xsd and defines the following elements and attributes:
- configuration (the root element) -> no attributes
- bundles -> no attributes
- bundle -> dir (relative path to the bundle), file (file name of the bundle), groupId (maven group id), artifactId (maven artifact id), version (maven version), start (if the bundle should be started) and startLevel (OSGi start level)
- properties -> no attributes
- property -> key, value
- bundles -> no attributes
The attributes for the property element are both required. For the bundle attributes either groupId, artifactId and version are required or at least the file attribute is needed (so that the launcher can locate the bundle)
.xml Example - ogema-launcher-1.2.1 and newer
To start OGEMA within Eclipse it is necessary to import the demokit rundirectory and the run configuration project "OgemaRunnerEclipse" (both are included in the demokit):
- Create a new project that is used to import the demokit rundirectory.
- Now import the rundirectory by right clicking the newly created project and browsing to the demokit rundirectory path (directory name: 'default').
- Afterwards import another project but this time choose "Existing Projects into Workspace".
- Finally you can start OGEMA now by selecting an appropriate run configuration:
Alternatively you can create your own run configuration as follows:
- Create a new run configuration (Run-> Run Configurations) for a 'Java Application'
- On the Main tab, enter a name and the main class (
org.ogema.launcher.OgemaLauncher). Selecting a project is optional.
- On the Arguments tab set the launcher arguments and more importantly its working directory (select File System and then browse to the demokit rundirectory - that folder in which the launcher is located). For a first-time run, also add the argument -clean to the program arguments.
- On the Classpath tab, nally, add the ogema-launcher jar to the classpath (using the "Add External JARs" button):
- Give the run configuration a proper name (e.g. run OGEMA) and click Apply.
Additional parameters can be passed via properties, which are read and parsed by Java, OSGi, OGEMA, or the applications that read and understand them. Properties can be passed via the properties entry in the config.xml file and/or by passing an additional file containing the properties to the OGEMA Launcher with the "-p" parameter. The common name for the file containing the properties read by the OGEMA framework is "config/ogema.properties". Refer to the List of OGEMA properties for a complete list of properties understood by the OGEMA framework.
Configuring the Logger (OGEMA 2.0)
The OGEMA 2.0 reference implementation internally uses logback for its logging system. The rundirectories provided with OGEMA systems contain a file loglevel.properties in the config subdirectory which configures the default verboseness of the loggers, which looks something like the following code:
The key of the properties is the full class name of the application's main class (the one implementing the Application interface), possible values are trace, debug, info, warn, error and none.
The log configuration is seperated in three parts:
- Console logging
- File logging
You can define the pattern for every part, or you can define a single property valid for all types. Wildcards can be used, such as "org.ogema.*=error,info,info" in the example above. However, exceptions to wildcard rules must not contain any wildcard; the line
would not have any effect, if it appeared after the more generic rule for "org.ogema.*". By specifying the full class name, exceptions to wildcard rules can be defined, however.
To switch off a particular logger use
in loglevels.properties, replacing 'org.apache.wicket.*' by the appropriate identifier.
Working with the Project Directories
Creating a deployable ZIP
The launcher can be used to create ZIP files containing all required files in one bundle that can be copied to a target machine and unzipped there. This allows to run OGEMA on systems that do not contain a Maven environment. To create such a ZIP file, call the launcher with
java -jar <name of the launcher JAR> -b
java -jar <name of the launcher JAR> --build
The launcher will be contained in the ZIP file. After unzipping the file on the target machine invoke the launcher with
java -jar <name of the launcher JAR> -uro
java -jar <name of the launcher JAR> --use-rundir-only
The option "--use-rundir-only" will cause the system to use the JAR-files contained in the ZIP, rather than searching Maven repositories for them.
OGEMA-Launcher Help Output
For further details there is a help output which can be printed by adding -? or --help:
java -jar <name of the launcher JAR> -?
java -jar <name of the launcher JAR> --help