Using the JAKARTA-TAGLIBS Source Distribution

Prerequisites

To successfully build the JAKARTA-TAGLIBS custom tag libraries, you must have successfully installed a Java Development Kit (JDK), version 1.1 or later, for your platform. Your PATH environment variable must include the /bin directory of the JDK, such that the java and javac commands are executable.

Also, you must acquire and install a suitable servlet.jar file that contains the standard servlet and JSP API classes for JSP version 1.1 or later. Normally, this file will be included with your servlet container. (If you have downloaded Tomcat, this file is available in the lib directory under your Tomcat installation home directory. Set an environment variable named SERVLET_JAR to contain the absolute pathname to the location of this file, to make it visible when you build JAKARTA-TAGLIBS libraries.

To build the JAKARTA-TAGLIBS custom tag libraries, you will need the Ant development tool, which is used to control the build process. A binary distribution of Ant is available from http://jakarta.apache.org/downloads/binindex.html. and should be unpacked (as described below) in a directory parallel to the directory into which you download and unpack the JAKARTA-TAGLIBS source distribution.

Finally, you will need a servlet container that is compatible with the Servlet API Specification, version 2.2 or later, and supports the JavaServer Pages (JSP) Specification, version 1.1 or later. Many such servlet containers are available -- the Jakarta project hosts the Tomcat servlet container (which meets these requirements) at http://jakarta.apache.org/downloads/binindex.html. (You can also download the source distribution of Tomcat and build it yourself, if you wish.)

Download and Installation

Source downloads of the JAKARTA-TAGLIBS distribution, as with all other Jakarta projects, are available from the Jakarta web site at http://jakarta.apache.org/downloads/sourceindex.html.

Download and unpack the JAKARTA-TAGLIBS distribution (from the link above) into a directory parallel to the directory into which you downloaded and unpacked the Ant distribution. For example, you might end up with the following directory structure:

your_home_directory/
    jakarta-ant/                <-- Contains binary distribution of Ant
        lib/                    <-- Binary libraries directory
	    ant.jar             <-- Ant executable classes
            xml.jar             <-- XML parser required by Ant
    jakarta-taglibs/            <-- Contains source distribution of the
                                    JAKARTA-TAGLIBS libraries
        ... see below ...

Be sure you have set your SERVLET_JAR environment variable to point at the servlet.jar containing the servlet and JSP API classes, as described above.

Directory Structures

The distribution archive will contain the following file and directory structure:

• LICENSE - A copy of the Apache Software Foundation license under which all Jakarta project software is distributed.
• README - A brief README file that contains pointers to the documentation that is available.
• build - A shell script that builds all of the included custom tag libraries on Unix platforms. See below for more details.
• build.bat - A shell script that builds all of the included custom tag libraries on Windows platforms. See below for more details.
• build.xml - An XML file that describes the build process for all of the included custom tag libraries. See the Ant documentation for more information about the contents of this file.
• doc - A directory containing documentation about the JAKARTA-TAGLIBS project as a whole, including this file. The following documents are included:
  • Documentation Index
  • Using the JAKARTA-TAGLIBS Binary Distribution (this document)
  • Using the JAKARTA-TAGLIBS Source Distribution
• A directory for each custom tag library included in the JAKARTA-TAGLIBS project, where the directory name matches the short name of that project. Each directory will contain the following files and subdirectories
  • build.bat - A shell script that builds this particular custom tag library on Windows platforms. See below for more details.
  • build.sh - A shell script that builds this particular custom tag library on Unix platforms. See below for more details.
  • build.xml - An XML file that describes the build process for this particular custom tag library. See the Ant documentation for more information on the contents of this file.
  • conf/ - A directory containing configuration and other resource files for this custom tag library, which will normally be used within a web application. At a minimum, the tag library descriptor (TLD) file for this custom tag library must be present, in a file that is named taglib.tld.
  • doc/ - The source code (Java classes, resource files, HTML pages, JSP pages, and so on) for a web application that will contain the developer documentation for this tag library. This web application will be combined into a {library}-doc.war web application archive in the binary distribution. See below for more information about the internal directory structure of web applications.
  • examples/ - The source code (Java classes, resource files, HTML pages, JSP pages, and so on) for a web application that demonstrates the use of custom tags within this custom tag library. This web application will be combined into a {library}-examples.war web application archive in the binary distribution. See below for more information about the internal directory structure of web applications.
  • src/ -- The Java source code and resource files of the classes that comprise this custom tag library. The internal directory arrangement within the source directory must reflect the assignment of classes to Java packages, in the usual manner. To avoid name clashes, the package name for each custom tag library should be org.apache.taglibs.{library} so that multiple JAKARTA-TAGLIBS can be used in the same application if desired.

Within the doc/ and examples/ subdirectories for each custom tag library, the following directory organization is used to contain the source components of this application:

• conf/ -- The web.xml file for this application, plus any other files that should be copied to the WEB-INF subdirectory.
• src/ -- The Java source code and resource files for this application. Package names are arbitrary, but we recommend using org.apache.taglibs.{library}.doc for the documentation application, and org.apache.taglibs.{library}.examples for the example application.
• web/ -- The HTML and JSP pages that comprise this application's user interface. The index.html or index.jsp page in this directory will be the "home" page of the application when it is deployed in a servlet container.

Building JAKARTA-TAGLIBS Libraries

To build the distribution version of all included custom tag libraries, set your current directory to the jakarta-taglibs directory into which you unpacked the distribution, and execute the global build script:

    build                       <-- Window platforms
    build.sh                    <-- Unix platforms

In addition to the directories described earlier, two additional directory hierarchies will be created to contain the results, resulting in the following overall organization:

your_home_directory/
    build/                      <-- Contains intermediate form results of
                                    building Jakarta applications
        taglibs/                <-- Contains intermediate form results of
                                    building JAKARTA-TAGLIBS custom libraries
    dist/                       <-- Contains the files that will be included
                                    in binary distributions of Jakarta
                                    applications
        taglibs/                <-- Contains the files that will be included
                                    in the binary distribution of the
                                    JAKARTA-TAGLIBS project, as described in
				    binary distribution documentation
    jakarta-ant/                <-- Contains binary distribution of Ant
        lib/                    <-- Binary libraries directory
	    ant.jar             <-- Ant executable classes
            xml.jar             <-- XML parser required by Ant
    jakarta-taglibs/            <-- Contains source distribution of the
                                    JAKARTA-TAGLIBS libraries

When you are working on a particular custom tag library, it is faster to rebuild only that particular library while doing development. To do this, change to the top level directory of that custom tag library (for example, change to the jakarta-taglibs/jspspec directory to work on the JSP Specification Examples custom tag library. You can now use one of several variants of the build script, depending on what you want to do. In each of the following cases use build on Windows systems, or build.sh on Unix systems:

• build -- Update the intermediate form (in the ../../build/taglibs directory) of the library itself, the documentation application, and the example application. This copies any static files that have been changed, and recompiles any Java sourc classes that have been changed. Because this is the most commonly executed command, it is the default.
• build library -- Update the intermediate form of the library classes only. This is useful when you are making sure it still compiles.
• build documentation -- Update the intermediate form of the documentation application. If your servlet container can accept an unpacked web application (as Tomcat can), the ../../build/taglibs/{library}/doc directory can be set as the document root, and the application can be executed directly.
• build examples -- Update the intermediate form of the examples application (including copying the library classes into WEB-INF/classes). If your servlet container can accept an unpacked web application (as Tomcat can), the ../../build/taglibs/{library}/examples directory can be set as the document root, and the application can be executed directly.
• build library-dist -- Build and copy the {library}.jar and {library}.jar files for this tag library into the distribution directory (../../dist/taglibs/{library}). These distribution files can be copied directly into web applications that wish to use this custom tag library.
• build documentation-dist -- Build the {library}-doc.war documentation application, and copy it into the distribution directory (../../dist/taglibs/{library}). This application can be deployed and executed on any servlet container.
• build examples-dist -- Build the {library}-examples.war examples application, and copy it into the distribution directory (../../dist/taglibs/{library}). This application can be deployed and executed on any servlet container.
• build dist -- Short cut command that builds all three distribution targets (dist-library, dist-doc, and dist-examples).
• build clean -- Deletes the intermediate and distribution results for this custom tag library, so that you can rebuild from scratch.

When you perform a global build, the build dist option is invoked on each included subproject.

Adding A New JAKARTA-TAGLIBS Custom Tag Library

Adding a new custom tag library subproject to JAKARTA-TAGLIBS is fairly straightforward. It involves the following steps:

• Create a top-level directory for the new project. The directory name should be a relatively short abbreviation of this custom tag library, because it will be used repeatedly in filenames.
• Within that directory, copy the top-level files (build, build.bat, and build.bat from one of the existing subprojects, such as jspspec. Using a text editor, customize the build.xml file by changing the value of the taglib.name property to the short name of the new custom tag library subproject you are building.
• Within the subproject directory, duplicate the directory structure from one of the existing subprojects, such as jspspec.
• You should now be able to develop and build your new tag library from within its subdirectory, using its own build.xml script. The final step is to modify the top level build.xml script, so that a global build will include your new library. The required changes are documented within the global build.xml file.