Using RefleX

RefleX runs in a JVM. You must have Java installed in your system.

RefleX consist on a single jar file distibuted with other libraries. Alongside RefleX you will find another jar file for the 2 applications XUnit and WUnit.

RefleX is accessible from the command line interface, can be embedded in an application, or is also runnable as a servlet in a Web application (see hereafter). According to the running environment (command line, Web server) you have to make the relevant jar files accessible to that environment (with the classpath, on inside the WEB-INF/lib/ directory of your Web applications).

You don't need to write any Java code if you use the command line interface or the servlet, unless otherwise you want to design yourself your own module in Java, or interact with the engine. See "How-To" if you have to. Note that custom modules can also be defined without Java, but as macros (that is to say that a custom implementation can be made with active XML tags rather than with Java code).

Download

RefleX can be downloaded at INRIA's gforge.

DownloadDescriptionPlatform
Full binary release (zip) This is the main binary distribution which contains RefleX and all additional third party libraries (see dependencies). Full documentation (including tutorials) + Javadoc + the XUnit and WUnit applications. All
  • Works on Java 1.4.2 and higher
  • Works on Tomcat 5.0.28 and higher if you use servlets.
According to what you intend to achieve with RefleX, Some of third-party tools might expect a higher version of Java. See "dependencies".
Minimal binary release (zip) This is the minimal binary distribution which contains RefleX and only the third party libraries that are required (see dependencies). No documentation is provided in this pack.
Light binary release (jar) Contains only reflex-0.4.0.jar without third party libraries. This distribution is not runnable alone, it should be used for minor upgrades, or if you intend to install the required third party libraries independantly. Check what has changed.
XUnit and WUnit applications (jar) Contains only xunit-0.4.0.jar for XML testing purpose and testing of Web applications. XUnit can be run with the minimal binary distribution. WUnit can be run with the minimal binary distribution and with additional libraries that you have to get separately (you can use XUnit without WUnit).
Source release (zip) Only the Java source + the build file (without the libraries). To unzip in the same directory that the full binary release if you intend to rebuild RefleX.
SVN repository The Subversion repository to checkout.

Older and new releases can be accessed online here.

Status

This version of RefleX is 0.4.0-beta. The engine is much more reliable than in the previous version. Complex scenarii are well-tested with XUnit and since v0.3.1 with WUnit. Web applications of the tutorial section are now part of the test suite of the engine. Please refer to the Active Test section.

See also what has been changed since the previous release. New beta versions will be released as soon as they become ready. See also the roadmap.

Why is it a beta version ?

RefleX can be used safely in production.

Although the current version is under a beta status, INRIA already uses it in production for a strategic project (which is not a research project but an operational project). The core engine is very reliable because it is built upon itself, thus improving its own basic features. However, the entire spectrum that Active Tags and RefleX -this Java implementation- whishes to cover has not yet been covered entirely. There are still some design points not yet stable and some pieces of this implementation not yet well realized. That's why RefleX is currently under a beta status. Particularly, there are some expected features that are not yet available :

  • there is no logger neither means to trace,
  • there are not enough unit tests,
  • active tags are not checked while unmarshalling, so if the user make a mistake, at best a Java exception will be thrown, at worst a bad result will be get silently,
  • some active tags are simply not yet implemented ; it is also possible to encounter active tags that are not producing the effect described in the relevant specification (in this case, the Javadoc may help).
  • some dirty stack trace may occurs ; usually you can ignore them.
  • etc

Users that would like to use RefleX in their project should be aware that as long as the Active Tags specifications are under a working draft status, things may still evolve ; users should rely only on active tags intensively tested. By keeping in mind these precautions, everything should be allright ! Just remember that there are features on which your application can rely on, and features that are not achieved or experimental.

Limitations

  • Pipelines and filters :
    • A filter can't be plugged to multiple output channels with a DOM input ; use SAX instead (it's easy to "cast" a DOM document to a SAX document).
  • Active Catalogs :
    • Partially implemented, but the core machinery works.
    • Circularity on catalogs is not checked.
  • Schemata :
    • Only Active Schema is (partially) supported. Consider Active Schema as experimental as it is not trivial to get an error report.
    • Other schemata (W3C XML Schema, Relax NG, etc) are supported if the underlying XML parser support it ; please refer to the documentation of your parser.
    • W3C XML datatypes can be used from an Active Schema, but some are not yet implemented. Check them here.
  • SQL :
  • XInclude and XPointer :
    • xml:base might be inconsistent ; it will be fixed in a future release.
    • XPointer : only pure XPath expressions (without the XPointer extensions) are available when using the xpointer() scheme.
    • XInclude and SAX : XInclusions that require to write backward on nodes that have been already fired doesn't work ; for example when the definition of an entity have to be added to the DTD, it's impossible to deal with such cases because the XInclude instruction is encountered after the DTD. The report of the XInclude test suite explains this and shows the few other errors that remain.
  • XUnit :
    • The flags that can tune the nodes comparison are ineffective.
  • Others :
    • XPath with SAX : syntaxically, there are no limitations on XPath expressions that can be used with XCL filters ; however, using a backward step on some nodes that have been discarded gives unexpected results. Please read this.
    • Surely others limitations... See also the list of things to do.

