Sourceforge

Peruser "Standalone" Installation Guide

When first trying out peruser software, you will probably want to do a quick build and run some unit tests. You may also want to try running a few of your own SPARQL queries against your own RDF models. All of this can be done without any additional software; we call this running in "Standalone" mode. If you then choose to run peruser integrated into Cocoon, some additional setup is necessary, which you can read about in the Peruser Cocoon Setup Guide.

Platform Preliminaries

You will need to have JDK 1.5 installed (JDK 1.4 is not supported, and we have not yet tested with JDK 1.6).
You will need a reasonably current version of ant installed. We currently test using ant 1.6.5.
To use our ant wrapper BASH script, you will need to either

Run peruser on a Unix/Linux compatible platform (which includes Mac OS X)
Use a cygwin shell on Microsoft Windows.

If you are using Windows without cygwin, then you will need to create your own .bat file or type some fairly long ant command lines.

Perhaps we will offer a ".bat" script sometime soon, but we haven't done it yet.
As you will see, our wrapper script is very simple and it is easy to create your own version for whatever reason.

Download and Unpack Peruser

After reviewing the Peruser license and agreeing to its terms, you will download the most recent versions of two file archives:

peruser_XXX_src (.zip or .tar.gz)
peruser_XXX_lib (.zip or .tar.gz)

(Here "XXX" refers to the version number string embedded into the filenames).

We will assume that you unpack these two archives into a parent directory that we will call /peruser_work. So, now you have a directory hierarchy that looks like this:

/peruser_work
	/peruser_XXX_src
		/app
		/bin
		/conf
		/java
		/ant_build.xml
		/ant_test.xml
		/peruser_LICENSE.txt		
		/peruser_NOTICE.txt		
		/peruser_README.txt
		/run_ant.sh
	/peruser_XXX_lib
		/cocoon_stub
		/container_stub
		/local
		/main

Choose a Host/Config Name

Peruser allows you to maintain multiple build/runtime configurations within a single source directory tree. Each configuration has a name, which by convention is of the form "domain/host". These names are used only by the peruser ant wrapper script (run_ant.sh) to determine the pathway to two important resources:

Your shell environment variable script
Your customized ant properties

When you download the peruser, it is set-up for two "dummy" configurations to get you started, which are named as follows. (The paths are all relative to your peruser_XXX_src directory).

Configuration Name	Path to Environment Setup Shell Script	Path to Customized Ant Properties
yourdomain/yourhost1	conf/sh_env/yourdomain/yourhost1.sh	conf/ant_prop/yourdomain/yourhost1.prop
yourdomain/yourhost2	conf/sh_env/yourdomain/yourhost2.sh	conf/ant_prop/yourdomain/yourhost2.prop

You can create a new configuration by creating the directories and files you want to use under conf/sh_env/ and conf/ant_prop. You do not have to use a two-level directory structure: It can be one levelor three levels or whatever you like. You merely need to be sure to use the same relative location for the environment script and the ant properties. So, the following alternatives are each acceptable:

short	conf/sh_env/short.sh	conf/ant_prop/short.prop
a/long/config/path/for/whatever/reason	conf/sh_env/a/long/config/path/for/whatever/reason.sh	conf/ant_prop//a/long/config/path/for/whatever/reason.prop

In the rest of the documentation, we will assume your configuration name is "yourdomain/yourhost1".

Note: All of this rigamarole is used merely to define a consistent way to access a few environment variables and ant properties. Experienced developers will see quite quickly how to change this structure around to suit their environments (in Eclipse or whatever).

Set Shell Environment Variables

Three environment variables are usually set within your environment setup shell script. You may instead set these variables in some other place (e.g. in your ".bashenv" file), but the shell script file must still exist (it can be empty) if you ar going to use our ant wrapper script.

The three variables as they look on a typical Windows host using cygwin are as follows.

Variable Name	Example Value	Description
JAVA_HOME	/cygdrive/c/wapp/jdk_150u11	Unix file path to your JDK installation
ANT_HOME	/cygdrive/c/japp/ant_165	Unix file path to your "ant" installation
PATH	"$JAVA_HOME/bin:$ANT_HOME/bin:$PATH"	Unix command search path: Should include the JDK/bin and ant/bin directories.

So, your job is to configure conf/sh_env/yourdomain/yourhost1.sh so that it sets these variables properly. If they are already set properly in your shelll environment, then you can leave the file empty.

It should now also be clear that if you want to use a Windows ".bat" file, you will simply need to emulate these three settings in your windows environment (which you may do through the windows control panel, etc.).

Set Ant Configuration Properties

To get started with running in standalone mode, there is only one environment variable you must be sure to set correctly, which is for the location of the peruser_XXX_lib installation.

