General

What is Jelly?

Jelly is an open and customizable XML processing engine. Please see the Home page and Overview documents for more detail.

Why is this called Jelly?

The name started out as 'Jele' as in Java ELEments but then I thought Jelly was a nicer spelling :-). The basic idea behind Jelly that Java code is bound on to XML elements.

Also Jelly (in British or Jello in American) can be molded to fit any shape required which kinda fits with Jelly's main aim to be a flexible Java and XML based scripting engine that can do anything.

There are many different specific frameworks that take an XML document, bind it to some kind of bean or object and then evaluate it in some kind of script or process, so Jelly was an attempt at a generic engine using ideas from JSP, JSTL, Velocity, Cocoon and Ant.

How do I report a bug or request a feature?

Use the Jelly JIRA page: http://issues.apache.org/jira/browse/JELLY

Using Jelly

How do I call Jelly from Java code?

Try the following code. Note that the runScript() method below is overloaded and can take a File, URL etc.

// pass the output of the script somewhere
Writer someWriter = new FileWriter( "output.xml" );
XMLOutput output = XMLOutput.createXMLOutput( someWriter );

// now run a script using a URL
JellyContext context = new JellyContext();
context.runScript( "foo.jelly", output );

How do I invoke Jelly from the command line?

When you build a binary disitribution of Jelly, there is a jelly script which works on Windows and Unixes to run Jelly. You can create a binary distribution of Jelly via maven dist

All you really need to do is to invoke the org.apache.commons.jelly.Jelly class from the command line with a correct classpath.

How do I invoke Jelly from inside Ant?

There is an Ant task that comes with the Ant library called org.apache.commons.task.JellyTask which can be taskdef'd in any Ant script.

How do I invoke Jelly from inside Maven?

Maven's maven.xml file is actually a Jelly script; so you can include any Jelly script inside any of the Maven goals. So if you want to execute a specific Jelly script you can just <j:include uri="foo.jelly" > it inside the maven.xml.

How do I add my own tag libraries to Jelly?

Firstly you need to create one or more tags, by deriving from TagSupport. Then create a TagLibrary class for your tags; typically all this does is register all the tags in your tag library and give them names. Then you can use your new tag library by specifying the classname in a namespace URI. For example

<j:jelly xmlns:j="jelly:core" xmlns:foo="jelly:com.acme.something.MyTagLibrary">

  <foo:bar x="12>
    something goes here
  </foo:bar>

</j:jelly>

Going forward we hope to provide an alias mechanism using the jar-extension mechanism used by JAXP so that a file could be placed on the classpath called META-INF/services/org.apache.commons.jelly.foo which would contain the class name of the tag library (com.acme.something.MyTagLibrary) then you could use it as follows, which would avoid using the class name in your scripts.

<j:jelly xmlns:j="jelly:core" xmlns:foo="jelly:foo">

  <foo:bar x="12>
    something goes here
  </foo:bar>

</j:jelly>

How do I use expressions and tag attributes?

Jelly uses introspection to set the properties on a Tag from the XML attribute values. If the attribute value in XML uses an expression, it will be evaluated and the result of the expression will be passed into your Tag's setter method. For example if you had the following Tag...

public class FooTag extends TagSupport {
  private String value;

  public void setValue(String value) {
    this.value = value;


  .
}

Then if you were to use it like this...

  <my:foo value="${customer.fullName}"/>

Then this would be equivalent in pseudocode to

FooTag tag = FooTag();
...
tag.setValue( ((Customer) context.getVariable("customer")).getFullName() );
...
tag.doTag(output);

If ever you find that your Tag's bean property is not being set it could be that your Tag is not properly following the bean introspection naming conventions. For example do you have a method called getValue() or isValue() with the wrong return type? (In this discussion substitute 'value' for the name of your own property, it doesn't have to be called 'value' :). For more details of the introspection rules, please checkout the Java Bean specification.

It could be that you want to coerce the value of an expression to some special type. For example if you want to evaluate the expression as an Iterator you can use a property on your Tag of type Expression so that in your Tag you can use the Expression.evaluateAsIterator() method. This is how the <x:forEach> tag currently is implemented for example.

public class FooTag extends TagSupport {
  private Expression value;

  public void setValue(Expression value) {
    this.value = value;
  }

  public void doTag(XMLOutput output) {
    Iterator iter = expression.evaluateAsIterator();
            ...
  }
}

How do Jelly scripts handle CDATA sections?

Jelly outputs the content of a CDATA section directly. You can use CDATA sections to create output that otherwise cannot be described in XML. For example, you can use a CDATA section to create a DTD. The following Jelly script:

<?xml version="1.0"?>

<j:file xmlns:j="jelly:core" var="foo" escapeText="false">
    
    <![CDATA[
        <!DOCTYPE foo [
            <!ELEMENT foo (#PCDATA)>
        ]>
    ]]>
    
    <foo/>
    
</j:file>

How does one write ${a.variable} to the output?

Use the double-dollar as in

<?xml version="1.0"?>
<j:jelly xmlns:j="jelly:core">
  This is $${escaped}
</j:jelly>

Building Jelly

How do I build Jelly?

Jelly uses Maven for its build system. So you should be able to build Jelly just like any other Maven enabled project. Please see the Maven documentation for details.