Install

Java must be installed in your system.

The JVM has to know some .jar files in order to run RefleX : the files are $REFLEX_HOME/reflex-0.4.0.jar and $REFLEX_HOME/lib/*.jar where REFLEX_HOME is the path where is unzipped one of the distributions of RefleX (excluding the light distribution that doesn't contain the expected third party libraries) that you should set after unzipping. $REFLEX_HOME/libext/*.jar contains also additional libraries for running SQL tutorials and for WUnit.

Just declares the .jar files in your classpath if you have to use RefleX from the command line. Please refer to the tutorial section to see how to launch RefleX from the command line.

Web applications don't need such preparation, as libraries are loaded automatically when required. Ensure that the libraries are accessible by the underlying servlet engine : with Tomcat, you should copy them to $CATALINA_BASE/shared/lib where $CATALINA_BASE is the place where Tomcat is installed ; if you don't want to share the libraries, you can also copy them to the WEB-INF/lib/ directory of each of your Web applications. Please refer to the tutorial to see how to use RefleX with servlets.

See also : running RefleX.

Checking that everything works fine

With the "full" or "source" distribution, simply run the first tutorial : type the command line that launches it from the directory where you have unzipped RefleX. With the "source" distribution, you can build RefleX before.

With the "minimal" distribution, you should download the first tutorial and run it :

 $ wget http://reflex.gforge.inria.fr/tutorial/basic/hello/hello-world-template.xcl
 $ java -Dwho="John Doe" -jar reflex-0.4.0.jar run hello-world-template.xcl

Building

RefleX can be built using Ant.

  • The source distribution doesn't contain the expected libraries but the "full binary" distribution have them. The "full binary" distribution and the "source" distribution must be unzipped in the same directory. The .jar files can be built from the "source" distribution that contains the Ant build file:
     $ ant jar
     $ ant junit
     $ ant javadoc
    (note that some JUnit tests might fail due to bugs in third-party libraries as explained in the JUnit report)
    If you intend to build with Java 1.5 or 1.6, ensure to set the required compatibility options when compiling.
  • A new distribution can also be built from the SVN repository.

In any case, please read this.

Dependencies

RefleX works on Java 1.4.2 and higher. Note that some of the tools mentioned might require a higher version of Java.

DependencyVersionRequiredComment
Jaxen 1.1.1 Always [ This product includes software developed by the Jaxen Project. ]
Apache Jakarta Commons Logging 1.1 or later
Apache Commons VFS 1.0
Apache Jakarta Commons Httpclient 3.1 or later for WebDAV HTTP (optional) and WUnit
Apache Commons fileUpload 1.2.1 for file uploads in Web applications and WUnit
Apache Jakarta Commons Codec 1.3 or later
Apache Commons VFS (sandbox) 1.0-RC7 for CIFS (smb) and WebDAV only the relevant providers are expected for CIFS and WebDAV ; the other classes are in VFS 1.0
Apache Jakarta Commons Collections 3.2 for VFS : LRU Cache (optional)
Apache Jakarta Commons Net 1.4.1 or later for FTP (optional)
Apache Jakarta ORO 2.0.8
Apache Jakarta Commons IO 1.3.1 or later
Apache Jakarta Commons Lang 2.3 or later
jCIFS 0.8.3 or later for CIFS
JSch 0.1.35 or later for SFTP
XML:DB eXist-1.1.1 bundle for XML:DB With XQuery support : download here
FOP 0.95 or later for XSLFO conversion to PDF
CSSToXSLFO 1.6.1 or later for XHTML conversion to XSLFO
Neko HTML 1.9.13 or later for HTML parsing and WUnit
HtmlUnit 1.14 or later for unit test of Web applications with WUnit
Winstone 0.9.9 for WUnit testing of Web applications with the servlet-container emulator.
CSS Parser 0.9.5 or later for WUnit testing of Web applications.
Rhino 1.7R2 or later for Web applications that send to the client (X)HTML pages with Javascript
Apache Xerces for Neko HTML
Apache XML Commons SAX 2.0 API, DOM level 2, JAXP 1.1
Apache Batik SVG Toolkit 1.7 or later for rasterizing SVG images (also contains xml-apis-ext.jar)
DSML v2 for LDAP to XML This component is NOT included in the distribution.

The above components are included in the distribution (unless otherwise indicated differently).

Versions that are specifying "or later" should be replaced by the last version compatible. Please refer to the relevant Web sites.

Running

RefleX doesn't perform anything by its own, it executes an Active Sheet (an XML script) that performs actions or an Active Document which is rather an XML template with pieces of active tags.

An Active Sheet or an Active Document may use resources to accomplish what they are intending for : for example, a user-define module is such a resource ; a custom tag found in the Active Sheet or Active Document will be recognized as an active tag if the engine knows the module defined by the user ; for this purpose, the user-define module and additional resources such as schemata must be declared in a catalog delivered to the engine. Both the servlet and the command line interface are providing means to plug a catalog (or several) to the engine.

Command line interface

RefleX supply a class to run Active Sheets or Active Documents from the command line.

The command line interface is the class org.inria.ns.reflex.ReflexCLI. Its usage can be displayed in the standard output of a console :

 $ java -jar reflex-0.4.0.jar -h

For running an active sheet, ensure that the classpath contains the expected .jar files and invoke the CLI with the options expected.

Typical invocations are as follows :

  •  $ java org.inria.ns.reflex.ReflexCLI run /path/to/active-sheet.xcl
    (if the classpath has been set before)
  •  $ java -jar reflex-0.4.0.jar run /path/to/active-sheet.xcl
  •  $ java -Dvar1=value1 -Dvar2=value2 -jar reflex-0.4.0.jar (line cut)
            run /path/to/active-sheet.xcl
    (if system parameters have to be set)
  •  $ java -jar reflex-0.4.0.jar -c /path/to/catalog.cat (line cut)
            run /path/to/active-sheet.xcl
    (if a catalog have to be added to the engine)

If you don't know what to run, have a look at the tutorials.

Servlet

RefleX runs on Tomcat 5.0.28 and higher.

The servlet is the class org.inria.ns.reflex.ReflexServlet. Options for running the servlet can be view here.

Ensure that the expected .jar files are placed under $CATALINA_BASE/shared/lib/ or the WEB-INF/lib/ directory of your Web application. The files are $REFLEX_HOME/reflex-0.4.0.jar and $REFLEX_HOME/lib/*.jar where REFLEX_HOME is the path where is unzipped one of the distributions of RefleX.

The deployment descriptor of your application should look like this :

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.4//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app> <display-name>RefleX application</display-name> <description>My RefleX application</description> <servlet> <servlet-name>ReflexServlet</servlet-name> <display-name>RefleX servlet</display-name> <description>Runs an Active Sheet</description> <servlet-class>org.inria.ns.reflex.ReflexServlet</servlet-class> <init-param> <param-name>activeSheetPath</param-name> <param-value>web:///WEB-INF/active-sheet.web</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping><!--custom mappings--> <url-pattern>*.gif</url-pattern> <servlet-name>default</servlet-name> </servlet-mapping> <servlet-mapping><!--RefleX mapping--> <servlet-name>ReflexServlet</servlet-name> <url-pattern>/</url-pattern> </servlet-mapping> <welcome-file-list> <welcome-file>index.html</welcome-file> </welcome-file-list> </web-app>

All the resources in the Active Sheet or in the catalogs can use safely the web URI scheme to retrieve a resource in the context of the Web application.

If you don't know what to run, have a look at the tutorials.

Embedding

The best way to use RefleX is certainly to use or extend org.inria.ns.reflex.processor.ProcessorInstance.

Here is a snippet Java code to begin :

  ProcessorInstance pi = new ProcessorInstance();
  // load the catalogs (if any)
  pi.addCatalogReference( "file:///path/to/catalog1.cat" );
  pi.addCatalogReference( "file:///path/to/catalog2.cat" );
  // load and unmarshall the active sheet
  pi.unmarshal(
    XFile.getXFile( "file:///path/to/active-sheet.xcl" )
  );
  DataSet dataSet = new DataSet( pi );
  pi.callMain( dataSet );

Note: an XFile is just a little more than a java File : it support numbers of URI schemes.

Performances

No real benchmark have been realized yet. Testimonials are welcome.

As many indirections are used by the RefleX engine, the overhead has been computed in a real application which consist on loading many files in a native XML database with a batch script (Active Sheet) : it appears that less than 10% of the activity was imputable to the engine.