A Open Source Frameworks and Utilities

Overview of Jakarta Struts

Jakarta Struts is an open source framework to assist with the development of Web applications using open standards such as Java servlets, JavaServer Pages, and XML. Struts supports a modular application development model based on the Model-View-Controller (MVC) pattern. With Struts, you can create an extensible development environment for your application, based on industry standards and proven design models.

The sections that follow describe how to install the Struts libraries, documentation, and sample applications in an OC4J standalone environment. This document does not cover how to build applications with Struts. See the user guide, installation guide, and other documentation on the Struts Web site, including the following locations:

http://struts.apache.org

http://struts.apache.org/learning.html

Downloading the Struts Binary Distribution

Struts distributions are available through the following location:

http://struts.apache.org/

Download the archive file from this location, choosing the appropriate format (ZIP file or compressed TAR file) for your platform, and save it to your local file system.

Unpacking the Struts Binary Distribution

Use the appropriate tool for your platform, such as WinZip or TAR, to unpack the archive file of the Struts binary distribution that you downloaded. This creates a directory structure such as the following (for the Struts 1.0.2 release):

jakarta-struts-1.0.2/INSTALL
jakarta-struts-1.0.2/LICENSE
jakarta-struts-1.0.2/README

jakarta-struts-1.0.2/lib/jdbc2_0-stdext.jar
jakarta-struts-1.0.2/lib/struts.jar
jakarta-struts-1.0.2/lib/struts.tld
jakarta-struts-1.0.2/lib/struts-bean.tld
jakarta-struts-1.0.2/lib/struts-config_1_0.dtd
jakarta-struts-1.0.2/lib/struts-form.tld
jakarta-struts-1.0.2/lib/struts-html.tld
jakarta-struts-1.0.2/lib/struts-logic.tld
jakarta-struts-1.0.2/lib/struts-template.tld
jakarta-struts-1.0.2/lib/web-app_2_2.dtd
jakarta-struts-1.0.2/lib/web-app_2_3.dtd

jakarta-struts-1.0.2/webapps/struts-blank.war
jakarta-struts-1.0.2/webapps/struts-documentation.war
jakarta-struts-1.0.2/webapps/struts-example.war
jakarta-struts-1.0.2/webapps/struts-exercise-taglib.war
jakarta-struts-1.0.2/webapps/struts-template.war
jakarta-struts-1.0.2/webapps/struts-upload.war

Installing and Accessing Struts Documentation

The Struts documentation is supplied as a Web application in a WAR file in the webapps directory of the Struts archive. Use steps such as the following, adjusted as appropriate for the particular Struts version you choose, to deploy the Struts documentation Web application to the OC4J default application.

Configuration files are in the j2ee/home/config directory.

1. In the OC4J global application descriptor, application.xml, add a new <web-module> element for the struts-documentation.war file. Place this element after any <web-module> elements already in the file.

   Specify the path to the directory in which the Struts binary distribution was extracted. Here is a sample entry:

   <orion-application ... >
      ...
      <web-module id="struts-documentation"
      path="your_path/jakarta-struts-1.0.2/webapps/struts-documentation.war" />
   ...
   </orion-application>
   
   

2. In the Web site XML file, http-web-site.xml, add a new <web-app> element to bind the documentation Web application to a URL context path. Place this element after any <web-app> elements already in the file. Here is a sample entry specifying /struts/doc as the URL context path for the Struts documentation:

   <web-site ... >
      ...
      <web-app application="default" name="struts-documentation"
               root="/struts/doc" />
      ...
   </web-site>
   
   

   Note the application="default" setting to use the OC4J default application. Any Web application deployed to OC4J must be contained in a J2EE application. Typically, this is accomplished by packaging the Web application WAR file inside a J2EE application EAR file. For convenience, however, you can use an OC4J default application in deploying a standalone WAR file, as in this case.

3. Start OC4J from the command line:

   % java -jar oc4j.jar
   
   

   You will see output similar to the following:

   Auto-unpacking /java/jakarta-struts-1.0.2/webapps/struts-documentation.war
   ... done.
   Oracle Application Server (10.1.2.0.0) Containers for J2EE initialized
   
   

   Unpacking struts-documentation.war results in the creation and population of the struts-documentation directory and subdirectories under the jakarta-struts-1.0.2/webapps directory.

