xdocs/index.xml - commons-jelly - Git at Google

 <?xml version="1.0"?>
 <!--
   Copyright 2002,2004 The Apache Software Foundation.

   Licensed 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="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 intergration 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://jakarta.apache.org/commons/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>
	<?xml version="1.0"?>
	<!--
	Copyright 2002,2004 The Apache Software Foundation.

	Licensed 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="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 intergration 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://jakarta.apache.org/commons/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>
	<document time="${now}">
	Welcome ${user.name} to Jelly!
	</document>
	</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>
	<j:jelly xmlns:j="jelly:core" xmlns:define="jelly:define" xmlns:my="myTagLib">

	<define:taglib uri="myTagLib">
	<define:jellybean name="foo" className="MyTask"/>
	</define:taglib>

	Now lets use the new tag

	<my:foo x="2" y="cheese"/>

	</j:jelly>
	</source>

	<p>
	This mechanism is kinda similar to using a <taskdef> 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 <define:jellybean method="doIt"/>
	</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>
	<babelfish:translate from="en" to="fr">
	Welcome ${user.name} to Jelly!
	</babelfish:translate>
	</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>