Usage Instructions

Introduction

The ObjectBox is an o:XML compiler and interpreter which can run either standalone, as a Java Servlet delivering dynamic content over the web, or as an integrated component in an Ant build environment.

Requirements

To run the ObjectBox, you will need a JAXP compliant XML parser and XSL Transform Engine, such as Xerces and Xalan from Apache XML. ObjectBox now also uses Jakarta ORO Regular Expressions package. Follow the links below if you need to download these:

You will also need a copy of JDK or JRE version 1.3 or newer, available from ibm.com or java.sun.com.

If you are running JDK/JRE 1.4 or newer, Xalan and Xerces will already be part of your configuration.

Running the ObjectBox from the command line

If you are using Java version 1.4 or newer you can run the ObjectBox commandline utility by downloading a single file: objectbox.jar. The utility can then be started with a command of the form:

java -jar objectbox.jar [options...] file

Otherwise make sure that you have all the required jar files, including those supplied with the ObjectBox, present in your classpath. This usually means setting the environment variable CLASSPATH. As a minimum you will need:

  • obox.jar
  • xinclude.jar
  • tagbox-util.jar
  • jcup-rt.jar
  • jakarta-oro-2.0.7.jar

If you are using an older version of Java you will also need an XML parser and XSLT engine, for example (from Jakarta Xerces/Xalan projects):

  • xalan.jar
  • xml-apis.jar
  • xercesImpl.jar

Once you've set the classpath, go to the subdirectory containing the o:XML program you want to run. For example, to execute the User example program go to examples/user. Run the ObjectBox command line utility org.oXML.engine.ObjectBox with a command such as:

java org.oXML.engine.ObjectBox user.oml

The ObjectBox also accepts these optional arguments:

-e extension-class

use specified class as a language extension.

-Dname[=value]

set the variable name to true, or to value.

-encoding charset

set the output encoding to charset.

-xsl

perform XSLT post-processing.

-v

be verbose - outputs trace messages.

-q

be quiet - suppresses info and warning messages.

-h

help - print usage information.

To pass parameters to a program you first need to declare them in the program itself. Parameter names passed on the command line may include a namespace URI, which has to be enclosed in curly braces before the local part of the name. For example to set the parameter "s:test" in the following program:



  <o:program xmlns:o="http://www.o-xml.org/lang/">
    <o:param name="s:test" xmlns:s="urn:examples"/>
  ...
  </o:program>

You would need to pass the parameter as follows:

java org.oXML.engine.ObjectBox -D{urn:examples}test

Running the ObjectBox as a Java Servlet

In the distribution top directory, copy the jar files (same as for standalone execution) to the directory WEB-INF/lib.

Using the Java jar tool, create a zip-file called ObjectBox.war that includes the WEB-INF directory and any other o:XML program files or other files that you want to include in the web application.

For example, to create a web application containing this page and all example o:XML programs, go to the top of the ObjectBox directory (where this file is) and issue the command:

jar cf ObjectBox.war WEB-INF examples images docs css readme.html

Then copy ObjectBox.war to the webapps directory of a Java Servlet Container such as Jakarta Tomcat and start the servlet engine.

You should then be able to see this page at the configured URL of your servlet engine, eg .

If you create your own web.xml file, it needs to include as a minimum:



 <servlet>
  <servlet-name>ObjectBox</servlet-name>
  <servlet-class>org.oXML.extras.http.ObjectBox</servlet-class>
 </servlet>

 <servlet-mapping>
  <servlet-name>ObjectBox</servlet-name>
  <url-pattern>*.oml</url-pattern>
 </servlet-mapping>

The first section tells your Java Servlet Engine about the ObjectBox servlet, the second sets up a file name mapping so that all files ending with .oml will be processed by the compiler/interpreter. After compiling and executing the program, the output will be further processed by an XSL Transform Engine (such as Xalan) only if the result contains a valid xml-stylesheet Program Instruction (eg <?xml-stylesheet href="stylesheet.xsl" type="text/xsl"?>).

The ObjectBox servlet will automatically set any program parameters to the value of the corresponding HTTP request parameter, whenever possible. If defined in the program it will also set the three special variables s:req (request object), s:res (response object) and s:servlet (servlet instance object), where the prefix "s" corresponds to the o:XML servlet extension namespace: http://www.o-xml.com/servlet/.

Using the ObjectBox with Ant

There's an ObjectBox Ant task that will run one or several program files as part of an Ant buildfile. To use it, you need the same jar-files as when running the ObjectBox from the command line (with the exception of xalan.jar since the Ant task does not perform an XSL transformation).

In your buildfile, you first have to define the new task:



  <taskdef name="obox" classname="org.oXML.extras.ant.ObjectBoxTask"
           classpath="obox.jar, xinclude.jar, tagbox-util.jar, 
                      jcup-rt.jar, jakarta-oro-2.0.7.jar, xercesImpl.jar">
  </taskdef>

After the task has been defined, you can use it to convert a set of o:XML program files into output XML files. The program files are specified in an enclosed fileset.



    <obox suffix=".xml" destdir="build/output">
      <fileset dir="programs">
        <include name="**/*.oml"/>
      </fileset>
    </obox>

Both suffix and destdir are optional parameters. suffix determines the filename of the output file, the default is .xml. The destdir parameter says where to put the output files, if not set they will end up where the program files are.

With the above given example, the ObjectBox will process all files ending with .oml anywhere under the programs directory. The results will be stored as separate xml files in the directory build/output.

To pass parameters to the program(s) you can use nested param elements. Other allowed nested elements are extension, for specifying language extensions, and classpath. There is also an optional attribute loglevel for setting the log verbosity level, its value must be either debug, info, warning or error. A full example follows:



    <obox loglevel="debug">
      <fileset dir="programs" includes="sort.oml"/> 
      <extension name="org.oXML.extras.java.JavaExtensions"/>
      <extension name="org.oXML.extras.db.DatabaseExtensions"/>
      <classpath location="extensions.jar"/>
      <classpath refid="lib.path"/>
      <param name="dir" value="${src.dir}"/>
    </obox>

This type of processing can be very effective in conjunction with an XSLT task to produce dynamically created, presentation-independent information. For example, the o:XML web site is automatically created by an Ant build script, using a combination of plain DocBook xml files and o:XML programs that generate DocBook output. These are then turned into both HTML and PDF output by applying different XSL stylesheets.

Running the ObjectBox as a BSF Engine

To Be Done

Troubleshooting

Some of the example programs, including the Eight Queens Problem and the servlet Snoop program, require a servlet context to run and will fail to execute from the command line.

If you get DOM related (typically MethodNotFound) exceptions you've probably got DOM level 1 interfaces in your system or user classpath. Make sure that xml-apis.jar is before any other XML jars in your classpath, or remove the conflicting jar from your Java system lib directory.