4. Access the documentation according to the URL context path you specified in http-web-site.xml:

   http://host:8888/struts/doc
   
   

   The Struts documentation welcome page appears.

Installing the Struts Sample Web Application

The Struts binary distribution also provides a sample Web application in a WAR file in the webapps directory. As with the documentation Web application, you can deploy the Struts sample Web application to the OC4J default application. Use steps such as the following, adjusted as appropriate for the particular Struts version you choose. Configuration files are in the j2ee/home/config directory.

1. In the OC4J global application descriptor, application.xml, add a new <web-module> element for the struts-example.war file. Specify the path to the directory in which the Struts binary distribution was extracted. Here is a sample entry:

   <web-module id="struts-example"
      path="your_path/jakarta-struts-1.0.2/webapps/struts-example.war" />
   
   

   Place this immediately after the <web-module> element you created for struts-documentation.war.

2. In the Web site XML file, http-web-site.xml, add a new <web-app> element to bind the sample Web application to a URL context path. Here is a sample entry that specifies /struts/example as the URL context path for the Struts documentation:

   <web-app application="default" name="struts-example" 
            root="/struts/example" />
   
   

   Place this immediately after the <web-app> element you created for the documentation Web application.

   As with the documentation Web application, the application="default" setting uses the OC4J default application to contain the sample Web application.

3. Start OC4J from the command line:

   % java -jar oc4j.jar
   
   

   You will see output similar to the following:

   Auto-unpacking /java/jakarta-struts-1.0.2/webapps/struts-example.war
   ...done.
   Oracle Application Server (10.1.2.0.0) Containers for J2EE initialized
   
   

   Unpacking struts-example.war results in the creation and population of the struts-example directory and subdirectories under the jakarta-struts-1.0.2/webapps directory.

4. Access the sample Web application according to the URL context path you specified in http-web-site.xml:

   http://host:8888/struts/example
   
   

   The Struts sample application welcome page appears.

Deploying Your Own Application with the Struts Framework

When deploying your own applications using the Struts framework, you must package the Struts library artifacts within your own WAR file and configure the standard web.xml deployment descriptor with the required entries for the Struts components. Your Web application will be constructed and packaged as a WAR file.

Use steps such as the following, adjusted as appropriate for the particular Struts version you choose.

1. Copy the Struts library from the Struts lib directory to the /WEB-INF/lib directory of your application. The following example is for a UNIX environment (from the directory in which you unpacked the archive file), where "%" is the system prompt:

   % cp jakarta-struts-1.0.2/lib/struts.jar web-inf/lib
   
   

