From IBM Semantic Layered Research Platform

Contents 1 Introduction 2 Boca Installation 2.1 Installing Boca 3 Boca DB2 Configuration 4 Verifying the Boca installation 4.1 Starting Boca 4.2 Verify that Boca is running 4.3 Pitfalls

Introduction

The Boca server comprises two main infrastructure components: a relational database backend and a Boca server front end. The Boca client libraries enable Semantic Web client and web applications to interact with the Boca RDF database using a Jena Framework-style API with an extended programming model for named graphs, replication, notification and security. This document will describe in detail how to download, install and configure the Boca server, as well as how to configure a DB2 database backend, using the freely available version of DB2 Express C. We will also describe how to compile, run and modify the sample code, demonstrating proper use of the Boca client API.

Boca Installation

Before getting started, a Java 5 compatible JDK must be installed.

There is nothing fundamental within Boca's design that prohibits the use of any particular relational database. However, most databases have their own particulars, and Boca has been optimized and tested for IBM DB2 so we will be describe in detail the setup of Boca 2.x for DB2. Boca 2.x works with several other relational databases such as Derby,MySQL,Postgres, and HSQL. For details on those databases see BocaDatabaseSupport-2.x you can then skip the Boca DB2 Configuration section.

Installing Boca

In Boca-1.x distributions, we distinguished between source and binary distributions. In 2.x, we provide a single package based on Apache Maven. The developer must first download and install Maven. Installation is as easy as unpacking the tar or zip, and adding the <maven-dir>/bin folder to your path. The distribution file called boca-2.x-maven.zip(tar.gz) contains only the source code of Boca. The Maven build and packaging system automatically downloads all dependencies, and compiles the Boca binaries. It also prepares an additional zip/tar.gz that can deployed on the server or workstation where the Boca server is to be run.

Even though we no longer provide Eclipse projects for each of the Boca subcomponents as in 1.x, the Maven system may be used to provide an Eclipse project, see BocaEclipse-2.x.

We now provide step-by-step installation instructions.

1. Download boca-2.2.zip
2. Unpack the archive to a clean directory such as c:\boca-2.2-maven\ or /usr/local/src/boca-2.2-maven
3. Run the appropriate build script, build.bat or build.sh. This will invoke Maven and download a bunch of dependencies and compile Boca.
4. In boca-2.2-maven\target there should be two archives. Extract the appropriate archive to a location where you would like to deploy the server. In Windows, for example, extracting to c:\ will result in c:\boca-2.2\. We choose this example moving forward.
5. In an editor of your choice, open c:\boca-2.2\bin\boca.bat or boca-2.2/bin/start.sh as appropriate. Make sure BOCA_HOME and DB2_JAVA point to the proper path.
6. Boca is now installed and ready to run as soon as the database has been created and database settings have been configured.

Boca DB2 Configuration

If DB2 V9 has not been installed, the first step is to download and install a version of DB2 9.1. DB2 Express-C describes how to download and install DB2 Express C, which is freely available.

The Boca DB2 configuration process consists of creating a database, tweaking the database configuration with an included script, and modifying Boca configuration properties to connect to the new database. We detail the steps below. The binary and source distributions of Boca have slightly different DB2 configuration steps that we will note as we go along.

• Open a DB2 Commnad Window: Start->Program Files->IBM DB2->[copy]->Command Line Tools->Command Window
• Change directory to c:\boca-2.2\bin\db2
• Create the database. We'll call the database boca, but you can substitute that with any name of your choosing.

 db2 create database boca using codeset utf-8 territory US

• Run the database configuration script

 db2setup boca

or Linux

 chmod +x db2setup.sh
 ./db2setup.sh boca

• Test the database connection

 db2 connect to boca user <userfromdb2install>

• Terminate the connection

 db2 terminate

• Modify Boca database server properties to connect to your database:

 com.ibm.boca.repository.database.user=<userfromdb2install>
 com.ibm.boca.repository.database.password=<pwfromdb2install>
 com.ibm.boca.repository.database.url=jdbc:db2://localhost:50000/boca
 com.ibm.boca.repository.database.clear=false
 com.ibm.boca.repository.database.type=BocaDB2

• The properties file to modify is c:\boca-2.2\conf\BocaServer.properties.db2

Note: You may modify other properties such as the port on which Boca is listening (8080 by default) if necessary

• Boca is now properly configured to run against the database.

Verifying the Boca installation

Starting Boca

1. Change directory to c:\boca-2.2\bin
2. Run boca.bat or start.sh on Linux

Verify that Boca is running

Open a web browser to

   http://localhost:8080/validation

you should see the following output

   Fetching remote model....
   ...done
   Adding properties to model...
   ...done
   Committing transaction....
   ...done
   Replicating dataset...
   ...done
   All is well.

Pitfalls

- many errors may be printed to the console, but others might show up only in c:\boca-2.2\var\ log files.

- If you are using linux, and receives errors about end-of-line characters (^M), then you can use dos2unix to fix the .sh scripts.

- If you receive DB2 lock errors because the startup of Boca was halted or interrupted, you should drop the Boca database and start afresh:

 db2 drop database boca
 db2 create database boca using codeset utf-8 territory US
 ./db2setup.sh boca
 ...