Skip Headers

Oracle Application Server Containers for J2EE Servlet Developer's Guide 10g (9.0.4) Part Number B10321-01 |
Home | Contents | Index

# A
Open Source Frameworks and Utilities

There are common open source frameworks and utilities that you can use with OC4J. For Oracle Application Server 10g (9.0.4), this appendix describes how to configure and use two of them in particular: Jakarta Struts 1.0.2 and Jakarta log4j 1.2.8.

The focus of this discussion is to assist you in configuring and using these open source utilities in the OC4J standalone environment. The following sections cover the details:

- Configuration and Use of Jakarta Struts in OC4J

- Configuration and Use of Jakarta log4j in OC4J

Important: The packaging and configuration instructions in this document are written for an OC4J standalone installation. If you are using an Oracle Application Server installation, use the management tools provided, such as Enterprise Manager and the `dcmctl` command line utility, to accomplish the same tasks. Avoid manual modifications to configuration files in an Oracle Application Server environment. The open source utilities and frameworks discussed here are not supported directly by Oracle. In addition, there has been no formal testing or certification of these utilities and frameworks with the OC4J product. For assistance in using these frameworks, use the regular forums available in the open source community.

## Configuration and Use of Jakarta Struts in OC4J

The following sections cover steps for using Jakarta Struts in an OC4J standalone environment:

- Overview of Jakarta Struts

- Downloading the Struts Binary Distribution

- Unpacking the Struts Binary Distribution

- Installing and Accessing Struts Documentation

- Installing the Struts Sample Web Application

- Deploying Your Own Application with the Struts Framework

Note: Oracle JDeveloper includes a wizard that simplifies Struts usage.

### Overview of Jakarta Struts

Jakarta Struts is an open source framework designed 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.

Following sections 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. Please see the user guide, installation guide, and other documentation on the official Struts Web site, including the following locations:

    http://jakarta.apache.org/struts

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

    http://jakarta.apache.org/struts/installation.html

Note: Struts is part of the Apache Jakarta Project, sponsored by the Apache Software Foundation.

### Downloading the Struts Binary Distribution

The Struts 1.0.2 distribution is available at the following location:

    http://jakarta.apache.org/builds/jakarta-struts/release/v1.0.2/

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

Note: The Struts 1.1 Beta releases can be deployed on OC4J in the same manner as the 1.0.2 release. With the increased functionality in Struts 1.1, a number of additional library files are supplied with the distribution. The instructions given here should generally apply to deploying an application using Struts 1.1, aside from the addition of the new library files and the specification of additional tag libraries.

### 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 1.0.2 binary distribution that you downloaded. This will create the following directory structure:

    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. You can use the following steps 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. You can place this element after any `<web-module>` elements already in the file.

   Specify the path to the directory where 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. You can 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, there is an OC4J default application that you can use 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 such as the following:

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

   Unpacking `struts-documentation.war` results in 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://your_host:8888/struts/doc

   You will see the following welcome page for the Struts documentation:

Text description of the illustration strutdoc.gif

### 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 the following steps. 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 where 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" />

   You can 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" />

   You can 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 such as the following:

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

   Unpacking `struts-example.war` results in 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://your_host:8888/struts/example

   You will see the following welcome page for the Struts sample application:

Text description of the illustration strutexa.gif

### 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.

Note: A good example of a WAR file configured to use Struts is provided in the `webapps` folder of the Struts archive file as `struts-blank.war`. This serves as a useful template when constructing your own Web applications.

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 where 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: This is only one way to access JSP tag library descriptor files, using a JSP 1.1 methodology. 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.

1. 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 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>

Upon completion of these steps, you have a Web application that can support the deployment of applications that utilize the Struts framework.

Once the rest 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.

Note: This is not a complete listing of steps required to use Struts within your applications. Developers are also required to create the Action classes and other components used by Struts at runtime, and to make corresponding entries in the Struts configuration file, `struts-config.xml`. These points are not OC4J-specific and are beyond the scope of this document. See the learning guide on the Struts Web site for more information:
    http://jakarta.apache.org/struts/learning.html

## Configuration and Use of Jakarta log4j in OC4J

The following sections cover considerations for using Jakarta log4j in an OC4J standalone environment:

- Overview of Jakarta log4j

- Downloading the log4j Binary Distribution

- Unpacking the log4j Binary Distribution

- Installing the log4j Library

- Using log4j Configuration Files

- Enabling log4j Debug Mode

### Overview of Jakarta log4j

The log4j framework is an open source project designed to provide 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. It 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.

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. Please 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

Note: The log4j framework is part of the Apache Jakarta Project, sponsored by the Apache Software Foundation.

### 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 saving 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 will create and populate the following directory structure:

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

