Introducing Open Anzo Semantic Application Server version 3.1.0

This document shows how to install 3.1.0 on several different databases. Please direct any questions to the OpenAnzo discussion group.

Requirements and Installation

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

Open Anzo 3.1.0 is a standalone executable server centered around the Equinox OSGi runtime. To get started download the Open Anzo 3.1.0 distribution package.

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

openanzo-3.1.0/startAnzo.bat

or

openanzo-3.1.0/start.sh

When startup is complete, you should see the message

osgi-> 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

Java 5

If you are running on Java 5, you need to edit

openanzo-3.1.0\configuration\config.ini

and change

org.openanzo.directory.3=plugins/dependencies

to 

org.openanzo.directory.3=plugins/dependencies,plugins/dependencies/java5

General Config

Running the Open Anzo 3.1.0 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.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\configuration\config

The first line of each file specifies the OSGi bundle to which the configuration applies, and should not be modified. WARNING: The properties in these configuration files are read only the first time the server is started. After that, the values are cached internally within the OSGI framework. For any configuration changes to take effect, you must flush the configuration cache as follows.

If you want to flush the old configuration completely, you need to delete the

openanzo-3.1.0\configuration\org.eclipse... directories

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\configuration\config\org.openanzo.SystemConfig.properties

The default file looks like this:

service.pid=org.openanzo.osgi.SystemConfig
org.openanzo.combus.port=61616
org.openanzo.combus.host=localhost
org.openanzo.services.user=sysadmin
org.openanzo.services.password=123
org.openanzo.ldap.ldapServerUser=uid=admin,ou=system
org.openanzo.ldap.ldapServerPassword=secret
org.openanzo.ldap.host=localhost
org.openanzo.ldap.port=10389

The first line should not be changed:

service.pid=org.openanzo.osgi.SystemConfig

This tells OSGI that this configuration file contains the SystemConfig data.

The next 2 lines tell the server on which port ActiveMQ should listen:

org.openanzo.combus.port=61616
org.openanzo.combus.host=localhost

The next 2 lines define the Open Anzo server's internal super/system admin user:

org.openanzo.services.user=sysadmin
org.openanzo.services.password=123

This user and password are specific to the Open Anzo server, and serve as the credentials which one can use to manage the server. These credentials are in no way tied to the operating system or the authentication source(ldap), but are defined here by the administrator of the server in order to have a set of credentials which one can use to manage the server.

The next 2 lines define the embedded ldap server's administrative credentials:

org.openanzo.ldap.ldapServerUser=uid=admin,ou=system
org.openanzo.ldap.ldapServerPassword=secret

Like the previous credentials, these credentials are internal to the embedded ldap server, and are defined here in order to provide a set of credentials which one can use to manage the embedded ldap server.

The next 2 lines define the embedded ldap server's listening port:

org.openanzo.ldap.host=localhost
org.openanzo.ldap.port=10389

This defines the port on which the embedded ldap server runs.

LDAP

The embedded LDAP server's initial data is in

openanzo-3.1.0\configuration\anzo.ldif

Logging

Open Anzo 3.1.0 uses a slf4j via log4j system adapted to OSGi. The initial log4j.properties file loaded into OSGI is

openanzo-3.1.0\configuration\config\log4j.properties

Databases

The database configuration properties are defined in

openanzo-3.1.0\configuration\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.0 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.

WARNING: When changing between different databases, you will need to delete the osgi configuration cache by deleting the

openanzo-3.1.0\configuration\org.eclipse... directories

H2

The default configuration uses a memory-backed H2 Java database. You can uncomment the first org.openanzo.database.url file in order to use a file-backed H2 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\scripts\db2\makeDb2Bundle.bat

or

openanzo-3.1.0\scripts\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:

1. 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
   

2. Run the db2setup.bat or db2setup.sh script found in the distribution in scripts/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
   

3. 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\scripts\buildBundles\oracle10g\makeOracleBundle10g.bat

or

openanzo-3.1.0\scripts\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=*

What has changed from previous versions of Open Anzo

In version 3.1.0, 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.

For the regular Open Anzo user, the shift to Open Anzo 3.1.0 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.1.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.0 concerns the Embedded Mode Anzo Client. In 3.1.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.0, 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.

Troubleshooting & FAQ

We're here to help.

My configuration changes aren't taking effect!

1. Stop the server
2. Delete the openanzo-3.1.0\configuration\org.eclipse.* directories
3. Start the server.

That should cause your configuration changes to take effect. Remember that the settings are cached the first time they are read. The only way currently to get configuration files re-read is to delete those directories.

java.lang.OutOfMemoryError

If the server is throwing java.lang.OutOfMemoryError exceptions you may need to increase maximum the heap size allocated to the server. You can give the server access to more memory by setting the ANZO_OPTS environment variable. For example, in Windows:

set ANZO_OPTS=-Xmx1024M

or in unix (bash-like shells):

export ANZO_OPTS=-Xmx1024M

If you are trying to send the server a very large data set, such as very large graphs, you should consider using the AnzoClient#importStatements functionality which is designed for adding large datasets to the server. If you are using the command line interface, then this functionality is available via the anzo import command.

Error: no 'server' JVM at C:\Program Files\Java\jre6\bin\server\jvm.dll

By default, the Open Anzo server passes the -server command line option to the JVM. If you only have a JRE installed rather than a full JDK, then you don't have support for the -server option. You should install the JDK and ensure that the JDK is in your PATH environment variable before the JRE. You can alternatively set the ANZO_OPTS environment variable to specify the -client option. However, we recommend that you run with the -server option for improved performance.