Using RefleX

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

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. See "How-To" if you have to. Note that custom modules can also be defined without Java, but as macros.

Download

RefleX can be downloaded at INRIA's gforge.

Older and new releases can be accessed online here.

Release notes

This version of RefleX is 0.3.2-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.

Status - Why is it a beta version ?

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 :
  • You can't use a filter 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 :
  • Any JDBC driver that support prepared statements and the ResultSet.TYPE_SCROLL_INSENSITIVE and ResultSet.CONCUR_UPDATABLE features.
  • See also other possible SQL issues.
• 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

The JVM has to know some .jar files in order to run RefleX : the files are $REFLEX_HOME/reflex-0.3.2.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 /WEB-INF/lib/ 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" and "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.3.2.jar run hello-world-template.xcl

Building

You can build RefleX 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. You can build the .jar files 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.
  
• You can also build a new distribution from the SVN repository.

In any case, please read this.

Dependencies

RefleX works on Java 1.4.2.

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

• Command line interface
• Servlet
• Embedding

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 document 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.3.1.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.3.2.jar run /path/to/active-sheet.xcl

•  $ java -Dvar1=value1 -Dvar2=value2 -jar reflex-0.3.2.jar 
          run /path/to/active-sheet.xcl

  (if system parameters have to be set)

•  $ java -jar reflex-0.3.2.jar -c /path/to/catalog.cat 
          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.3.2.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
  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 );

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.