Oracle Application Server Containers for J2EE Servlet Developer's Guide 10g (9.0.4) Part Number B10321-01 |
|
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:
The following sections cover steps for using Jakarta Struts in an OC4J standalone environment:
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
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.
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
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.
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>
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.
% 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.
http-web-site.xml
:
http://your_host:8888/struts/doc
You will see the following welcome page for the Struts documentation:
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.
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
.
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.
% 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.
http-web-site.xml
:
http://your_host:8888/struts/example
You will see the following welcome page for the Struts sample application:
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.
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
.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. |
web.xml
file.
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>
<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>
/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, http://jakarta.apache.org/struts/learning.html |
The following sections cover considerations for using Jakarta log4j in an OC4J standalone environment:
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
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.
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.)
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:
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
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
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.
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:
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:
Note:
A log4j runtime is configured only once using the automatic configuration files when the first call is made to the http://www.mail-archive.com/log4j-user@jakarta.apache.org/ |
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.
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); }
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].
|
Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|