|
Oracle® Containers for J2EE Developer's Guide
10g Release 3 (10.1.3) Part No. B14433-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE Developer's Guide
10g Release 3 (10.1.3) Part No. B14433-01 |
|
|
Previous |
Next |
This chapter discusses developing applications on open source frameworks for deployment into OC4J. It contains the following sections:
To enable a Web application built on an open source framework to be used in OC4J, the JAR file(s) containing the open source implementation as well as any dependent libraries must be available within OC4J. Note that no open source framework libraries are available at the global level in OC4J by default.
The standard approach is to package the required JAR file(s) with the Web application on the WEB-INF/lib path. The library can then be deployed into OC4J with the Web application. While this is the most straightforward process, it will result an instance of the library being loaded for each Web application.
If the open source library is required by multiple Web applications, or to multiple Web modules within a single J2EE application, the OC4J proprietary shared library mechanism may be a more practical approach. Using this mechanism is an efficient use of system resources, as OC4J creates a single classloader for the shared library, rather than loading multiple copies of the same library.
To use the shared library mechanism, you will install the shared library on the OC4J instances hosting the applications using one of the options described in "Options for Installing and Publishing a Shared Library". You can then configure specific applications to import the shared library as described in "Configuring an Application to Import a Shared Library".
Making the open source framework implementation available as a shared library is a practical approach when:
You want all Web modules within a J2EE application (EAR) to use the same version of the library.
In this case, you will configure the application to import the shared library in the EAR-level orion-application.xml deployment descriptor as described in "Declaring Dependencies in an Application's OC4J Deployment Descriptor", or in the MANIFEST.MF file as outlined in "Declaring Dependencies in an Application's Manifest File".
You want to ensure that all Web modules deployed into OC4J use the same version of the library.
This requires configuring the default application to import the shared library, as described in "Configuring All Deployed Applications to Import a Specific Shared Library". Note that if this configuration is used, an application will use the version of the shared library imported from the default application, even if a different version of the library is packaged with the application.
You can create shared libraries using any of the mechanisms described in "Options for Installing and Publishing a Shared Library". The following example illustrates how you can easily add the Xerces parser as a shared library within an OC4J server using Application Server Control Console.
Click Administration>Shared Libraries.
Click Create on the Shared Libraries page.
Enter the name for the shared library. In this case, you will enter xerces.xml.
Enter the shared library version, which in this case is 2.5.0.
Click Add to upload the library JAR files to the OC4J instance. Upload the following Apache libraries:
xercesImpl.jar
xml-apis.jar
The following shared library declaration is added to the ORACLE_HOME/j2ee/instance/server.xml file:
<shared-library name="xerces.mxl" version="2.5.0"> <code-source path="xercesImpl.jar"/> <code-source path="xml-apis.jar"/> </shared-library>
When working with open-source frameworks, it may sometimes be necessary to remove or override Oracle shared libraries imported by default to avoid conflicts with corresponding open source libraries packaged with an application.
For example, the Oracle XML parser packaged with OC4J will be used by default by any application deployed into OC4J. This is not desirable, for example, with an Axis-based application, which requires the Xerces parser library.
In this scenario, you have several options:
Specify the shared library to remove in the orion-application.xml file packaged with the application
See "Removing and/or Replacing an Oracle Shared Library Imported by Default" for an overview of using the <remove-inherited> tag.
Configure the application to not import the Oracle shared library at deployment time
See "Removing and/or Replacing an Oracle Shared Library Imported by Default" for a step-by-step example illustrating how a shared library can be removed at deployment time.
If the required open-source JAR is packaged within a Web module, you can specify that OC4J search for and load this local library, which will cause it to be used instead of the default Oracle library.
See "Using a Packaged JAR In Place of an Oracle Shared Library" for a step-by-step example.
The following sections provide an overview of using Jakarta Struts in an OC4J environment:
Jakarta Struts is an open source framework for building Web applications using open standards such as Java servlets, JavaServer Pages, and XML. Applications built on the latest official release of Struts, version 1.1, can be easily deployed into the latest release of OC4J.
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. No OC4J-specific configuration is required to deploy Struts MVC-enabled Web applications into OC4J.
Struts is part of the Apache Jakarta Project, sponsored by the Apache Software Foundation. See the user guide, installation guide, and other documentation on the official Struts Web site:
http://jakarta.apache.org/struts
|
Note: The Struts documentation strongly recommends against installing Struts as a shared library. Specifically, the documentation notes thatClassNotFoundException issues may occur unless all of your application classes are stored in the shared library directory.
As such, you should package |
Oracle JDeveloper 10g provides extensive support for building Web applications on the Struts 1.1 framework.
JDeveloper includes the source for the Struts framework in the jdev_install/jakarta-struts/ directory. This directory contains the same Struts package, including sample Web applications, that can be downloaded from the Apache Struts home page.
A sampling of the features for Struts development provided in JDeveloper includes:
The Struts page flow diagram lets you draw the flow of your application's Web pages using icons selected from a palette. The diagram visually represents standard Struts elements, including actions and action forwards, and automatically updates those elements in the Struts configuration file.
The Structure window and Property Inspector let you edit the attributes of any Struts element.
The Struts Configuration Editor allows you to directly edit the Struts configuration file.
A large set of custom JSP tag libraries that work with the Struts framework is provided, and the Struts tag libraries are accessible from the JDeveloper Component Palette.
See the online Help provided with Oracle JDeveloper for details on Struts support.
If you are not using Oracle JDeveloper, you can download the Struts 1.1 distribution directly from Jakarta at the following site:
http://jakarta.apache.org/site/binindex.cgi
The sample applications, packaged as WAR files, make an excellent resource for understanding generic Struts. 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 you are constructing your own Web applications.
This section provides an overview of using the Spring Framework 1.2 in OC4J. It includes the following topics:
Spring is an increasingly popular open source Java/J2EE application framework based on the Dependency Injection (DI) design pattern. OC4J provides full support for applications built on Spring Framework 1.2. This latest release of Spring also provides extensive support for Oracle TopLink integration, providing you with a powerful platform for persistent data access.
Like Struts, Spring provides a Model-View-Controller (MVC) framework, and Web applications built on Spring MVC can be deployed seamlessly into OC4J, without requiring any OC4J-specific deployment configuration.
Spring is particularly strong in the area of persistent data access, making it an attractive framework for building Web applications that will interact with a relational database. The Spring framework itself includes a persistence layer built on the J2EE Data Access Objects (DAO) design pattern. The DAO layer integrates well with object-relational mapping (ORM) tools, including the open source Hibernate and the proven Oracle TopLink.
Spring 1.2 includes extensive support for Oracle TopLink releases 9.0.4 and 10.1.3. The result of this integration is a powerful, high-performance framework for persisting "plain old Java objects" (POJOs) to relational databases.
Section 11.4 in the Spring Reference Documentation, provided with the Spring distribution as spring-refrence.pdf, discusses TopLink integration in considerable detail. Documentation on the various TopLink classes provided with spring.jar is also provided.
The Spring 1.2 distribution is available as a ZIP file from the following location:
http://www.springframework.org/download
The latest snapshot build can also be downloaded from this location.
The Spring Reference Documentation is provided with the distribution as spring-refrence.pdf. Spring also ships with several sample applications that illustrate best practices. These can be used as templates for your own applications.
Spring 1.2 is organized into seven modules, each packaged as a JAR file. The "core" module is packaged as spring.jar and contains all of the other modules. However, the modular structure makes it possible to provide only those JAR files that are needed, if desired.
The following provides an overview of how Web applications built using Apache MyFaces work with OC4J.
MyFaces is an open source alternative implementation of JavaServer Faces (JSF), a standard Java framework for building Web applications. MyFaces has been developed under the aegis of the Apache Foundation.
Because it is simply another "flavor" of JSF, Web applications built on MyFaces can be easily deployed into OC4J; no OC4J-specific configuration changes are necessary.
You can download the MyFaces distribution from the following location:
http://myfaces.apache.org/binary.cgi
The framework is packaged as myfaces.jar, which must be made available to Web applications deployed into OC4J.
You can also download a set of Web applications packaged as WAR files that are built on the MyFaces framework from this site.
The taglib directive for the core and html tag libraries is the same for all JSF implementations. This means, for example, that you can use either the Sun RI or MyFaces libraries, without having to update your JSPs that have been deployed to OC4J.
If you deploy a Web application that uses MyFaces, the following libraries must be made available to the application:
myfaces-api.jar
myfaces-impl.jar
Alternatively, you can utilize myfaces-all.jar, which includes all files in these two JAR files. However, using the two separate JAR files makes it easier to "swap out" a specific library.
MyFaces also offers an open-source extension library named Tomahawk that is fully compatible with any JSF 1.1 compatible implementation, including the Sun JSF RI packaged with JDeveloper. If this component extension is used, the following library must be made available to deployed applications:
tomahawk.jar
In addition, you must include the following taglib directive in all JSPs that will use the library (note that tools such as JDeveloper will do this for you:)
<%@ taglib uri="http://myfaces.apache.org/tomahawk" prefix="t"%>
Oracle JDeveloper has built-in support for the Sun JavaServer FacesReference Implementation (RI). However, you can easily configure JDeveloper to use other JSF implementations, including MyFaces, through the Import Custom JSP tag library interface.
You can have both the Sun RI and MyFaces implementations installed in JDeveloper. In fact, you can even build your JSPs using one of these standard implementations, then change to using another at deployment time simply by replacing the libraries used.
See the JDeveloper page on the Oracle Technology Network for additional information and "how to's" on using JSF, MyFaces and Oracle ADF:
http://www.oracle.com/technology/products/jdev/index.html
The following provides an overview of using Hibernate with applications deployed into OC4J.
Hibernate is an open source object-relational mapping (ORM) tool for Java environments. Hibernate is often used in Java Swing applications, Java Servlet-based applications, or J2EE applications using EJB session beans.
You can access the Hibernate libraries and documentation from the following site:
http://hibernate.org/
Both Oracle TopLink, which is packaged by default with OC4J, and Hibernate use antlr.jar. To avoid class collisions between the library packaged with OC4J and that packaged with your Hibernate application, you must explicitly remove the oracle.toplink shared library from the set of libraries that will be imported by the application.
See "Removing and/or Replacing an Oracle Shared Library Imported by Default" for details.
The following provides an overview on using Axis-based Web services in OC4J.
Apache Axis is a well-known and widely-used framework for implementing Web services. Applications that include Web services based on Axis 1.2 and 1.3 can easily be deployed into OC4J.
You can access the Axis libraries and documentation from the following Apache site:
http://ws.apache.org/axis/
Axis applications typically utilize the Xerces XML parser by default. However, Axis applications can safely use the Oracle XML parser packaged with OC4J if the Xerces parser is not packaged with the application.
The Oracle XML parser is configured to be used by all deployed applications by default—even the Xerces libraries are packaged within your Web module (WAR) file. As such, if you do want Axis-based applications to use the Xerces parser, you must use one of the shared library mechanisms provided by OC4J to ensure that the Xerces parser is used by a given Axis-based application. See "Removing Imported Oracle Shared Libraries to Avoid Conflicts" for details.
Note that attempting to remove the Oracle XML parser will result in an error if the affected Web service includes Oracle's JAX-RPC and/or SAAJ libraries (jaxrpc-api.jar and saaj-api.jar).
Axis and Oracle each provide different implementations of several key Web services libraries, such as JAX-RPC and WSDL libraries. Table 6-1 below lists these common libraries.
Table 6-1 Web Services Libraries
| Oracle | Axis |
|---|---|
jaxrpc-api.jar
|
jax-rpc.jar
|
saaj-api.jar
|
saaj.jar
|
orawsdl.jar
|
wsdl4j-1.5.1.jar
|
Because these libraries currently contain the same class implementations, classloader-related issues are not expected when an Axis application is deployed into OC4J.
However, a single application (EAR) cannot contain one Web service that uses Axis, and another that uses Oracle. Specifically, an Axis Web service calling out to another Web service via a Web services client created using JAX-RPC implementation is not supported.
The following sections cover considerations for using Jakarta log4j in an OC4J environment:
The log4j framework is an open source project of the Apache Jakarta Project, sponsored by the Apache Software Foundation. The framework 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:
http://jakarta.apache.org/log4j/docs/index.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 save it to your local file system.
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 If you install the log4j library separately for each Web application, in each 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 like /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:
java -Dlog4j.debug=true -jar oc4j.jar
OC4J displays 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 succeeded.
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.
|
