Skip Headers

Oracle® Application Server Containers for J2EE Servlet Developer's Guide 10g Release 2 (10.1.2) B14017-02 |
| Library | Product | Contents | Index

Previous | Next |

# A Open Source Fra meworks and Utilities

There are common open source frameworks and utilities that you can use with OC4J in Oracle Application Server 10g Release 2 (10.1.2). This appendix describes how to configure and use two of them in particular: Jakarta Strut and Jakarta log4j.

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. In 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 employing these frameworks, use the regular forums available in the open source community. The documentation here discusses particular versions of Struts and log4j, but the general framework of what is discussed applies to later versions as well.

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

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

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

Note: The following sections show steps for using the 1.0.2 Struts version, but you can deploy newer Struts versions to OC4J using the same general steps. Note that later versions have additional functionality, so likely include additional library files.

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

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

Note: Additional steps are required to use Struts within your applications. You must also create the Action classes and other components used by Struts at runtime and 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://struts.apache.org/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 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

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 save it to your local file system.

Note: The following sections show steps for using the 1.2.8 log4j version, but you can deploy newer log4j versions to OC4J using the same general steps.

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

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

To install the log4j library at a global application level in OC4J, copy the log4j JAR file (`log4j-1.2.8.jar`, for example) from the log4j `lib` directory to the `j2ee/home/applib` directory. By default, a `<library>` element in the `j2ee/home/config/application.xml` global application descriptor makes this directory available for libraries that are to be shared between all applications deployed to the OC4J instance. At runtime, OC4J automatically loads all libraries in the `applib` directory. 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-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, do not use the `applib` directory. Do not use the `applib` directory for log4j in an Oracle Application Server environment. Oracle Enterprise Manager 10g also uses log4j, and placing your copy at the global application level may 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 JAR file (`log4j-1.2.8.jar`, for example) from the log4j `lib` directory into the `/WEB-INF/lib` directory of your Web application. At runtime, the servlet container makes the log4j library available to the Web application through a Web application classloader. 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-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

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

By default, log4j uses a configuration file named `log4j.properties` or `log4j.xml` to determine its logging behavior. It automatically attempts to load these files from the classloaders available to it at runtime. If it finds both files, then `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 includes, 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 install 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, then the log4j logger is initialized separately for each Web application. This enables you to use separate automatic log4j configuration files for each Web application.

#### 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 loads the URL directly and uses that as the configuration file.

If the specified value is not a correctly formed URL, log4j uses 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 tries 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 tries 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, although 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 tries to load `barfoo.xml` from the same directory from which 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 process 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 a good practice to place files that define behavior, and that should not be accessible to clients from an HTTP request, directly into the `/WEB-INF` directory of the Web application. (Do not use a subdirectory of `/WEB-INF`.) This applies to `log4j.xml`, for example. The servlet specification requires contents of the `/WEB-INF` 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 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].

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.