Wiki Navigation

Introducing Open Anzo Semantic Application Server version 3.1
1. What has changed
Requirements and Installation
1. Configuration

Introducing Open Anzo Semantic Application Server version 3.1

This document outlines the practical differences between Open Anzo 3.0 and 3.1, and shows how to install 3.1 on several different databases. Please direct any questions to the OpenAnzo discussion group.

In version 3.1, we have moved Open Anzo from our temporary homegrown component framework (The Service Container), to the widely adopted and robust OSGi framework. OSGi provides not only a cleaner and more maintainable componentization, but also allows for greater scalability and the dynamic management of components. For example, new components such as Semantic Execution Services and Http Servlets may be added simply by injecting a self-describing OSGi bundle into the OSGi container.

What has changed

For the regular Open Anzo user, the shift to Open Anzo 3.1 requires very little change, and may be largely viewed as an implementation detail of the server. The API and programming model remain mostly fixed. The existing documents V3MigrationGuide and AnzoClientDesign are still the best references for developing applications, and the CommandLineInterface works the same way as in Open Anzo 3.0.

Instantiation of AnzoClient objects has changed slightly.

// prepare the configuration for the client
String username = "default";
String password = "123";
String host = "localhost";
int port = 61616;
// instantiate a anzo client
anzoClient = new AnzoClient(AnzoClientConfigurationFactory.createJMSConfiguration(username, password, host, port));
// connect the client
anzoClient.connect();

The most significant API change in 3.1 concerns the Embedded Mode Anzo Client. In 3.0, the embedded client communicated directly with the database layer, without any network messaging, and could be instantiated just like a JMS-based Anzo Client, though with different arguments. In 3.1, the Anzo OSGi container provides sophisticated pooling and management of AnzoClient objects to properly configured OSGi bundles running inside the container. For example, if you have a web-application whose Servlets and JSPs require AnzoClients to service requests, the container will provide pooled access to AnzoClient objects automatically, as long as the web application is configured as an OSGi bundle. For help on integrating your server-side Open Anzo application with the OSGi container, please contact the mailing list.

For those wanting to treat the Open Anzo Server as a black-box standalone server and have as little to do with OSGi as possible, Open Anzo-based client and web applications can still connect to the Open Anzo server from outside the OSGi container, but they must now do so via the JMS connection as shown above. The JMS layer has not proven to be a performance bottleneck, so we chose this clean design over allowing users to talk directly to the database outside of the OSGi container.

Requirements and Installation

The base requirement for running Open Anzo 3.1 is a Java Runtime 1.5 or higher. Open Anzo includes the Apache Felix OSGi runtime, as well as the relational database libraries for H2 and Postgresql. Running Open Anzo 3.1 atop additional databases has further requirements.

Open Anzo 3.1 is a standalone executable server centered around the Apache Felix OSGi runtime. To get started download the Open Anzo 3.1 distribution package.

Extract the package and basic installation is complete. To run the server, run

openanzo-3.1.0-SNAPSHOT/bin/startAnzo.bat

openanzo-3.1.0-SNAPSHOT/bin/start.sh

When startup is complete, you should see the message

Welcome to OpenAnzo running in Felix.
=========================================

-> All Currently Registered OpenAnzo services started.

You can see the status of the running OSGi bundles by visiting

http://localhost:8080/status

And you can check to see if the server is working by visiting

http://localhost:8080/validation

Configuration

Running the Open Anzo 3.1 server as directed above without modifying any configuration uses port 61616 for the Combus (JMS). It is also setup with two users in the embedded ldap server: the sysadmin user sysadmin pw:123 and a default user default pw:123. The RDB used is the H2 database. This configuration works well for prototyping and test, but more complex development and production systems will likely require additional users and a more robust database.

In Open Anzo 3.0, all configuration was performed through modifying a set of RDF files. In Open Anzo 3.1, base configuration needed to startup the system is done through properties files in a more OSGi-style fashion. The Open Anzo server comprises several OSGi bundles, each with their own configuration. However, most bundles have fixed configuration. The handful whose configuration is important, have configuration properties specified in

openanzo-3.1.0-SNAPSHOT\conf\config

The first line of each file specifies the OSGi bundle to which the configuration applies, and should not be modified. The properties in these configuration files are read only the first time the server is started. After that, the values are cached (as with any other files used by the OSGi bundles) in

openanzo-3.1.0-SNAPSHOT\conf\cache

To change the configuration property values without blowing away the cache directory (and any important state such as a file-backed H2 database), OSGi tooling must be used. Remember, this means that the files in conf\config won't be read again even across server restarts unless the conf\cache directory is removed.

Open Anzo 3.1 does provide a powerful RDF-based configuration mechanism called The Anzo Registry, but it is beyond the scope of this document, and is only useful when server-side applications are hosted with the OSGi container. Interested users should contact the mailing list.

Connectivity

The Combus (JMS) and LDAP hosts and ports, as well as the default system user are specified in

openanzo-3.1.0-SNAPSHOT\conf\config\org.openanzo.SystemConfig.properties

The user and password specified must be the administrative user and password.

LDAP

The embedded LDAP server's initial data is in

openanzo-3.1.0-SNAPSHOT\conf\anzo.ldif

Logging

Open Anzo 3.1 uses a log4j system adapted to OSGi. The log4j.properties file to use is

