Java installed in your system.runs in a JVM. You must have
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).
|Full binary release (zip)||This is the main binary distribution which contains dependencies). Full documentation (including tutorials) + Javadoc + the XUnit and WUnit applications.and all additional third party libraries (see||All
|Minimal binary release (zip)||This is the minimal binary distribution which contains dependencies). No documentation is provided in this pack.and only the third party libraries that are required (see|
|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 without ).|
|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.|
|SVN repository||The Subversion repository to checkout.|
Older and new releases can be accessed online here.
This version of Active Test section.is 0.4.0-beta. The engine is much more reliable than in the previous version. Complex scenarii are well-tested with and since v0.3.1 with . Web applications of the tutorial section are now part of the test suite of the engine. Please refer to the
Why is it a beta version ?
can be used safely in production.
Although the current version is under a beta status,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 and -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 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.
Users that would like to usein their project should be aware that as long as the 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.
- 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).
- Partially implemented, but the core machinery works.
- Circularity on catalogs is not checked.
- Schemata :
- Only get an error report. is (partially) supported. Consider as experimental as it is not trivial to
- 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 here. , but some are not yet implemented. Check them
- 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.
- The flags that can tune the nodes comparison are ineffective.
- Others :
Java must be installed in your system.
The JVM has to know some .jar files in order to run: 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 (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 .
Just declares the .jar files in your classpath if you have to use tutorial section to see how to launch from the command line.from the command line. Please refer to the
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 with servlets.
See also : running .
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 . With the "source" distribution, you can build 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
Ant.can be built using
- 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.
works on Java 1.4.2 and higher. Note that some of the tools mentioned might require a higher version of Java.
|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.|
|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.
doesn't perform anything by its own, it executes an (an XML script) that performs actions or an which is rather an XML template with pieces of active tags.
Anor an 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 or 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
supply a class to run s or s 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 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 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.
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.
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 web URI scheme to retrieve a resource in the context of the Web application.or in the catalogs can use safely the
If you don't know what to run, have a look at the tutorials.
The best way to use org.inria.ns.reflex.processor.ProcessorInstance.is certainly to use or extend
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 );
No real benchmark have been realized yet. Testimonials are welcome.
As many indirections are used by theengine, the overhead has been computed in a real application which consist on loading many files in a native XML database with a batch script ( ) : it appears that less than 10% of the activity was imputable to the engine.