(This does not show the entire structure; 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. This can be accomplished in a variety of ways, depending on your specific operational requirements. For example, the log4j library can be installed at a system or global application level, making it available to all applications deployed to the container. Alternatively, the log4j library can be packaged 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:

1. Use the log4j Library at a Global Application Level

2. Package the log4j Library as a Web Application Library

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

#### Use the log4j Library at a Global Application Level

To install the log4j library at a global application level in OC4J, copy the `log4j-1.2.8.jar` file from the log4j `lib` directory to the `j2ee/home/applib` directory. By default, this directory is available for libraries that are to be shared between all applications that are deployed to the OC4J instance. This is accomplished through a `<library>` element in the `j2ee/home/config/application.xml` global application descriptor. At runtime, OC4J automatically loads all libraries in the `applib` directory. The following example is for a UNIX environment (from the directory where you unpacked the archive file), where "`%`" is the system prompt:

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

Notes: Be aware of the overhead in using this approach. If you do not want the log4j library to always be loaded, then you should not use the `applib` directory. Do not use the `applib` directory for log4j in an Oracle Application Server environment. Oracle Enterprise Manager also uses log4j, and placing your copy at the global application level might cause version conflicts for Enterprise Manager.

#### Package the log4j Library as a Web Application Library

To package the log4j library for a specific Web application, copy the `log4j-1.2.8.jar` file from the log4j `lib` directory into the `/WEB-INF/lib` directory of your Web application. At runtime, the servlet container will make the log4j library available to the Web application through a Web application classloader.

The following example is for a UNIX environment (from the directory where you unpacked the archive file), where "`%`" is the system prompt:

    % 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 consists of both EJB components and Web components and they all use log4j, you can package the log4j library as a single shared library which can be used by both sets of components.

The J2EE classloading mechanism implies that a Web application that is deployed within the same EAR file as an EJB application has access to classes available in the EJB classloader. This means that by making log4j a library of the EJB application, it also becomes a library of the Web application.

The EJB classloader, as well as the Web classloader, can access any libraries that are 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 would be stored in the same directory. 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 will also make 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

Text description of the illustration clldhier.gif

### Using log4j Configuration Files

The log4j framework enables you to control the logging behavior through settings specified in an external configuration file. The enables 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:

1. Use the Default Files for Automatic log4j Configuration

2. Use Alternative Files for Automatic log4j Configuration

3. Programmatically Specify External Configuration Files

#### Use the Default Files for Automatic log4j Configuration

By default, log4j will use a configuration file named `log4j.properties` or `log4j.xml` to determine its logging behavior. It will automatically attempt to load these files from the classloaders available to it at runtime. If it finds both, `log4j.xml` takes precedence.

To use an automatic configuration file, place it in a directory location that falls within the classpath used by OC4J. This would include, in order of loading precedence:

1. Global application level: `j2ee/home/applib`

2. Web application level: `/WEB-INF/classes`

Note: A log4j runtime is configured only once using the automatic configuration files when the first call is made to the `org.apache.log4j.Logger` class. If you have installed the log4j library at the global application level by placing it in the `j2ee/home/applib` directory, then you can use only one automatic configuration file to define all the log levels, appenders, and other log4j properties for all the applications running on your server. If you install the log4j library separately for each Web application, in each `/WEB-INF/lib` directory, the log4j logger is initialized separately for each Web application. This enables you to use separate automatic log4j configuration files for each Web application. Visit the following log4j site and see the log4j user mailing list for more information:
    http://www.mail-archive.com/log4j-user@jakarta.apache.org/

#### Use Alternative Files for Automatic log4j Configuration

You can choose alternative file names instead of using the default names for automatic configuration of log4j. To do this, specify an additional runtime property when OC4J is started, as follows, where "`%`" is the system prompt and `url` designates the location of the configuration file to use:

    % java -Dlog4j.configuration=url

If the specified value for the `log4j.configuration` property is a fully formed URL, log4j will load the URL directly and use that as configuration file.

If the specified value is not a correctly formed URL, log4j will use the specified value as the name of the configuration file to load from the classloaders it has available.

For example, assume OC4J is started as follows (where this is a single wraparound command line):

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

In this case, log4j will try to load the file `d:\temp\foobar.xml` as its configuration file.

As another example, assume OC4J is started as follows:

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

In this case, log4j will try to load `foobar.xml` from the classloaders it has available. This works in the same manner as using the default automatic configuration file `log4j.xml`, but using the specified file name instead.

Note: This approach, while offering an additional level of flexibility, does require all external configuration files for all deployed applications to have the same name.

#### Programmatically Specify External Configuration Files

Instead of relying on the automatic configuration file loading mechanism, some applications use a programmatic approach to load the external configuration file. In this case, the path to the configuration file is supplied directly within the application code. This allows different file names to be used for each application. The log4j utility loads and parses the specified configuration file (either an XML document or a properties file) to determine required logging behavior.

Here is an example:

    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);
    }

In this case, log4j will try to load `barfoo.xml` from the same directory where OC4J was started.

Using the programmatic approach provides the most flexibility to developers and system administrators. A configuration file can be of any arbitrary name and be loaded from any location. System administrators can still make changes to the logging behavior without requiring application code changes through the external configuration file.

To provide even further flexibility, and to avoid coding a specific name and location into an application, a useful technique is to supply the file name and location as parameters inside the standard `web.xml` deployment descriptor. The servlet or JSP page reads the values of the parameters specifying the location and name of the configuration file, and dynamically constructs the location from which to load the configuration file. This allows system administrators to choose both the name and location of the configuration file to use.

Here is a sample web.xml entry specifying the name and location of the configuration file:

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

The application reads the location value from the deployment descriptor, constructs a full path to the file on the local file system, and loads the file. Following is some sample code:

    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);
    }

Note: It is generally a good practice to place files that define behavior, and which should not be accessible to clients from an HTTP request, directly into the `/WEB-INF` directory (not a subdirectory) of the Web application. This would apply to `log4j.xml`, for example. The servlet specification requires contents of this directory to be inaccessible to clients.

### 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 where it 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 will display output similar to the following:

    Oracle Application Server (9.0.4.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].

Note: You can also use the `debug` attribute of the `log4j:configuration` tag in an external configuration file to enable debug output. However, this does not display the loading operations that take place, so does not offer the best service for resolving problems in loading configuration files.

| Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
Home | Contents | Index