--------------------------------------------------------------------------- Standard Tag Library 1.1 -- SOURCE DISTRIBUTION --------------------------------------------------------------------------- Thanks for downloading the source code of the Standard tag library, an implementation of the JavaServer Pages(tm)(JSP) Standard Tag Library (JSTL). JSTL is an effort of the Java Community Process (JCP) and comes out of the JSR-052 expert group. For more information on JSTL, please go to http://java.sun.com/products/jstl. --------------------------------------------------------------------------- BUILD ENVIRONMENT SETUP --- J2SE (Java 2 Standard Edition) Download and install Sun's distribution of J2SE 1.4.2 (or higher) for your operating system platform. J2SE can be found at http://java.sun.com/j2se. Sun's distribution of J2SE 1.4.2 includes many of the libraries that standard 1.1 depends on. However, please note that standard 1.1 will compile and run on previous versions of J2SE (from 1.3 up to 1.4.1) as long as the standard 1.1 dependencies not included in these versions of the J2SE are properly setup. See section 'LIBRARY DEPENDENCIES' for details. - Set a JAVA_HOME environment variable to point at the directory where J2SE is installed. - Add the JAVA_HOME/bin directory to your PATH. --- Ant Download and install version 1.5 or higher of the Jakarta Ant Project distribution. Ant can be fount at http://ant.apache.org. - Set the ANT_HOME environment variable to point at your Ant distribution directory - Add the ANT_HOME/bin directory to your PATH. --------------------------------------------------------------------------- LIBRARY DEPENDENCIES This version of the Standard Tag Library has the following compile-time dependencies: 1. Dependencies not included in J2SE: - Servlet 2.4 - JSP 2.0 2. Dependencies included in newer J2SEs (1.4.2 and higher) - JAXP 1.2 - Xalan 2.5 - JDBC Standard Extension 2.0 Since all of the dependencies in (2) are included in Sun's distribution of J2SE 1.4.2 (or higher), this is therefore the J2SE version of choice to compile and run the standard tag library. If you still need the jar files for the dependencies listed in (2), instructions on where you can get these jar files are included below. --- build.properties - Copy the file standard/build_sample_standard.properties to build.properties. - Edit build.properties and make the following modifications: - Set the "base.dir" property in build.properties to the base directory of your 'standard' distribution. It must be an absolute path. - Set the jar file properties to the absolute path and filename for the jar files required to build the standard tag library (see below). --- Servlet 2.4 and JSP 2.0 Download and install the Servlet 2.4 and JSP 2.0 APIs. The jar files for these APIs may be found in distributions of jakarta-servlet-api-5-bin and jakarta-jsp-api-5-bin at http://cvs.apache.org/builds/jakarta-tomcat-5/nightly. They are also included in Tomcat 5, available at http://jakarta.apache.org/tomcat. Set the following properties in build.properties to the file paths of the jars: - servlet24.jar - jsp20.jar --- JAXP 1.2 [required only if building with versions of J2SE that do not include the JAXP APIs, such as J2SE 1.3] The JAXP 1.2 jar files can be obtained in the Java Web Services Developer Pack (JWSDP) available at http://java.sun.com/products/jwsdp. Set the following properties in build.properties to the file paths of the jars: - jaxp-api.jar - dom.jar - sax.jar - xercesImpl.jar --- Xalan 2.5 [required only if building with J2SE 1.3 up to J2SE 1.4.1] The Xalan jar file can be obtained in the Java Web Services Developer Pack (JWSDP) available at http://java.sun.com/products/jwsdp, as well as from Apache at http://xml.apache.org/xalan-j. Set the "xalan.jar" property in build.properties to the jar file of Xalan. If using jdk 1.3, put xalan.jar in the lib directory of ant so XSLT transformations of documentation can be properly done. --- JDBC Standard Extension 2.0 [required only if building with J2SE 1.3] The JDBC 2.0 Optional Package can be obtained from: http://java.sun.com/products/jdbc/download.html Set the "jdbc2_0-stdext.jar" property in build.properties to the JDBC 2.0 Standard Extensions jar file path. --------------------------------------------------------------------------- Building the Standard tag library To build the distribution set your current directory to the 'standard' directory into which you unpacked the distribution. Build 'standard' by executing ant in a shell. Some common build targets include: > ant <-- builds the intermediate form of the library, documentation, and example targets > ant dist <-- builds all the distribution targets > ant clean <-- deletes intermediate results so that target can be rebuilt from scratch. Two directory hierarchies are created to contain the results of the build: {base.dir}/ build/ <-- Contains intermediate form results of building standard custom library dist/ <-- Contains the files that will be included in the binary distribution of the standard project The following directory and files are created when doing a build: * build/standard - Location of all directories and files built for the standard taglib. * build/standard/standard - Results of the build process (classes, jar files, tlds) * build/standard/standard-doc/ - Files used to create the standard-doc.war file * build/standard/standard-examples/ - Files used to create the standard-examples.war file. The following directory and files are created when doing a distribution build: * dist/standard/ - Location of all files built for a binary distribution of the taglib. * dist/standard/README - Information to use the binary distribution of the standard tablib. * dist/standard/javadoc/ - The javadocs * dist/standard/lib/ - The standard jar files: jstl.jar and standard.jar * dist/standard/tld/ - Directory with the Tag Lib Descriptors for the tag library. * dist/standard/standard-doc.war - Tag Library documentation war file. * dist/standard/standard-examples.war - Tag Library examples war file. * dist/standard/tld - Directory with the Tag Lib Descriptors for the tag library. --------------------------------------------------------------------------- USING THE STANDARD TAG LIBRARY See the README file of the binary distribution you have built with these instructions. --------------------------------------------------------------------------- UNIT TESTING THE STANDARD TAG LIBRARY --------------------------------------------------------------------------- OVERVIEW OF THE UNIT TEST FRAMEWORK The Unit test directory hierarchy should mimic the RI implementation hierarchy. This way, you have a mapping between the unit test and the file that it covers. If there's no appropriate mapping you can put the test in the general test directory: /test/org/apache/taglibs/standard The Test should be written using Junit Test name conventions and start with "Test*.java" Here is the Unit test directory hierarchy: / test/ conf/ <-- unit test configuration files web/ <-- unit test web application files WEB-INF/ org/ apache/ taglibs/ standard/ extra/ spath/ functions/ lang/ jstl/ resources/ tag/ common/ core/ fmt/ sql/ xml/ el/ core/ fmt/ sql/ xml/ rt/ core/ fmt/ sql/ xml/ tei/ tlv/ --------------------------------------------------------------------------- UNIT TEST BUILD ENVIRONMENT SETUP In order to build the Standard Unit Test Framework, you will need to set the following properties and download the corresponding implementation files. See the "build_sample_standard.properties" for the definitions: build.dir Base directory into which we are building the components. build.classes Base JSTL classes directory jstl.jar JSTL API jar file standard.jar JSTL implementation jar file servlet24.jar Servlet jar jsp20.jar JSP jar junit.jar JUnit jar cactus.jar Cactus jar cactus.ant.jar Cactus custom Ant tasks jar aspectjrt.jar Cactus AspectJ Language Support jar httpclient.jar Cactus httpclient jar commons-logging.jar Cactus logging jar tomcat.home Home directory where Tomcat is installed tomcat.webapps Tomcat webapps directory username Tomcat username with manager role privileges password password for the user with manager privileges web.server.host hostname for the running webserver web.server.port port for the running webserver compile.debug debug mode for compilation compile.deprecation deprecation mode for compilation compile.optimize optimization mode for compilation --------------------------------------------------------------------------- BUILDING THE UNIT TESTS Some common unit test build targets include: > ant test <-- Build, deploy and run all the tests > ant run.cactus <-- Build, deploy and run the Cactus tests > ant run.junit <-- Build, deploy and run the Junit tests The following directories and files are created when building the unit tests: To execute the build-tests.xml unit test targets directly you can do the following: > ant -f build-tests.xml Some examples of targets available in the build-tests.xml file include: > ant -f build-tests.xml props <-- Print out test environment properties > ant -f build-tests.xml undeploy <-- Manually undeploy the Cactus Tests web application > ant -f build-tests.xml deploy <-- Manually deploy the Cactus Test web application The following directories will be created when building the Unit Tests: build/ standard/ standard/ test/ WEB-INF/ classes/ ... lib/ org/ ... A Unit Test web application war file will also be created. It is located here: build/standard/standard/jstl_test.war --------------------------------------------------------------------------- UNIT TEST RUNTIME SETUP You will need to have the Tomcat manager administration application enabled in order to run the tests. The Unit Test build file uses the Tomcat manager to automatically deploy and undeploy the Cactus tests. The following runtime properties need to be properly set in order to successfully run the unit tests: tomcat.webapps Tomcat webapps directory username Tomcat username with manager role privileges password password for the user with manager privileges web.server.host hostname for the running webserver web.server.port port for the running webserver The Tomcat manager application may sometimes get into an unstable state after many web application deployments and undeployments. If the Cactus tests start failing for unknown reasons, stop your web container and clean out your work directory before restarting. ---------------------------------------------------------------------------