Jakarta Project: Ant Tasks Tag library

Version: 1.0

Overview
Requirements
Configuration
Tag Summary
Tag Reference
Examples
Javadocs
Revision History

Overview

The Gnat tag library is originally modeled after the tasks in the Ant build tool. Ant is a platform-neutral, pure Java, XML-based alternative to make, jam, const and similar tools. You can learn more about Ant at the Jakarta Ant Project.

This JSP tag library can be used to perform a variety of build-related and Ant-like tasks. It's called the Gnat Tag Library for a couple reasons, one being that it's even smaller than Ant (keeping in the insect metaphor), and less powerful. But it is and will continue to borrow ideas and even code from Ant where possible.

The goal of this tag library is to make all (give or take a few) of the Ant tasks available as stand-alone JSP custom actions, and to convert Ant behaviors to JSP behaviors where appropriate. Examples of changes to make the Ant tasks more like JSP tags are 1) treating the default output stream as JspWriter instead of System.out, and 2) throwing JspTagExceptions in places where an Ant task would throw a BuildException. Examples of changes that make the tasks work as standalone custom actions are 1) there is no need for a full Ant <project> or even a <target> in order to use the tasks as individual tags, and 2) tasks can take sub-elements where appropriate, such as property or fileset elements. But it should not be limited to or by Ant in anyway, and is free to have tags and functionality that one may not find or have any need for in Ant tasks.

A second goal that is currently on the backburner until Ant 2.0 gets rolling is a future, separate tag library that provides a JSP interface to the full Ant capabilities. In this case you should be able to take a build.xml file and enclose it in a JSP custom action, or generate (or modify) one on the fly, include it from an external source, and so on. This latter goal will hopefully be made easy by a client interface provided by Ant 2.0, which will allow a JSP custom action to cleanly tie into Ant with a minimum of effort on the JSP side.

Requirements

This custom tag library requires no software other than a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher.

Configuration

Follow these steps to configure your web application with this tag library:

Copy the tag library descriptor file to the /WEB-INF subdirectory of your web application.
Copy the tag library JAR file to the /WEB-INF/lib subdirectory of your web application.

Add a <taglib> element to your web application deployment descriptor in /WEB-INF/web.xml like this:

<taglib>
  <taglib-uri>http://jakarta.apache.org/taglibs/gnat-1.0</taglib-uri>
  <taglib-location></taglib-location>
</taglib>

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

<%@ taglib uri="http://jakarta.apache.org/taglibs/gnat-1.0" prefix="gnat" %>

where "gnat" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

Tag Summary

deltree	Deletes a directory and all its files and subdirectories.
echo	Echoes a message to the JSP output stream, or writes it to a file.
fail	Stops processing the current JSP by immediately returning SKIP_PAGE, optionally logging a message.
gzip	Creates a zip file.
gunzip	Decompresses a zip file.
ls	Returns a directory listing.
mkdir	Creates a directory on the host file system.
touch	Updates the last-modified time of files on the host file system, creating them if necessary.
tstamp	Sets variables TSTAMP, DSTAMP and TODAY to current times, same as Ant task of same name.

Tag Reference

deltree

Availability: version 1.0

Deletes a directory and all its files and subdirectories.

Tag Class org.apache.taglibs.gnat.deltreeTag

Tag Body empty

Script Variable No

Restrictions None

Attributes

Name	Required	Runtime Expression Evaluation
dir	true	true

Example

<%-- Delete a directory under the current Web application's tmp directory. --%>

<gnat:deltree dir="<%= tempdir+"/foodir" %>" />

echo

Availability: version 1.0

Echoes a message to the JSP output stream, or writes it to a file.

Tag Class org.apache.taglibs.gnat.echoTag

Tag Body jsp

Script Variable No

Restrictions None

Attributes

Name	Required	Runtime Expression Evaluation
message	false	true

file	false	true

append	false	true

Example

<%-- Echo a string literal to JSP out via the message attribute. --%>

<gnat:echo message="Hello, World!"/>
<%-- Echo a string literal and an expression to JSP out via opening and closing tags. (The time variable is used in example 3 too.) --%>
<%java.util.Date time = new java.util.Date();%>

<gnat:echo> Hi, here is a brief message and a dynamic date: <%= time %>. </gnat:echo>
<%-- Append the value of an expression to a file. --%>
<% File tempdir = (File)application.getAttribute("javax.servlet.context.tempdir"); %>
<%String echoLog = tempdir+"/echoAppendLog.txt";%>
<% String messageString = "Hello World. The time is: "+time+System.getProperty("line.separator"); %>

<gnat:echo message="<%= messageString %>" append="true" file="<%= echoLog %>" />

fail

Availability: version 1.0

Stops processing the current JSP by immediately returning SKIP_PAGE, optionally logging a message.

Tag Class org.apache.taglibs.gnat.exitTag

Tag Body empty

Script Variable No

Restrictions None

Attributes

Name	Required	Runtime Expression Evaluation
message	false	true
Optional message to log when the page fails.

Example

<%-- Exit the current JSP when it hits this tag, optionally logging a message through ServletContext.log(). --%>

<gnat:fail message="This JSP Failed!"/>

gzip

Availability: version 1.0

