<?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at
  
       http://www.apache.org/licenses/LICENSE-2.0
  
  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->

<document>

 <properties>
  <title>Jelly : Executable XML</title>
  <author email="jstrachan@apache.org">James Strachan</author>
 </properties>

<body>

<section name="Warning: low development activity">
<p>Please note that Commons Jelly is enduring a phase 
 with low activity of its developers.
  </p>
</section>

<section name="Jelly : Executable XML">

<p><em>Jelly</em> is a tool for turning XML into executable code.
So Jelly is a Java and XML based scripting and processing engine. 
Jelly can be used as a more flexible and powerful front end 
to <a href="http://jakarta.apache.org/ant/">Ant</a> 
such as in the <a href="http://maven.apache.org/">Maven</a>
project, as a testing framework such as <a href="jellyunit.html">JellyUnit</a>, 
in an integration or workflow
system such as <a href="http://werkflow.werken.com/">werkflow</a> 
or as a page templating system inside engines like 
<a href="http://cocoon.apache.org/">Cocoon</a>.
</p>

<p>
Jelly borrows many good ideas from both JSP custom tags, Velocity, Cocoon, Ant. 
Jelly can be used from the command line, inside Ant and 
Maven or inside a Servlet, Web Service, JMS MessageListener or embedded directly into your software. 
</p>

<p>
Jelly has native support for a Velocity-like expression language called
<a href="http://commons.apache.org/jexl/">Jexl</a> 
which is a superset of the JSP, JSTL and JSF expression languages
as  well as support for other pluggable expression languages like XPath via 
<a href="http://jaxen.org">Jaxen</a>, JavaScript, beanshell and Jython.
</p>

<p>
Jelly is completely extendable via custom tags in a similar way to JSP custom tags or Ant tasks.
Though Jelly is really simple and has no dependencies either Servlets or JSP.
So you could think of Jelly as similar to an XML-ized Velocity where the directives are XML tags.
Or you could think of Jelly as a more flexible engine for processing Ant tasks with better expression, 
logic and looping support.
</p>

<p>
Jelly is also based on an XML pipeline architecture, like Cocoon, so that it is ideal for processing XML,
scripting web services, generating dynamic web content or being part of a content generation 
system such as Cocoon.
</p>

</section>


<section name="How it works">

<p>A Jelly script is an XML document which gets parsed into a Script. The script can then be ran to produce
dynamic XML events which can then be turned into text, XML, HTML etc.
</p>
 
<p>
Rather like Velocity, the XML can contain expressions to make the output dynamic and can work with a variable 
context.
</p> 


<source>
&lt;document time="${now}"&gt;
  Welcome ${user.name} to Jelly!
&lt;/document&gt;
</source>


<p> 
XML elements can be bound to some Java code to implement some kind of dynamic processing.
The default way to do this is to implement Jelly <i>Tags</i> which are Java Beans which also implement Jelly's 
<a href="apidocs/org/apache/commons/jelly/Tag.html">Tag</a> interface. 
</p>

<p>
When a Jelly script is run, the properties of the Jelly Bean are configured using the XML attributes.
Then the tag is run by calling its <i>doTag()</i> method. 
The Tag can then perform some processing and invoke its body (the contents of the XML element) 
if it wishes, however many times it wants. So Jelly Tags are very like JSP custom tags and analogous 
to <i>directives</i> in Velocity..
</p>

<p>
There is an Ant Tag Library which allows all Ant tasks to be used inside a Jelly script.
</p>

<p>
Also Jelly Tags can be defined at runtime in dynamic Jelly script using the 
<a href="libs/define/tags.html">define</a> tag 
library so that simple yet powerful macros can be made very easily using just Jelly script.
</p>

<p>
<i>Jelly Beans</i> can be created with the define tag library. A Jelly Bean is where a regular 
Java Bean can be bound to a Jelly tag. If the bean implements the Runnable interface or has some kind
of invokable method, like run(), invoke() or execute() then the bean will also be invoked by the tag.
</p>

<p>
For example imagine if you had written the following bean
</p>

<source>
public class MyTask {

    // 'doIt' method that does some function/task...
    public void run() throws SomeException {
        // do something...
    }

    // Properties, can be any type
    public void setX(int x) {
        this.x = x;
    }
    public void setY(String y) {
        this.y = y;
    }
}
</source>

<p>
Then you can use this bean in a script by defining a new tag library and
then using the new tag as follows...
</p>