2. Copy the Struts tag library descriptor files (all .tld files, for JSP tag libraries) from the Struts lib directory to your /WEB-INF directory:

   % cp jakarta-struts-1.0.2/lib/*.tld web-inf 
   
   

   
   

   Note: These steps, using a JSP 1.1 methodology, describe only one way to access JSP tag library descriptor files. Other options are available in a JSP 1.2 environment such as in OC4J. See the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information.

   
   

3. Add Struts servlet and tag library entries to the web.xml file.

   1. Add the servlet definition element for the Struts controller. (You can optionally specify an application-wide MessageResource file to use, the name and location of the Struts configuration file, and additional properties such as debugging levels.) The <servlet> element is a subelement of the top-level <web-app> element.

      <servlet>
        <servlet-name>action</servlet-name>
        <servlet-class>org.apache.struts.action.ActionServlet</servlet-class>
        <init-param>
          <param-name>application</param-name>
          <param-value>ApplicationResources</param-value>
        </init-param>
        <init-param>
          <param-name>config</param-name>
          <param-value>/WEB-INF/struts-config.xml</param-value>
        </init-param>
      </servlet> 
      
      

   2. Add a servlet mapping element for the Struts controller servlet. This step maps the servlet name (mapped to the servlet class in the <servlet> element above) to a URL servlet path. The <servlet-mapping> element is a subelement of the top-level <web-app> element.

      <servlet-mapping>
        <servlet-name>action</servlet-name>
        <url-pattern>*.do</url-pattern>
      </servlet-mapping>
      
      

   3. Add entries for the Struts tag libraries. These entries assume the TLD files were placed in the /WEB-INF directory as shown in Step 2. The <taglib> element is a subelement of the top-level <web-app> element.

      <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-html.tld</taglib-uri>
        <taglib-location>/WEB-INF/struts-html.tld</taglib-location>
      </taglib>
      
      <taglib>
        <taglib-uri>/WEB-INF/struts-logic.tld</taglib-uri>
        <taglib-location>/WEB-INF/struts-logic.tld</taglib-location>
      </taglib>
      
      

You now have a Web application that can support the deployment of applications that utilize the Struts framework.

After the remainder of the Web application—including JSP pages, servlets, Struts components, and other files—has been added to the WAR file, the application can be deployed to OC4J.

http://struts.apache.org/learning.html

Overview of Jakarta log4j

The log4j framework is an open source project that provides an efficient and flexible API to support runtime logging operations for Java applications. It enables developers to insert log statements into their code, incorporating messages at different levels of alarm as desired. Log4j also enables system administrators to separately define the level of logging they wish to see from the application at runtime, without requiring changes to the supplied application code.

Features of log4j allow you to enable logging at runtime without having to modify the application binary file. Statements can remain in shipped code without incurring significant performance cost. Logging is controlled through a configuration file without requiring changes to the application binary.

The sections that follow describe how to install the log4j library and configure it for use with OC4J. Use of the extensive log4j API is not OC4J-specific, so is not covered in this document. See the documentation on the official log4j Web site, including the following locations:

http://jakarta.apache.org/log4j/docs/index.html

http://jakarta.apache.org/log4j/docs/documentation.html

Downloading the log4j Binary Distribution

The log4j distribution is available at the following location:

http://jakarta.apache.org/log4j/docs/download.html

Download the archive file from this location, choosing the appropriate format (ZIP file or compressed TAR file) for your platform, and save it to your local file system.

Unpacking the log4j Binary Distribution

Use the appropriate tool for your platform, such as WinZip or TAR, to unpack the log4j archive file that you downloaded. This creates and populates a directory structure such as the following:

jakarta-log4j-1.2.8/
   build/
   contrib/
      ...
   dist/
      classes/
         ...
      lib/
   docs/
      ...
   examples/
      ...
   src/
      ...

(Some of the directory structure is not shown; there are many further subdirectories.)

Installing the log4j Library

To enable J2EE applications to use log4j functionality, the log4j library must be made available by the classloaders of OC4J. You can accomplish this in several ways, depending on your specific operational requirements. For example, you can install the log4j library at a system or global application level, making it available to all applications deployed to the container. Alternatively, you can package the log4j library as a library of a specific application (or applications). Different approaches have different operating characteristics, such as the way in which the automatic loading of configuration files works. For more details about possible approaches and their advantages and disadvantages, refer to the log4j Web site and user mailing lists.

The following sections cover three techniques to make log4j available to OC4J:

• Use the log4j Library at a Global Application Level

• Package the log4j Library as a Web Application Library

• Package the log4j Library as a Shared Library for EJB and Web Applications

% cp jakarta-log4j-1.2.8/dist/lib/log4j-1.2.8.jar j2ee/home/applib

% cp jakarta-log4j-1.2.8/dist/lib/log4j-1.2.8.jar web-inf/lib

Package the log4j Library as a Shared Library for EJB and Web Applications

When you have an application that comprises EJB components and Web components that all use log4j, you can package the log4j library as a single shared library that both sets of components can use.

The J2EE classloading mechanism implies that a Web application deployed within the same EAR file as an EJB application has access to classes available in the EJB classloader. Making log4j a library of the EJB application also makes it a library of the Web application.

The EJB classloader, as well as the Web classloader, can access any libraries specified in the Class-Path attribute of the META-INF/Manifest.mf file of the EAR file. The library JAR files are loaded relative to the file (such as the EAR file) with the Class-Path entry, so they are stored in the same directory as that file. Using this facility, it is possible to place the log4j JAR file in the same directory as the EJB JAR file and reference it in the manifest file as a required library. This also makes the log4j library accessible to the Web applications inside the same EAR file, because they have visibility of the classes of the EJB components.

Figure A-1 illustrates the classloading hierarchy for a J2EE application.

Figure A-1 J2EE Classloading Hierarchy

Description of "Figure A-1 J2EE Classloading Hierarchy"

Using log4j Configuration Files

The log4j framework enables you to control logging behavior through settings specified in an external configuration file, allowing you to make changes to the logging behavior without modifying application code.

There are three common ways to use the external configuration files. Each approach defines what the configuration files are named and how they are located by the J2EE application server at runtime.

The following sections describe the three approaches:

• Use the Default Files for Automatic log4j Configuration

• Use Alternative Files for Automatic log4j Configuration

• Programmatically Specify External Configuration Files

% java -Dlog4j.configuration=url

% java -Dlog4j.debug=true -Dlog4j.configuration=file:///d:\temp\foobar.xml 
       -jar oc4j.jar

% java -Dlog4j.debug=true -Dlog4j.configuration=foobar.xml -jar oc4j.jar

public void init(ServletContext context) throws ServletException
{
  // Load the barfoo.xml file as the log4j external configuration file.
  DOMConfigurator("barfoo.xml");
  logger = Logger.getLogger(Log4JExample.class);
}

<context-param>
  <param-name>log4j-config-file</param-name>
  <param-value>/web-inf/classes/app2-log4j-config.xml</param-value>
</context-param>

public void init(ServletContext context) throws ServletException
{
  /*
   * Read the path to the config file from the web.xml file,
   * should return something line /web-inf/xxx.xml or web-inf/classes/xxx.xml.
   */
  String configPath = context.getInitParameter("log4j-config-file");

  /*
   * This loads the file based on the base directory of the web application
   * as it is deployed on the application server.
   */
  String realPath = context.getRealPath(configPath);
   if(realPath!=null)
   DOMConfigurator.configure(realPath);
  _logger = Logger.getLogger(Log4JExample.class);
}

