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.
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.
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:
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):
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 exitTo 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
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).
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>
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.
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.
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.
To Be Done!
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
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.