<source>
&lt;j:jelly xmlns:j="jelly:core" xmlns:define="jelly:define" xmlns:my="myTagLib"&gt;

  &lt;define:taglib uri="myTagLib"&gt;
    &lt;define:jellybean name="foo" className="MyTask"/&gt;
  &lt;/define:taglib&gt;

  Now lets use the new tag
  
  &lt;my:foo x="2" y="cheese"/&gt;

&lt;/j:jelly&gt;
</source>

<p>
This mechanism is kinda similar to using a &lt;taskdef&gt; in Ant except that the
bean can be anything, it doesn't need to derive from Ant's Task - it can be
any java object with some kind of 'doIt' method which takes no arguments.
Indeed the method name can be set via &lt;define:jellybean method="doIt"/&gt;
</p>


</section>

<section name="JSTL">
<p>
<a href="http://java.sun.com/products/jsp/jstl/">JSTL</a> 
is the JSP Standard Tag Library which is standardized through the JCP process.
</p>

<p>
Jelly implements a collection of JSTL tags to perform core features like 
expression evaluation, conditional branching and looping, as well the processing of beans, XML, XPath and SQL. 
</p>

<p>
Jelly can act as a stand alone lightweight engine for running JSTL 
scripts which can be run from the command line or from Ant or that can be easily 
embedded into SOAP services, Servlet engines, JMS MessageListeners or your own software.
</p>

<p>
In addition Jelly allows the JSTL tags to be used to create unit testing scripts 
for web applications and web services.
</p>
</section>


<section name="Ant">
<p>
There is a JellyTask for calling Jelly from 
<a href="http://jakarta.apache.org/ant/">Ant</a> 
as well as a Jelly tag library for using any Ant Tasks inside a Jelly script!
</p>

<p>
Jelly's support the Jexl expression language which is a superset of the expression language in JSTL 
and Ant's expression language, means that Ant properties can be used inside Jelly scripts seamlessly
while also working with beans, properties, collections, method calls etc.
</p>

<p>
So Jelly can be thought of as a more flexible scripting and processing engine for Ant, kinda like 
a combination of Ant, Velocity and JSP.
</p>
</section>


<section name="XML and Web Services">
<p>
Jelly is based on an XML event pipeline architecture (SAX), like Cocoon, rather than being purely text
based like JSP and Velocity. This means that Jelly tags can consume XML events and emit them. Each
Jelly Tag can then act as an XML source, result, filter or transformation.
</p>

<p>
Also because Jelly works on an XML event pipeline, XML can be processed very efficiently without redundant
runtime parsing. 
Once a Jelly script is parsed, it can be cached so that whenever it is run, no XML parsing is usually necessary of the input or the output.
</p>

<p>
In addition there is a tag library called the Jelly Stylesheet Library (
<a href="libs/jsl/tags.html">JSL</a>) for
performing XSLT-style declarative processing of XML documents using a pattern match approach.
</p>

<p>
Using the dynamic tag creation features of the <i>define</i> tag library we can easily script SOAP services using
a simple tag based macro language. 
</p>

<p>
For example the following piece of Jelly script could evaluate its dynamic 
body (which can contain any Jelly tags, JSTL or Ant tasks) then convert the body into the correct SOAP message, call a SOAP service
then format the results neatly as XML.
</p>

<source>
&lt;babelfish:translate from="en" to="fr"&gt;
  Welcome ${user.name} to Jelly!
&lt;/babelfish:translate&gt;
</source>

<p>
A Jelly script is an XML document, which means that Jelly can process itself.
All of these things make Jelly a good choice for for working with XML and Web Services.
</p>

</section>


<section name="Other uses">
<p>
We hope Jelly can be both generic and powerful XML processing and transformation engine, 
a web and XML based scripting engine as well as a unit testing framework for 
testing web applications and web services.
</p>

<p>
Currently Jelly is being used inside <a href="http://maven.apache.org/">Maven</a>
to provide more flexible and powerful build mechanism while still preserving investment in Ant tasks.
</p>

</section>

<section name="JSTL References">
  <ul>
    <li><a href="http://java.sun.com/products/jsp/jstl/1.1/docs/tlddocs/index.html">JSTL Tag reference</a></li>
    <li><a href="http://java.sun.com/products/jsp/jstl/1.1/docs/api/index.html">JSTL API</a></li>
    <li><a href="http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html">Apache JSTL Implementation</a></li>
  </ul>
</section>

</body>
</document>