Enabling log4j Debug Mode

When deploying an application on OC4J that uses log4j and external configuration files, it is sometimes helpful to view how log4j is trying to find and load the requested configuration files. To facilitate this, log4j provides a debug mode that displays how it is loading (or attempting to load) its configuration files.

To turn on log4j debug mode, specify an additional runtime property when you start OC4J, as follows (where "%" is the system prompt):

% java -Dlog4j.debug=true -jar oc4j.jar

OC4J displays output similar to the following:

Oracle Application Server (10.1.2.0.0) Containers for J2EE initialized
log4j: Trying to find [log4j.xml] using context classloader [ClassLoader:
[[D:\myprojects\java\log4j\app1\webapp1\WEB-INF\classes],
[D:\myprojects\java\log4j\app1\webapp1\WEB-INF\lib/log4j-1.2.7.jar]]].
log4j: Using URL [file:/D:/myprojects/java/log4j/app1/webapp1/WEB-INF/classes/
log4j.xml] for automatic log4j configuration.
log4j: Preferred configurator class: org.apache.log4j.xml.DOMConfigurator
log4j: System property is :null
log4j: Standard DocumentBuilderFactory search succeded.
log4j: DocumentBuilderFactory is: oracle.xml.jaxp.JXDocumentBuilderFactory
log4j: URL to log4j.dtd is [classloader:/org/apache/log4j/xml/log4j.dtd].
log4j: debug attribute= "null".
log4j: Ignoring debug attribute.
log4j: Threshold ="null".
log4j: Level value for root is  [debug].
log4j: root level set to DEBUG
log4j: Class name: [org.apache.log4j.FileAppender]
log4j: Setting property [file] to [d:/temp/webapp1.out].
log4j: Setting property [append] to [false].
log4j: Parsing layout of class: "org.apache.log4j.PatternLayout"
log4j: Setting property [conversionPattern] to [%n%-5p %d{DD/MM/yyyy}
d{HH:mm:ss} [%-10c] [%r]%m%n].
log4j: setFile called: d:/temp/webapp1.out, false
log4j: setFile ended
log4j: Adding appender named [FileAppender] to category [root].