Setting up the CopperCore runtime

This documentation is outdated and will be updated.

Introduction

This manual describes how CopperCore can be setup from scratch. The manual is intended for expert users who require a different configuration as provided trough the supplied CopperCore RunTime (CCRT). The CCRT may be a good starting point when modifying the setup of CopperCore.

CopperCore currently provides a number of components that can be deployed on a J2EE compliant application server. However not all components are necessary for all purposes. The following components are provided:

Component	Description	Req
CopperCore Kernel	This is the kernel application containing all code necessary for processing an IMS Learning Design level A, B or C.	X
Publisher	A servlet providing a primitive web interface for the validation and publication of IMS LD packages.	O
Clicc	A command line user interface allowing the execution of various types of administrative tasks.	O
WebPlayer	An primitive version of an web interface for the run time delivery of a IMS Learning Design. Currently the WebPlayer works only in Microsoft Internet Explorer.	O
CopperCoreSoap	A W3C SOAP compliant layer on top of the CopperCore kernel allowing applications to communicate with the CopperCore kernel through the SOAP protocol over HTTP.	O

Requirements

This list below gives the prerequisites for CopperCore. The list only contains components that have been tested with CopperCore. Although other versions may work as well, they have not been tested.

OS: Windows 2000/XP or Linux

Java JDK: Sun Java J2SE SDK 1.4.x.

DBMS: Microsoft SQL Server 2000/MSDE 2000
PostgreSQL 7.3
HSQLDB 1.7.2
Apache Derby (aka IBM Cloudscape)

JDBC: Microsoft SQL Server 2000 JDBC driver
PostgreSQL 7.3 JDBC driver
The JDBC driver for the HSQL DBMS and for Apache Derby is integrated with the database.

Components: The java UUID generator 1.0.3
The Jakarta file upload library

SOAP The AXIS 1.1 SOAP toolkit for Java

App. Server: JBoss 3.2.6

Compilation of the Code

Download the CopperCore source files from SourceForge. The sources are split over two different packages. The first is coppercore_sources which contains all sources required to build the kernel, WebPlayer, Publisher and Clicc. The second package is coppercore-soap_sources and contains all sources necessary for building the SOAP interface layer. You only need to use the soap package if you want to CopperCore to be accessible via the SOAP protocol.

