View source

Servlex is the implementation of the EXPath Webapp module using Java Servlet technology for the server part, and Saxon and Calabash for the XSLT, XQuery and XProc processing.

==Configuration==

Servlex can be downloaded from its [http://code.google.com/p/servlex/downloads/list Google Code project].

Servlex is a typical Java EE web application, relying only on the Servlet specification.  It uses an EXPath repository on the disk.  The exact location of the repository is read via the system property <code>org.expath.servlex.repo</code> (this is the directory at the root of the repository).  For Tomcat, you can set the property by adding the following to the global <code>catalina.properties</code> file:

<pre>
org.expath.servlex.repo=/some/path/to/servlex/repo
</pre>

For Tomcat on a server, the following security permissions should also be set (in the policy file):

<pre>
grant codeBase "file:${catalina.base}/webapps/servlex/-" {
    // the repository dir
    permission java.io.FilePermission "/some/path/to/servlex/repo/-", "read";
    // commons xml resolver does read those properties
    permission java.util.PropertyPermission "xml.catalog.*", "read";
    permission java.util.PropertyPermission "user.dir", "read";
    // if you use the http client module within the stylesheets
    permission java.util.PropertyPermission "org.expath.hc.http.version", "read";
    permission java.net.NetPermission "getProxySelector";
    permission java.net.SocketPermission "site-accessed.com", "resolve,connect";
};
</pre>

Once you've deployed the WAR in your application server, you can see if everything is fine by accessing the application page.  For instance, if you use Tomcat locally on http://localhost:8080/, just navigate to http://localhost:8080/servlex/.

==Google App Engine==

Servlex can be deployed on [http://code.google.com/appengine/ Google App Engine].
Because GAE does not allow the webapp to access the file system, Servlex
cannot use the on-disk repository.  Instead, the repository must
be in the classpath.
A [http://code.google.com/p/servlex/source/browse/trunk/bin/servlex-appengine.sh script]
allows you to do it automatically.

Let's see how to call it in the simplest form.  If your webapp
project has the following structure on disk (i.e. following the
[http://code.google.com/p/expath-pkg/source/browse/trunk/project/ EXPath Project]
structure):

 my-webapp/
     dist/
         my-webapp-1.0.0.xaw
     src/
         ...
     xproject/
         appengine-web.xml
         expath-web.xml
         project.xml

Providing the GAE descriptor (that is, <code>appengine-web.xml</code>) sets
the property <code>org.expath.servlex.repo.classpath</code> to the value
<code>org.expath.servlex.repo.appengine</code>, then from the top-level
directory, you can call the script like the following (relying on
default values for all other options, and where servlex.war is
the WAR file from the Servlex release):

 servlex-appengine --servlex .../servlex.war dist/my-webapp-1.0.0.xaw

This wil create the directory <code>dist/servlex-appengine-war/</code>,
which you can upload using the GAE SDK script's appcfg.sh:

 APPENGINE_SDK/bin/appcfg.sh update dist/servlex-appengine-war/

For the basic usage, that's all you need to know.  In order to
adapt this to your real-life project, you might need to know in
further details what's going on under the hood.  What this script
does is the following:

* unzip the WAR file to the destination directory

* create a new, empty, temporary repository for EXPath packages (that is, XAR and XAW files)

* deploy every packages you give on the command line to this temporary repository

* zip this repository into a JAR file

* put this JAR file, as well as your GAE descriptor to the destination directory (that is, within the unzipped WAR)

Doing so, the repository is then accessible through the
classpath, using a specific ''Java package prefix''.  By default
this is <code>org.expath.servlex.repo.appengine</code>, but you can adapt
it.  In any case, this must be set as the value of the system
property <code>org.expath.servlex.repo.classpath</code> in the GAE
descriptor.  A minimal descriptor is then (along with other
required values from GAE):

 <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
 
    <application>yourid</application>
    <version>0</version>
 
    <precompilation-enabled>false</precompilation-enabled>
 
    <system-properties>
       <property name="org.expath.servlex.repo.classpath" value="..."/>
    </system-properties>
 
 </appengine-web-app>

Note the precompilation is disabled.  This is because of an
[http://blog.adriaandejonge.eu/2010/06/running-saxon-he-on-google-app-engine.html incompatibility]
between GAE precompilation and signed JARs, as Saxon is.

The complete list of options for the scripts (besides the
''option'' --help to display the help message) is:

 servlex-appengine [--servlex ...] [--dir ...]? [--desc ...]? [--xrepo ...]?
                   [--pkg ...]? [--jar ...]? [--tmp ...]?
                   <list of XAR and XAW files...>
 
 --servlex     path to the Servlex WAR file
 --dir         the target directory to create the exploded WAR into
 --desc        path to the GAE appengine-web.xml descriptor
 --xrepo       path to the xrepo command (by default in the PATH)
 --pkg         Java package name to put the in-classpath-repository in
 --jar         the name of the JAR file to create for the repository
 --tmp         a working directory to create files (by default a tmp dir)