BocaSetup
From IBM Semantic Layered Research Platform
Contents |
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. The IBM JDK has the proper XML libraries included. If you are using Sun's, you must download a current XML parser, such as Xerces, and place it in the build path and classpath where needed (com.ibm.adtech.jastor and com.ibm.adtech.boca.standalone, respectively).
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 implemented for IBM DB2 and Apache Derby. Derby, while useful for client-side persistence performs poorly as the main RDF store. Thus, we discuss setting up Boca to run on DB2.
If DB2 V9 has not been installed, the first step is to download and install a version of DB2 9.1. DB2Setup describes how to download and install DB2 Express C, which is freely available.
Installing Boca from binaries
If the developer need not modify or trace through the source code of Boca, the binary distribution provides the fastest path to a running Boca instance. (Though, Eclipse users will find source installation just as straightforward if not easier.)
- Download boca-1.8.4-bin.zip
- Unpack the archive to a clean directory, c:\boca-1.8\ (we'll use this directory going forward, but you can pick whatever directory you'd like)
- Examine c:\boca-1.8\build.xml, and update the location of your DB2 Java libraries if necessary. If DB2 has not been installed revisit this step upon installation.
<property name="db2.java" value="C:/Program Files/IBM/SQLLIB/java" />
- Run the check-dependencies script (c:\boca-1.8\check-dependencies.bat or boca-18/check-dependencies.sh)
Note: The check-dependencies script downloads and unpacks several third-party libraries to c:\boca-1.8\download and places necessary jar files in c:\boca-1.8\lib At the time of the Boca 1.8 release, the locations of these libraries were known and tested. Of course, links can break and change. See the links section in c:\boca-1.8\build.xml. If you already have the dependencies downloaded or do not have faith in the Ant script, you can either place the downloaded packages in c:\boca-1.8\download, or copy the proper jars into c:\boca-1.8\lib\. The script looks for exact names so keep that in mind if you choose to prepare the libraries manually. - Boca is now installed and ready to run as soon as the database has been created and database settings have been configured.
Installing Boca from source
Eclipse is the only well supported (and highly recommended) method for compiling, modifying and running Boca from source. Presumably, an Eclipse developer will have several custom Eclipse projects that will make use of Boca. However, we recommend importing Boca into a clean workspace to get started. Eclipse Calisto (3.2) is recommended.
- Download boca-1.8.4-src.zip
- Unpack the archive to a clean directory, c:\boca-1.8-src\ (we'll use this directory going forward). c:\boca-1.8-src\ now contains several Eclipse projects that will be incomplete until after step 4.
- Examine c:\boca-1.8-src\requiredLibraries.xml, and update the location of your DB2 Java libraries if necessary. If DB2 has not been installed revisit this step upon installation.
<property name="db2.java" value="C:/Program Files/IBM/SQLLIB/java" />
- Run the insert-dependencies script (c:\boca-src-1.8\insert-dependencies.bat or c:\boca-1.8-src\insert-dependencies.sh)
Note: The insert-dependencies script downloads and unpacks several third-party libraries to c:\boca-1.8-src\download and c:\boca-1.8-src\lib. This script also copies the necessary jar files into the various Eclipse project folders. At the time of the Boca 1.8 release, the locations of these libraries were known and tested. Of course, links can break and change. See the links section in c:\boca-1.8-src\requiredLibraries.xml. If you already have the dependencies downloaded or do not have faith in the Ant script, you can either place the downloaded packages in c:\boca-1.8-src\download, or copy the proper jars into c:\boca-1.8-src\lib\. The script looks for exact names so keep that in mind if you choose to prepare the libraries manually. - With Eclipse running, select File->Switch Workspace, and choose c:\boca-src-1.8. This will create the necessary workspace .metadata folder in c:\boca-src-1.8. Next import the projects by selecting File->Import->General->Existing Projects Into Workspace. Point it to c:\boca-src-1.8. If all went well, the projects will show no build errors. (Note: if you encounter build errors and at least some of them refer to Xerces, make sure your eclipse workspace is configured to use the IBM jre, or that Xerces has been obtained and referenced).
- 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
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
- (binary) Change directory to c:\boca-1.8\dbscripts
- (source) Change directory to c:\boca-1.8-src\com.ibm.adtech.boca.model\doc
- Create the database. We'll call the database boca, but you can substitute that with any name of your choosing.
db2 create database boca automatic storage yes 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 our database:
com.ibm.boca.repository.database.driver=com.ibm.db2.jcc.DB2Driver 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
- (binary) The properties file to modify is c:\boca-1.8\BocaServer.properties.db2
- (source) The properties file to modify is c:\boca-1.8-src\com.ibm.adtech.boca.standalone\src\com\ibm\adtech\boca\standalone\BocaServer.properties.db2
For the source case, once you have modified BocaServer.properties.db2, copy the file to BocaServer.properties because this is what the server executable in the Eclipse project will use.
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.
(Optional) Boca Derby Configuration
Boca has been tested and will work with Apache Derby as its back-end database, but will not perform as well as using DB2. Derby has been tested in embedded mode, but not tests have been run with the Apache Derby network server driver.
- Modify Boca database server properties to connect to our database:
com.ibm.boca.repository.database.driver=org.apache.derby.jdbc.EmbeddedDriver com.ibm.boca.repository.database.user=boca com.ibm.boca.repository.database.password= com.ibm.boca.repository.database.url=jdbc:derby:<Path to database>;create=true;upgrade=true com.ibm.boca.repository.database.clear=false com.ibm.boca.repository.database.type=BocaDerby
- (binary) The properties file to modify is c:\boca-1.8\BocaServer.properties.db2
- (source) The properties file to modify is c:\boca-1.8-src\com.ibm.adtech.boca.standalone\src\com\ibm\adtech\boca\standalone\BocaServer.properties.db2
For the source case, once you have modified BocaServer.properties.db2, copy the file to BocaServer.properties because this is what the server executable in the Eclipse project will use.
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
binary
- Change directory to c:\boca-1.8\
- Run boca.bat or start.sh on Linux
source
- Right-click on com.ibm.adtech.boca.standalone.BocaStandalone in the Eclipse Package Explorer, and select Run as->Java Application
- If you receive an error dialog popup, do Run As->Run... Select the Classpath tab. Select com.ibm.adtech.boca.standalone under User Entries. Click the Edit button to the right. Make sure Only include exported entries is checked. Try the first step again...
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
- 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 ...