openanzo-3.1.0-SNAPSHOT\conf\config\log4j.properties

Databases

The database configuration properties are defined in

openanzo-3.1.0-SNAPSHOT\conf\config\org.openanzo.datasource.nodecentric.defaultDatasource.properties

Like any other component or dependency in OSGi, database drivers must be exposed to the container as an OSGi bundle. Open Anzo 3.1 includes OSGi bundles for H2 and Postgresql, as well as build scripts to create and install bundles for DB2 and Oracle. To run these scripts you must have Maven 2 installed and in your path.

H2

The default configuration uses a disk-backed H2 Java database. The location specified by the ${bundleLocation} is used to store the data under the working directory for the OSGi bundle, and managed by the OSGi container. This portion of the database URL may be modified to store the database elsewhere on disk, or in memory only. The memory-only store should be used only for the most rudimentary testing.

service.factoryPid=org.openanzo.datasource.nodecentric.Factory
org.openanzo.services.enabled=true
org.openanzo.services.instanceURI=http://openanzo.org/datasource/systemDatasource
org.openanzo.datasource.initFiles=resource:/org/openanzo/datasource/nodecentric/initialize.trig
org.openanzo.datasource.isPrimary=true
org.openanzo.database.password=
org.openanzo.database.user=sa
org.openanzo.database.type=ServerH2
org.openanzo.database.url=jdbc:h2:${bundleLocation}/databases/systemDB
#org.openanzo.database.url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1
org.openanzo.datasource.uriPatterns=*

Postgresql

To run with Postgresql, simply update the defaultDatasource properties as follows, and make sure to have created the database.

service.factoryPid=org.openanzo.datasource.nodecentric.Factory
org.openanzo.services.enabled=true
org.openanzo.services.instanceURI=http://openanzo.org/datasource/systemDatasource
org.openanzo.datasource.initFiles=resource:/org/openanzo/datasource/nodecentric/initialize.trig
org.openanzo.datasource.isPrimary=true
org.openanzo.database.password=<password>
org.openanzo.database.user=<user>
org.openanzo.database.type=ServerPostgres
org.openanzo.database.url=jdbc:postgresql:anzo
org.openanzo.datasource.uriPatterns=*

DB2

Because the DB2 JDBC libraries may only be distributed with DB2, we have provided a script to create and install an OSGi bundle using the libraries that come with an installed DB2 9 distribution. The script is

openanzo-3.1.0-SNAPSHOT\lib\buildBundles\db2\makeDb2Bundle.bat

openanzo-3.1.0-SNAPSHOT\lib\buildBundles\db2\makeDb2Bundle.sh

You may need to edit the script to point to the location of the DB2 libraries if you selected an alternate installation location for DB2. The script may generate some exceptions, but as long as the "Build Successful" message is returned by Maven, the script ran properly. You must of course update the defaultDatasource configuration as well.

service.factoryPid=org.openanzo.datasource.nodecentric.Factory
org.openanzo.services.enabled=true
org.openanzo.services.instanceURI=http://openanzo.org/datasource/systemDatasource
org.openanzo.datasource.initFiles=resource:/org/openanzo/datasource/nodecentric/initialize.trig
org.openanzo.datasource.isPrimary=true
org.openanzo.database.password=<password>
org.openanzo.database.user=<user>
org.openanzo.database.type=ServerDB2
org.openanzo.database.url=jdbc:db2://localhost:50000/anzo
org.openanzo.datasource.uriPatterns=*

Note that to create the database for use by Open Anzo, you should follow these steps:

Create a database for Open Anzo to use. One way to do that is to issue the following command from within a DB2 command window or logged into the DB2 instance id:
```
db2 create database anzo using codeset utf-8 territory US
```

Run the db2setup.bat or db2setup.sh script found in the distribution in bin/db2.

Windows: While in a DB2 command window
  db2setup.bat [database name] [database username]
  example: db2setup.bat anzo db2inst1

Linux/Unixes: While logged in as the instance owner
  db2setup.sh [database name]
  example: ./db2setup.sh anzo

Stop and restart the DB2 instance.
```
db2stop
db2start
```

Oracle

Because the Oracle JDBC libraries may only be distributed with Oracle, we have provided a script to create and install an OSGi bundle using the libraries that come with an installed Oracle 10g distribution. The script is

openanzo-3.1.0-SNAPSHOT\lib\buildBundles\oracle10g\makeOracleBundle10g.bat

openanzo-3.1.0-SNAPSHOT\lib\buildBundles\oracle10g\makeOracleBundle10g.sh

You may need to edit the script to point to the location of the Oracle libraries if you selected an alternate installation location for Oracle. You must of course update the defaultDatasource configuration as well.

service.factoryPid=org.openanzo.datasource.nodecentric.Factory
org.openanzo.services.enabled=true
org.openanzo.services.instanceURI=http://openanzo.org/datasource/systemDatasource
org.openanzo.datasource.initFiles=resource:/org/openanzo/datasource/nodecentric/initialize.trig
org.openanzo.datasource.isPrimary=true
org.openanzo.database.password=<password>
org.openanzo.database.user=<user>
org.openanzo.database.type=ServerOracle
org.openanzo.database.url=jdbc:oracle:thin:@localhost:1521
org.openanzo.datasource.uriPatterns=*

Download in other formats:

Plain Text

The Open Anzo Project

Semantic Application Middleware