Copyright : This page is largely inspired from the original Struts installation page. For those familiar with Struts, there is nothing really new.

In order to build a Components source distribution, or install and use a Components binary distribution, you will need to acquire and install several other software packages, as follows:

• Java Development Kit - You must download and install a Java2 (version 1.2 or later) Java Development Kit implementation for your operating system platform. A good starting point for locating Java Development Kit distributions is http://java.sun.com/j2se .
• Servlet Container - You must download and install a servlet container that is compatible with the Servlet API Specification, version 2.2 or later, and the JavaServer Pages (JSP) Specification, version 1.1 or later. One popular choice is to download Apache's Tomcat (version 3.1 or later required, version 3.2 or later recommended).
• Ant Build System - If you are building Components from the source distribution, you must download and install version 1.2 or later of the Ant build system. This package is also strongly recommended for use in developing your own web applications based on Struts.
  • If you are using the release version of Ant version 1.2, you will also need to download the "optional.jar" file that contains the implementation of Ant's <style> command.
• Servlet API Classes - In order to compile Components itself, or applications that use Components, you will need a servlet.jar file containing the Servlet and JSP API classes. Most servlet containers include this JAR file. Otherwise, you can get the Servlet API classes distribution from here .  
• XML Parser - Components requires the presence of an XML parser that is compatible with the Java API for XML Parsing (JAXP) specification, 1.0 or later. You can download and install the JAXP reference implementation , which is required for building the Components source distribution. In Struts-based web applications, you may replace the reference implementation classes with any other JAXP compliant parser, such as Xerces . See detailed instructions related to the parser in the instructions for building and installing Components, below.
• Xalan XSLT Processor - If you are building Components from the source distribution, you must download and install version 1.2 (problems have been reported with current versions of Xalan 2.0) of the Xalan XSLT processor (which also includes the Xerces XML parser), or use the version of Xalan included in the JAXP 1.1 release. This processor is used to convert the Components documentation from its internal XML-based format into the HTML that is presented in the Components documentation application.

First, download a source distribution of Components by following the instructions here . Then, make sure you have downloaded and installed all of the prerequisite software packages described above.

To build Components, you will need to customize your development environment as follows:

• Set an environment variable ANT_HOME that contains the absolute pathname of the directory where you installed Ant.
• Set an environment variable JAVA_HOME that contains the absolute pathname of the directory where you installed your Java Development Kit.
• Set an environment variable SERVLETAPI_HOME that contains the absolute pathname of the directory where you installed the Servlet API distribution (not required if you have servlet.jar on your CLASSPATH already).

To build a "distribution" version of Components, first change your current directory to the directory in which you have unpacked the Components source distribution, and then type one of the following commands (based on whether you are running on a Unix or Windows platform):

            ./build.sh dist    <-- Unix platform
            build dist         <-- Windows platform
          

This command will create a binary distribution of Components, in a directory named dist (relative to where you are compiling from). This directory contains an exact replica of the files included in a binary distribution of Components, as described in the following section.

First, download a binary distribution of Components by following the instructions here . Then, make sure you have downloaded and installed all of the prerequisite software packages described above.

Unpack the Components binary distribution into a convenient directory. (If you build Components from the source distribution, the result of the build will already be an unpacked binary distribution for you). The distribution consists of the following contents:

• lib/components.jar - This JAR file contains all of the Java classes included in Components. It should be copied into the WEB-INF/lib directory of your web application.
• lib/tiles.tld - This is the "tag library descriptor" file that describe the custom tags in the various Components tag libraries. They should be copied into the WEB-INF directory of your web application.
• webapps/comps-doc.war - This is a "web application archive" file containing all of the Components documentation found on the Components web site (including these pages). You can install this web application on any servlet container compatible with Servlet API 2.2 or later.
• webapps/comps-tutorial.war - This is examples from the Components tutorial that uses a large percentage of Components features. You can install this web application on any servlet container compatible with the Servlet 2.2 (or later) and JSP 1.1 (or later) specifications.
• webapps/comps-template.war - This web application both introduces and demonstrates the Components template tags.  This is the original Struts template application revisited with Components.