Variable Name	Example Value	Description
peruser.lib.dir	/peruser_work/peruser_XXX_lib	If you are running on Windows, this may be set using the windows directory path format. Ant is pretty smart about interpreting file paths, generally.

To see a comprehensive list of the other properties you can set in this file, have a look at Peruser Build/Install Properties.

Build Peruser

Now let's try a standalone build of the peruser code. Open a unix shell (or cygwin shell, or windows command prompt...) and go to the root of the peruser_XXX_src directory. Then try running the command shown below.

./run_ant.sh ant_test.xml yourdomain/yourhost -p

If you look at the contents of the run_ant.sh script, you will see that what it does is

Make sure that the script was passed at least 3 arguments, which are as follows. (If less than three args are passed, the script prints a help message and aborts).

The name of an ant file
The name of a "configuration" as discussed above
Additional arguments to ant, including a list of ant targets. The list of targets may be preceded by ant property definitions using the ant syntax: -Dproperty_name=property_value

Invoke bin/peruser_ant.sh, which

Reads in the environment variables (in this example, from conf/sh_env/yourdomain/yourhost.sh)
Invokes ant using the supplied arguments.

In the case of our command-line above, the ant command line executed will be:

ant -f ant_test.xml -propertyfile yourdomain/yourhost.prop -p

The "-p" argument tells ant to simply print the list of tasks that are defined in the specified build file. Ant should give you back a list that looks like this:

build-server
clean
clean-cocoon
clean-webapp
compile
config-cocoon-src
confirmed-directory-delete
deploy-cocoon
deploy-into-cocoon
deploy-peruser-cocoon
deploy-webapp
fix-permission
generate-java-constants
init
install-directory-safely
install-javadoc
invoke-class-main
javadoc
jena-db-cmd
jena-db-model-reload
jena-rdfcat
peruser-jar
test-peruser-Evaluator
test-peruser-ModelMachine
test-peruser-Projector
test-peruser-Selector
test-peruser-java

For details on all these tasks, you can review the Peruser Ant Tasks documentation.

Assuming that worked for you, now you're ready to actually try a build, as follows

ant -f ant_test.xml -propertyfile yourdomain/yourhost.prop clean build-server

This task should proceed to compile the peruser java code, and should run without any errors. If this process fails, something is wrong in your configuration or platform setup. Remember that you need to use JDK 1.5!

Run Unit Tests

Once you have successfully built the code, you can run some tests.

The first test to try is the selector test, which executes a simple SPARQL query, and dumps the results as XML on your console. Run it as follows

ant -f ant_test.xml -propertyfile yourdomain/yourhost.prop test-peruser-Selector

You should see some output like:

    [echo] Preparing to execute :
    [echo] ===============================
    [echo] invoke.class=net.peruser.test.module.selector.SelectorTest
    [echo] invoke.args=${invoke.args}
    [echo] basedir=/peruser_work/peruser_211_src
    [echo] peruser.standalone.log4jconfig=conf/standalone/log4j/log4j.properties
    [echo] ===============================
    [java] 00:22:22 INFO  SelectorTest         :: SPARQL Unit Test - inflating!
    [java] 00:22:24 DEBUG SelectorTest         :: <?xml version="1.0"?>
    [java] <sparql
    [java]     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    [java]     xmlns:xs="http://www.w3.org/2001/XMLSchema#"
    [java]     xmlns="http://www.w3.org/2005/sparql-results#" >
    [java]   <head>
    [java]     <variable name="slab"/>
    [java]     <variable name="muri"/>
    [java]   </head>
    [java]   <results>
    [java]     <result>
    [java]       <binding name="slab">
    [java]         <literal>Java</literal>
    [java]       </binding>
    [java]       <binding name="muri">
    [java]         <uri>http://software.freshmeat.net/browse/java</uri>
    [java]       </binding>
    [java]     </result>
    [java]     <result>
    [java]       <binding name="slab">
    [java]         <literal>Ruby</literal>
    [java]       </binding>
    [java]       <binding name="muri">
    [java]         <uri>http://software.freshmeat.net/browse/ruby</uri>
    [java]       </binding>
    [java]     </result>
    [java]     <result>
    [java]       <binding name="slab">
    [java]         <literal>XSLT</literal>
    [java]       </binding>
    [java]       <binding name="muri">
    [java]         <uri>http://software.freshmeat.net/browse/xslt</uri>
    [java]       </binding>
    [java]     </result>
    [java]   </results>
    [java] </sparql>

    [java] 00:22:24 INFO  SelectorTest         :: SPARQL Unit Test - deflating!

If that works, then you're all set. Congratulations! You're ready to read some more docs and start experimenting with the sofware.