|
Oracle® Application Server Containers for J2EE Servlet Developer's Guide
10g Release 2 (10.1.2) Part No. B14017-01 |
|
 Previous |
 Next |
|
Oracle® Application Server Containers for J2EE Servlet Developer's Guide
10g Release 2 (10.1.2) Part No. B14017-01 |
|
|
Previous |
Next |
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 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 log4j in OC4J
|
Important:
|
The following sections cover steps for using Jakarta Struts in an OC4J standalone environment:
|
Note: Oracle JDeveloper includes a wizard that simplifies Struts usage. |
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 official Struts Web site, including the following locations:
http://jakarta.apache.org/strutshttp://jakarta.apache.org/struts/learning.html
|
Note: Struts is part of the Apache Jakarta Project, sponsored by the Apache Software Foundation. |
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 save it to your local file system.
|
Note: You can deploy the Struts 1.1 Beta releases to OC4J using the same steps as in deploying the 1.0.2 release. Due to the increased functionality in Struts 1.1, additional library files are supplied with the distribution. The instructions given here generally apply to deploying an application using Struts 1.1, aside from the additional library files and tag libraries in Struts 1.1. |
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 creates 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
The Struts documentation is supplied as a Web application in a WAR file in the webapps directory of the Struts archive. 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.
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>
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.
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.
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, as in the following graphic:
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.
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.
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.
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.
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, as in the following graphic:
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 thewebapps folder of the Struts archive file as struts-blank.war. This example serves as a useful template when constructing your own Web applications.
|
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
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. |
Add Struts servlet and tag library entries to the web.xml file.
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>
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>
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:
|
The following sections cover considerations for using Jakarta log4j in an OC4J standalone environment:
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.htmlhttp://jakarta.apache.org/log4j/docs/documentation.html
|
Note: The log4j framework is part of the Apache Jakarta Project, sponsored by the Apache Software Foundation. |
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.
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 the following directory structure:
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.)
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:
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, 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:
|
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 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
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.
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:
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:
Global application level: j2ee/home/applib
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 theorg.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. Visit the following log4j Web site and see the log4j user mailing list for more information:
|
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. |
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.
|
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 thedebug 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.
|