Unzip the packages to a directory. They both contain a build.bat for Windows and build.sh for Linux allowing the build of the software. These files should be modified in such a way that all references to the required libraries are correct for your situation. In order to build the files with these scripts you will need to have Ant installed (http://ant.apache.org/) on your machine. The outcome of the build process should be:

coppercore.jar, being the kernel module.
coppercore.sar, contains JBoss specific timer scheduler.
coppercore-client.jar, contains the client api library. It also includes Clicc, the command line tool for CopperCore.
coppercore-common.jar, contains utility classes shared by the different components of CopperCore.
publisher.war, containing the servlet providing an interface for publishing and validating an IMS LD package.
webplayer.war, containing the example run time delivery interface for CopperCore.
coppercore.ear, containing the sx packages listed above for easy deployment on the application server.
coppercore-soap.war, containing the SOAP interfaces for CopperCore.

Note that you will have to compile CopperCore first before compiling CopperCoreSoap.

Setup JBoss 3.2.6

Start by downloading JBoss from http://www.jboss.org. Install JBoss by simply unzipping the distribution. All the downloaded libraries should be put on the class path when launching the JBoss application server. This can either be achieved by copying the required libraries into the lib directory of your deployment directory or alternatively modifying the class path to include the downloaded libraries when launching the run.bat or run.sh. This can be done in a separate batch or script which in turn launches the run.bat or run.sh respectively. See the CCRT for an example.

Setting up coppercore.properties

CopperCore uses a common properties file for all components for configuration of the environment. The following table contains the entries of this file.

webroot	Contains the file location of the web server root used for storing regular web content. The default web server shipped with Tomcat may be used for this purpose. A typical value would be: <JBoss-server>/server/default/deploy/jbossweb-tomcat50.sar/ROOT.war
schemalocation*	The location where CopperCore may find the schemas needed for parsing the IMS LD packages. The schemas can be found in the schemas directory of the CopperCore download.
contenturioffset	The URL offset to be used when serving the regular web content. This offset will be put in front of every URI referenced in the IMS LD package. An example is http://localhost:8080
uploadlocation*	The file location were uploaded IMS LD packages will be stored for publication.
filepropertyuploadlocation*	The file location were uploaded user file will be stored.
smtphost	The hostname of the SMTP server to be used.
smtpport	The SMPT port to be used (normally this is 25).

Note: make sure this coppercore.properties file can be found in the class path.

* If you don’t want to work with absolute paths, it is possible to use relative paths and pass CopperCore a directive to put an offset in front of all file paths. This can be done by launching the JBoss environment or Clicc with the following additional parameter:

-Dcoppercore.prefix=<offset to directory>.

An example of the coppercore.properties file can be found in the root of the CCRT package. In CCRT the directory of the batch/script file is used as offset for all relative file references. This allows the complete installation to be moved to another directory without having to change the setup.

Logging

CopperCore will log errors and warning via log4j. If nothing special is done, the output of this logging will be redirected to the stdout. In order to generate daily log files, the log4j.properties of JBoss needs to be adopted. An example of such adopted file can be found in the CopperCore/deploy directory. This file may be copied to the <jboss-root>/server/default/conf replacing the original logging configuration. Please look at the Log4j documentation for other configurations.

Deployment

The next step involves deploying the build files. To deploy CopperCore copy coppercore.ear to <jboss-root>/server/default/deploy. If you also want to install the soap interface, copy coppercore-soap.war to the same directory and copy coppercore-client.jar and coppercore-common.jar to <jboss-root>/server/default/lib.

Database setup

CopperCore uses a relational DBMS for persisting state of the IMS Learning Design for each user during delivery. Momentary there is support for four DBMSs, Microsoft SQL server, PostgreSQL, Apache Derby (IBM Cloudscape) and HSQL. Which database you choose is entirely up to you and depends on your needs, platforms and availability of licenses. Note that all but Microsoft SQL Server are open source developments and no special licenses are required. CCRT uses the HSQL database as this one integrates seamlessly with the JBoss application server. However it has drawbacks with regards to robustness and scalability.

Setup for PostgreSQL 7.3

PostgreSQL is distributed as open source and can be downloaded from http://www.postgresql.org. The installation of PostgreSQL itself is out of scope for this document. After you have installed PostgreSQL make sure that TCP/IP connections are allowed. This is achieved by modifying the postgresql.conf file (typically found at /var/lib/pgsql/data when using SUSE). The configuration file should contain the following line: tcpip_socket = true

If JBoss and PostgreSQL are installed on different computers you must modify the pg_hba.conf so the right access permission are granted. The next step is creating the database needed for CopperCore. The database script required for PostgreSQL can be found in the database/PostgreSQL directory of CopperCore

Proceed with the following steps to install the database:

Start a shell under the ‘postgres’ user account. We will assume that postgres: is the user account under which PostgreSQL was installed.
linux: /# su - postgres
Start PostgreSQL.
postgres@linux:~> pg_ctl start -D <path to data directory>
The next step involves creating a database user for CopperCore. We will use the user java. Please define your own account and remember it and its password as we need it when setting up JBoss:
postgres@linux:~> createuser -d -A -P java
Create a unicode database with the name ld_publication using the user created in the previous step as owner of the database.
postgres@linux:~> createdb -U java -E UNICODE -D <path to data directory> ld_publication
Start the PostgreSQL command line utility for the created user.
postgres@linux:~> psql -U java -d ld_publication
Create the database structures by executing the ld_publication_postgres.sql script that can be found in the CopperCore_1.0.zip/CopperCore/database folder.
ld_publication=> \i <path>/ld_publication_postgres.sql

The database is now installed. Next download the JDBC driver for PostgreSQL. This driver can be found at http://jdbc.postgresql.org/. Store the driver somewhere on the same computer where you want to install JBoss. It will be one of the parameters provided to JBoss.

In order to make the database available for CopperCore the JDNI name Publication has to be bound to the database. For this purpose you must copy the the postgres-ds.xml, in the following directory: <jboss root>/server/default/deploy. If you have modified the user id or password in the previous steps you must modify this file accordingly.

Setup for Microsoft SQL Server 2000/MSDE 2000

CopperCore supports Microsoft SQL Server 2000. You can either acquire a copy or download the free MSDE product. The latter may be downloaded from http://www.microsoft.com/sql/msde. Make sure that TCP/IP connectivity is installed and that SQL Server authentication is enabled. For details see the installation manual of the product. Make sure the database is running before proceeding with the next step. The database script required for PostgreSQL can be found in the database/MSSQL directory of CopperCore

To create the database, proceed with the following steps:

1. Modify the ld_publication_mssql.sql script as follows that is provided in the CopperCore_1.0.zip/CopperCore/database folder:
- modify the paths of the database and log file in the create database statement to reflect your situation.
- Optionally change the user id and password of the CopperCore database user (‘java’, ‘java’). You will need the user id and password when setting up the database connection in JBoss.

Locate the osql.exe which was part of the SQL Server installation. Run the script by entering the following command:
C:\Program Files\Microsoft SQL Server\80\Tools\Binn >osql -i c:\ld_publication_mssql.sql -U sa

The database is now installed and ready to use. Next install the JDBC driver for Microsoft SQL Server 2000 on the same computer where you want to install JBoss. It can be downloaded from Microsoft at http://www.microsoft.com/sql/. The driver comes with an installer. Remember the path where the driver was installed as it is one of the parameters for JBoss start script.

In order to make the database available for CopperCore the JDNI name Publication has to be bound to the database. For this purpose you must copy the the mssql-ds.xml, in the following directory: <jboss root>/server/default/deploy. If you have modified the user id or password in the previous steps you must modify this file accordingly.

Setup for HSQL

HSQL is the DBMS that is provided with JBoss, It therefore integrates with the least effort and is used in CCRT. The following steps describe how the JBoss HSQL environment should be modified so it can be used by CopperCore. These modifications are included by courtesy of Paul Sharples of the Reload Project http://www.reload.ac.uk/.. We assume that JBoss has been downloaded and installed. The required additional resource can be found in the database/HSQL directory of CopperCore.

Copy hsql-mbean-lib.jar from the database directory in CopperCore to the lib directory to <jboss-root>/server/default/lib.
Copy the Publication directory into <jboss-root>/server/default/data. The file Publication.script contains the user id and password for accessing the database.

In order to make the database available for CopperCore the JDNI name Publication has to be bound to the database. For this purpose you must copy the hsql-ds.xml, in the following directory: <jboss root>/server/default/deploy. If you have modified the user id or password in the previous steps you must modify this file accordingly.

Applications

After the CopperCore has been set up and the JBoss application server has been launched you can start the applications provided with CopperCore.

Clicc

The Command Line Interface for CopperCore is a command line tool that allows the execution of the administrative tasks. Clicc is included in the coppercore-client.jar. Clicc requires quit a number of libraries and it therefore best to modify the clicc.bat or clicc.sh in the root of CCRT for this installation.

Clicc commands correspond almost one-to-one with the API call provided through the LDCourseManagerDelegate and the LDEngineDelegate. Clicc can also be very useful for debugging purposes, when you incorporate CopperCore in your own environment.

Publisher

The publisher is a primitive web interface on the publication and validation process. It can be called by entering the following URL: http://localhost:8080/Publisher/publication.html

WebPlayer

The WebPlayer application is a primitive interface for the runtime delivery of IMS LD Packages. Currently the WebPlayer application will only run with Microsoft Internet Explorer. The webplayer may be started with: http://localhost:8080/WebPlayer/runswitch.html