To use Components in your own application, you will need to follow these steps:

• Install Struts library.
• Copy the file lib/components.jar from the Components distribution into the WEB-INF/lib directory of your web application.
• Copy the file that match lib/tiles.tld from the Components distribution into the WEB-INF directory of your web application.
• Copy the file struts.jar from the Struts distribution into the WEB-INF/lib directory of your web application.
• Copy the file that match struts-*.tld from the Struts distribution into the WEB-INF directory of your web application.
• Modify the WEB-INF/web.xml file for your web application to include a <servlet> element to define the controller servlet, and a <servlet-mapping> element to establish which request URIs are mapped to this servlet. Use the WEB-INF/web.xml file from the Components tutorial application for a detailed example of the required syntax.
• Modify the WEB-INF/web.xml file of your web application to include the following tag library declarations:

            <taglib>
            <taglib-uri>/WEB-INF/struts-bean.tld</taglib-uri>
            <taglib-location>/WEB-INF/struts-bean.tld</taglib-location>
            </taglib>
            
            <taglib>
            <taglib-uri>/WEB-INF/struts-form.tld</taglib-uri>
            <taglib-location>/WEB-INF/struts-form.tld</taglib-location>
            </taglib>
            
            <taglib>
            <taglib-uri>/WEB-INF/struts-logic.tld</taglib-uri>
            <taglib-location>/WEB-INF/struts-logic.tld</taglib-location>
            </taglib>
            
            <taglib>
            <taglib-uri>/WEB-INF/tiles.tld</taglib-uri>
            <taglib-location>/WEB-INF/tiles.tld</taglib-location>
            </taglib>
          

• If you want to use centralized definitions, use the modified version of ActionServlet , by adding following lines in the WEB-INF/web.xml file :
<servlet>
    <servlet-name>action</servlet-name>
    <servlet-class>org.apache.struts.tiles.ActionComponentServlet</servlet-class
    <init-param>
      <param-name>instances-config</param-name>
      <param-value>/WEB-INF/componentInstances.xml</param-value>
    </init-param>
...
 
• If you use centralized definitions , but don't want to use modified servlet, you must initialize instances list, either in your own servlet (see ComponentActionServlet.java) or at begining of page (see tags).
• If you use centralized definitions , create a file WEB-INF/templateDefinitions.xml that defines the instances of your Components. You can use the templateDefinitions.xml file from the Components tutorial application for a detailed example of the required syntax.
• At the top of each JSP page that will use the Components custom tags, add line(s) declaring the Components custom tag libraries used on this particular page, like this:

  <@ taglib uri="/WEB-INF/tiles.tld" prefix="comps" %>

• If you want to use Components library in place of templates library, you can do this by replacing previous line by this:

  <@ taglib uri="/WEB-INF/tiles.tld" prefix="template" %>

• When compiling the Java classes that comprise your application, be sure to include the components.jar file (copied earlier) on the CLASSPATH that is submitted to the compiler.

For most containers, you need only to:

• Copy the WAR files in your Components /webapp directory to your containers webapps directory.
• In some cases, you may need to restart your container if it is running.

Status of various containers

• Tomcat 3.1 and prior - Not recommended. Use Tomcat 3.2.1 or later.
• Tomcat 3.2.1+ "standalone" - No additional steps required.
• Resin 2.1+ "standalone" - No additional steps required.
• WebLogic 6.0+ - No additional steps required.

• Bluestone Universal Business Server - Additional steps required, see struts pages.
• JRUN - Additional steps required, see struts pages.
• Orion Application Server - Additional steps required, see struts pages.
• Silverstream - - Additional steps required, see struts pages.
• Tomcat 3.2.1 with Apache - Additional steps required, see struts pages.
• Weblogic 5.1 (sp8) - Additional steps required, see struts pages.
• WebSphere - Additional steps required, see struts pages.