Creates a zip file.

Tag Class org.apache.taglibs.gnat.gzipTag

Tag Body empty

Script Variable No

Restrictions None

Attributes

Name	Required	Runtime Expression Evaluation
src	true	true
The file to zip.
zipfile	true	true
The filename of the zipped result, e.g., fooFile.gz or fooFile.Z.

Example

<%-- GZip a file (see <gnat:echo> example for tempdir variable creation). The src file is zipped with whatever name and extension is given in the zipfile attribute. --%>
<%final String foo = "/foo-file.txt";%>
<%final String foozip = foo + ".gz";%>

<gnat:gzip src="<%= tempdir+foo %>" zipfile="<%= tempdir+foozip %>"/>

gunzip

Availability: version 1.0

Decompresses a zip file.

Tag Class org.apache.taglibs.gnat.gunzipTag

Tag Body empty

Script Variable No

Restrictions None

Attributes

Name	Required	Runtime Expression Evaluation
src	true	true
An absolute path to the file to be unzipped.
dest	false	true
The [optional] destination file name.

Example

<%-- GUnzip a file. The dest attribute is optional and can be a directory to unzip the file into, or can be a new file name. If dest is omitted, the parent dir of src is taken as the destination (i.e., a copy of the file is unzipped in its current directory). The file is only expanded if the src file is newer than the dest file, or when the dest file does not exist. --%>
<%final String foounzip = foo + ".unzipped.txt";%>

<gnat:gunzip src="<%= tempdir+foozip %>" dest="<%= tempdir+foodir+foounzip %>" />

ls	Availability: version 1.0

Returns a directory listing.

Tag Class org.apache.taglibs.gnat.lsTag

Tag Body jsp

Script Variable Yes, named via the "id" attribute

Restrictions None

Attributes

Name	Required	Runtime Expression Evaluation
dir	true	true
An absolute file path to a directory. Support for relative paths may be added in a future revision.
id	true	true
Script variable id for use with standard jsp:getProperty tag

Example

<%-- List the contents of a directory under the current Web application's tmp directory. --%>

<gnat:ls dir="<%= tempdir+"/foodir" %>" id="files" > <jsp:getProperty name="files" property="items"/> </gnat:ls>

mkdir

Availability: version 1.0

Creates a directory on the host file system.

Tag Class org.apache.taglibs.gnat.mkdirTag

Tag Body empty

Script Variable No

Restrictions None

Attributes

Name	Required	Runtime Expression Evaluation
dir	true	true
An absolute path to a directory or a hierarchy of new directories to create (like UNIX mkdir -p).
clobber	false	true
Optional attribute for forcing mkdir to overwrite an existing directory structure.

Example

<%-- Name(s) of directory(ies) to create. All the parent directories of pickles will be created if they don't already exist. See <gnat:echo> example for creation of the tempdir variable. --%>
<%final String foodir = "/foodir/bar/baz/pickles";%>

<gnat:mkdir dir="<%= tempdir+foodir %>"/>

touch

Availability: version 1.0

Updates the last-modified time of files on the host file system, creating them if necessary.

Tag Class org.apache.taglibs.gnat.touchTag

Tag Body empty

Script Variable No

Restrictions None

Attributes

Name	Required	Runtime Expression Evaluation
file	true	true

millis	false	true

datetime	false	true

Example

<%-- Simple example of touching a file. See <gnat:echo> example for creation of the tempdir variable. --%>
<%final String foo = "/touched-file.txt";%>

<gnat:touch file="<%= tempdir+foo %>"/>
<%-- The millis attribute value can be assigned dynamically by using an expression, like so. --%>

<gnat:touch file="<%= tempdir+foo %>" millis="<%= new java.util.Date().getTime() %>" />
<%-- Or millis can be assigned statically, using milliseconds since midnight Jan 1 1970... The example below sets the last modified time as 12/24/2000 21:15pm. --%>

<gnat:touch file="<%= tempdir+foo %>" millis="977710526363" />
<%-- Or millis can be assigned statically, using milliseconds since midnight Jan 1 1970... The datetime attribute value must be set in format: MM/DD/YYYY HH:MM AM or PM. --%>
<%final String foo2 = "/second-touched-file.txt";%>

<gnat:touch file="<%= tempdir+foo2 %>" datetime="06/28/1983 2:02 pm" />

tstamp

Availability: version 1.0

Sets variables TSTAMP, DSTAMP and TODAY to current times, same as Ant task of same name.

Tag Class	org.apache.taglibs.gnat.tstampTag
Tag Body	empty
Script Variable	Yes: TSTAMP, DSTAMP and TODAY
Restrictions	Should only be used once in a page or else a duplicate variable exception will occur at translation time.
Attributes	None
Example	<%-- Set the time stamp variables for the current page. --%> `<gnat:tstamp />`

Examples

See the example application gnat-examples.war for examples of the usage of the tags from this custom tag library.

Java Docs

Java programmers can view the java class documentation for this tag library as javadocs.

Revision History

Review the complete revision history of this tag library.

Jakarta Project: Ant Tasks Tag library

Version: 1.0

Table of Contents

Overview

Requirements

Configuration

Tag Summary

Tag Reference

Examples

Java Docs

Revision History