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. 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.

There are also open-source alternatives such as Kaffe - see this GNU page for more information.

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:

  • objectbox.jar

If you are using an older version of Java (eg 1.3) you will also need an XML parser and XSLT engine, for example (from Apache 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:

        -Dname                  set program parameter 'name' to true
        -Dname=value            set program parameter 'name' to 'value'
        -Sname                  set session parameter 'name' to true
        -Sname=value            set session parameter 'name' to 'value'
        -S                      create an empty program session
        -encoding charset       set output character encoding to 'charset'
        -noext                  do not load default language extensions
        -e classname            use language extension 'classname'
        -xsl                    post-process with XSLT engine
        -xml                    expect XML input
        -sml                    expect SML input
        -test                   run unit tests
        -compile                compile program without executing
        -xmldocs                generate DocBook XML documentation
        -htmldocs               generate HTML documentation
        -v                      be verbose
        -q                      be quiet
        -help (or -h)           print instructions and exit
        -version                print version details and exit

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 "ex:test" in the following program:



  <o:program xmlns:o="http://www.o-xml.org/lang/">
    <o:param name="ex:test" xmlns:ex="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 order for the ObjectBox to work as a servlet, you need to include the required jar-files in the WEB-INF/lib directory of you web application. You will also need to define the ObjectBox servlet in the web application descriptor file, WEB-INF/web.xml.

If you create your own web.xml file, it needs to include as a minimum the servlet definition and at least one mapping:



 <servlet>
  <servlet-name>ObjectBox</servlet-name>
  <servlet-class>org.oXML.extras.http.ObjectBoxServlet</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 o:XML compiler/interpreter. When receiving a request, the ObjectBox servlet will compile and execute the program. The output will then 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/. If the program takes an o:session parameter, this will be initiated with the current user session (cookie- or URL-rewriting-based).

Configuration

The Servlet configuration may include two optional parameters: logLevel and/or uploadDirectory. The first one sets the runtime log level to either debug, info, warning or error. Default is info.

The uploadDirectory parameter tells the ObjectBox Servlet where to save attachments that are received with multipart MIME requests.


 <servlet>
  <servlet-name>ObjectBox</servlet-name>
  <servlet-class>org.oXML.extras.http.ObjectBoxServlet</servlet-class>
 </servlet>
  <init-param>
    <param-name>logLevel</param-name>
    <param-value>debug</param-value>
  </init-param>
  <init-param>
    <param-name>uploadDirectory</param-name>
    <param-value>upload</param-value>
  </init-param>

Request Attachments

Attachments may be sent by browsers when submitting forms that contain file upload parameters. Such forms may be recognised by the encoding type multipart/form-data.

To access attachments you need to specify the s:req, or request object, parameter in your program. The attachments can then be retrieved by calling $s:req.getAttachment(name), where name is the corresponding form input parameter. If a form specifies more than one file parameter, they must have different parameter names.

Redirect, Forward and Error

The ObjectBox servlet handles several different types of program return values. Returning a value from a program is different from letting it terminate normally, and is generally only useful for handling specific circumstances such as errors or redirections.

By using the various types in the o:Lib servlet module as return values, you can control exactly the type and content of the response that is sent back to the client. The advantage of using return values over calling functions on the Servlet response object, is that you don't havie to declare any Servlet input parameters. This makes it easy to write web-application programs that can be tested directly from the command line, without having to deploy them to a Servlet engine.

To send a redirection response, simply return an instance of the s:Redirect type.


   <o:return select="s:Redirect('target.html')"/>

Instead of redirecting, the current request can be forwarded to a different handler. Forwarding doesn't generate a response, instead the responsibility of responding is delegated. Hence the client will not be aware of the URL or resource changing.

To create any other responses using the established HTTP response codes (see RFC2616 Section 10), instantiate a s:Response directly.


   <o:return select="s:Response(204)"/> <-- send a 204 No Content response -->

Errors don't generally contain a response body, instead one is created by the Servlet engine using the configured error pages. Errors can be created with an error code (in the 4xx or 5xx ranges) and an optional error description. If the error description is not given, the default is used - each error code has its own default description.


   <o:return select="s:Error(404, 'Not Found')"/> <-- send a 404 error response -->

The API documentation for the Servlet response library types is available here.

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="objectbox.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!

Example Programs

There are examples from the Programming Guide available on the o:XML download page.

You can also download a zip file with examples from the article Introducing o:XML, published on the O'Reilly website XML.com

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.