Application Oracle Server Containers for J2EE
Standalone User's Guide 10g Release 2 (10.1.2)
Part No. B14361-02
July 2005
Oracle Application Server Containers for J2EE Standalone User's Guide, 10g Release 2 (10.1.2) Part No. B14361-02 Copyright 2002, 2005, Oracle. All rights reserved. Primary Authors: Sheryl Maring, Dan Hynes Brian Wright
Contributing Author:
The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited. The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose. If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted Rights (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065 The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs. Oracle, JD Edwards, PeopleSoft, and Retek are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.
Contents
Preface ................................................................................................................................................................. xi
Intended Audience...................................................................................................................................... xi Documentation Accessibility ..................................................................................................................... xi Related Documentation ............................................................................................................................. xii Conventions ................................................................................................................................................ xii
1
Configuration and Deployment
Introduction to OC4J Standalone.......................................................................................................... 1-1 OC4J Installation ...................................................................................................................................... 1-2 Requirements ...................................................................................................................................... 1-2 Basic Installation................................................................................................................................. 1-2 Testing the Default Configuration................................................................................................... 1-3 Starting and Stopping OC4J................................................................................................................... 1-3 Starting OC4J ...................................................................................................................................... 1-3 Administering OC4J .......................................................................................................................... 1-4 Restarting OC4J ........................................................................................................................... 1-5 Shutting Down OC4J ......................................................................................................................... 1-5 HTTP and RMI Communication...................................................................................................... 1-6 Quick Start for JSPs and Servlets ..................................................................................................... 1-6 Creating the Development Directory ................................................................................................... 1-6 Configuring the FAQ Application Demo ............................................................................................ 1-7 Environment Setup for FAQ Demo................................................................................................. 1-8 Oracle Database........................................................................................................................... 1-8 OC4J System Configuration for FAQ Demo .................................................................................. 1-9 Data Source Configuration ........................................................................................................ 1-9 Security Configuration ............................................................................................................... 1-9 Deploy the FAQ Demo ................................................................................................................... 1-10 Deploy Using Automatic Deployment in a Development Environment ........................ 1-10 Deploy Using the Admin.JAR Tool in All Environments.................................................. 1-11 Deployment Details Explained ..................................................................................................... 1-12 Deploying Applications....................................................................................................................... 1-13 Archive Application into an EAR File.......................................................................................... 1-13 Deployment In a Production Environment Using ADMIN.JAR ............................................. 1-14 Binding the Web Application................................................................................................. 1-15 Deploy Your Application Manually in a Development Environment............................. 1-15
v
Verifying Deployment.................................................................................................................... Impact of Undeploying/Redeploying an Application .............................................................. Impact of "Hot Deploying" an Application ................................................................................. What Happens When You Deploy? ................................................................................................... Undeploying Web Applications .........................................................................................................
1-16 1-16 1-16 1-17 1-17
2
Advanced Configuration and Development
Overview of OC4J and J2EE XML Files ............................................................................................... 2-1 XML Configuration File Overview.................................................................................................. 2-1 XML File Interrelationships .............................................................................................................. 2-4 Sharing Libraries ...................................................................................................................................... 2-6 Manually Adding Applications in a Development Environment.................................................. 2-7 Configuring a Listener....................................................................................................................... 2-7 Configuring J2EE Applications ........................................................................................................ 2-7 Building and Deploying Within a Directory ...................................................................................... 2-8 OC4J Automatic Deployment for Applications .............................................................................. 2-10 Changing XML Files After Deployment........................................................................................... 2-11 Designating a Parent of Your Application........................................................................................ 2-12 Developing Startup and Shutdown Classes .................................................................................... 2-12 OC4J Startup Classes ...................................................................................................................... 2-13 OC4J Shutdown Classes ................................................................................................................. 2-15 Setting Performance Options.............................................................................................................. 2-15 Performance Command-Line Options......................................................................................... 2-16 Thread Pool Settings ....................................................................................................................... 2-16 Statement Caching .......................................................................................................................... 2-18 Task Manager Granularity............................................................................................................. 2-19 Enabling OC4J Logging ...................................................................................................................... 2-19 Viewing OC4J System and Application Log Messages ............................................................. 2-19 Text Log Files............................................................................................................................ 2-20 Oracle Diagnostic Logging (ODL) Log Files........................................................................ 2-21 Redirecting Standard Out and Standard Error........................................................................... 2-22 Disabling Access Logging for a Web Application...................................................................... 2-22 OC4J Debugging ................................................................................................................................... 2-23 Servlet Debugging Example .......................................................................................................... 2-25
3
Configuring Security
Overview of Security Functions ............................................................................................................ Authentication .......................................................................................................................................... Specifying Users and Groups ........................................................................................................... Example: Specifying Users and Groups in jazn-data.xml..................................................... Example: Specifying Users and Groups in principals.xml ................................................... Authenticating HTTP Clients ........................................................................................................... Authenticating EJB Clients ............................................................................................................... Setting JNDI Properties.............................................................................................................. No JNDI Properties.............................................................................................................. JNDI Properties File............................................................................................................. JNDI Properties Within Implementation ......................................................................... 3-1 3-2 3-2 3-3 3-3 3-4 3-4 3-4 3-4 3-4 3-5
vi
Using the Initial Context Factory Classes................................................................................ 3-5 Authorization ............................................................................................................................................ 3-6 Specifying Logical Roles in a J2EE Application............................................................................. 3-6 Mapping Logical Roles to Users and Groups ................................................................................ 3-7 Plugging In a User Manager................................................................................................................... 3-8 Using the JAZNUserManager Class................................................................................................ 3-8 Using the JAZNUserManager Class with the LDAP-Based Provider Type ...................... 3-9 Using the JAZNUserManager Class with the XML-Based Provider Type ..................... 3-10 Using the XMLUserManager Class .............................................................................................. 3-10 Creating Your Own User Manager............................................................................................... 3-11 Confidentiality Through SSL ............................................................................................................. 3-13 Overview of Using SSL for OC4J Standalone ............................................................................ 3-13 Overview of SSL Keys and Certificates ................................................................................ 3-13 Using Certificates with OC4J Standalone............................................................................. 3-14 Configuration of OC4J for SSL ...................................................................................................... 3-15 Requesting Client Authentication with OC4J Standalone ................................................. 3-19 HTTPS Common Problems and Solutions ................................................................................. 3-20 General SSL Debugging .......................................................................................................... 3-21
A
Troubleshooting OC4J
Problems and Solutions ......................................................................................................................... Unable to Start OC4J When Using JDK 1.3 ................................................................................... Unable to Restart OC4J After Abnormal Termination When OracleAS JMS is Active .......... Stateful Replication Not Consistent Across OC4J instances ....................................................... Using A Non-Certified Version of the JDK for OC4J Only......................................................... java.lang.OutOfMemory Errors Thrown When Running OC4J................................................. Connection Timeouts Through a Stateful Firewall Affect System Performance ..................... OPMN-Managed OC4J Unable to Access EJB Resources Via the Default RMI Port ............. Application Performance Impacted by JVM Garbage Collection Pauses................................. Invalid or Unneeded Library Elements Degrade Performance.................................................. JSP Error: Tag Not Registered ......................................................................................................... JSP Error: Zero-Length Class File ................................................................................................... JSP Error: Illegal use of <when>-style tag without <choose> as its direct parent .................. Need More Help? .................................................................................................................................... A-1 A-1 A-2 A-2 A-2 A-2 A-3 A-4 A-4 A-5 A-5 A-5 A-6 A-6
B
Additional Information
Description of XML File Contents ....................................................................................................... OC4J Configuration XML Files ....................................................................................................... server.xml ................................................................................................................................... http-web-site.xml ....................................................................................................................... jazn-data.xml .............................................................................................................................. principals.xml ............................................................................................................................. data-sources.xml ........................................................................................................................ jms.xml......................................................................................................................................... rmi.xml ........................................................................................................................................ J2EE Deployment XML Files ........................................................................................................... B-1 B-1 B-1 B-2 B-2 B-3 B-3 B-3 B-3 B-4
vii
The J2EE application.xml File .................................................................................................. The OC4J-Specific orion-application.xml File........................................................................ The J2EE ejb-jar.xml File ........................................................................................................... The OC4J-Specific orion-ejb-jar.xml File................................................................................. The J2EE web.xml File............................................................................................................... The OC4J-Specific orion-web.xml File .................................................................................... The J2EE application-client.xml File ....................................................................................... The OC4J-Specific orion-application-client.xml File............................................................. Elements in the server.xml File............................................................................................................. Configure OC4J ................................................................................................................................. Reference Other Configuration Files.............................................................................................. <application-server> Element Description ........................................................................... Elements Contained Within <application-server> ............................................................... Elements in the application.xml File ................................................................................................. <application> Element Description ............................................................................................. Elements Contained Within <application>.......................................................................... Elements in the orion-application.xml File...................................................................................... <orion-application> Element Description .................................................................................. Elements Contained Within <orion-application>............................................................... Elements in the application-client.xml File ..................................................................................... <application-client> Element Description .................................................................................. <application-client> ................................................................................................................ Elements Contained Within <application-client>............................................................... Elements in the orion-application-client.xml File .......................................................................... <orion-application-client> Element Description ....................................................................... Elements Contained Within <orion-application-client>.................................................... Standalone OC4J Command-Line Options and Properties .......................................................... Options for the OC4J Server JAR .................................................................................................. Options for the OC4J Administration Management JAR ......................................................... General OC4J Administration ................................................................................................ Application Deployment ........................................................................................................ Adding Web Sites .................................................................................................................... DataSource And Application Options .................................................................................. OC4J System Properties ....................................................................................................................... Configuration and Deployment Examples....................................................................................... J2EE Application XML Configuration Example ......................................................................... application.xml Example ........................................................................................................ web.xml Example..................................................................................................................... ejb-jar.xml Example ................................................................................................................. server.xml Addition................................................................................................................. http-web-site.xml Addition .................................................................................................... Client Example ......................................................................................................................... JNDI Properties for the Client......................................................................................... Deploying Example ................................................................................................................. EJB Module ............................................................................................................................... Web Module--Servlet and JSP Calling EJBs........................................................................ Client Module--Standalone Java Client Invoking EJBs.....................................................
B-4 B-4 B-4 B-4 B-5 B-5 B-5 B-5 B-6 B-6 B-6 B-6 B-7 B-14 B-14 B-15 B-16 B-16 B-16 B-21 B-22 B-22 B-22 B-24 B-24 B-24 B-26 B-26 B-26 B-27 B-27 B-29 B-31 B-33 B-36 B-36 B-37 B-38 B-38 B-39 B-40 B-40 B-40 B-41 B-41 B-41 B-42
viii
Manifest File for the Client .............................................................................................. B-42 Executing the Client ......................................................................................................... B-42
C
Third Party Licenses
Third-Party Licenses ............................................................................................................................... C-1 Apache HTTP Server ........................................................................................................................ C-1 The Apache Software License .................................................................................................. C-1
Index
ix
x
Preface
This preface introduces you to the Oracle Application Server Containers for J2EE Standalone User's Guide, discussing the intended audience, structure, and conventions of this document. It also provides a list of related Oracle documents.
Intended Audience
This manual is intended for anyone who is interested in using Oracle Application Server Containers for J2EE (OC4J) in standalone mode, assuming you have basic knowledge of the following:
Java and J2EE XML JDBC
Documentation Accessibility
Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/ Accessibility of Code Examples in Documentation Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace. Accessibility of Links to External Web Sites in Documentation This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.
xi
TTY Access to Oracle Support Services Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services within the United States of America 24 hours a day, seven days a week. For TTY support, call 800.446.2398.
Related Documentation
For more information on OC4J, see the following documentation available from other OC4J manuals:
Oracle Application Server Containers for J2EE Services Guide Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference Oracle Application Server Containers for J2EE Servlet Developer's Guide Oracle Application Server Containers for J2EE Security Guide Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide
The following documentation may also be helpful in understanding OC4J:
Oracle Application Server Performance Guide Oracle Application Server High Availability Guide Oracle9i JDBC Developer's Guide and Reference Oracle HTTP Server Administrator's Guide Oracle Application Server DMS API Reference
Conventions
The following text conventions are used in this document:
Convention boldface italic monospace Meaning Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary. Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values. Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.
xii
1
Configuration and Deployment
This chapter demonstrates how to configure and execute OC4J as simply and quickly as possible. Within OC4J, you can execute servlets, JSP pages andEJBs. As an example of deploying an application to OC4J, this chapter describes how to configure the FAQ application demo. This chapter includes the following topics:
Introduction to OC4J Standalone OC4J Installation Starting and Stopping OC4J Creating the Development Directory Configuring the FAQ Application Demo Deploying Applications What Happens When You Deploy? Undeploying Web Applications
Introduction to OC4J Standalone
Oracle Application Server Containers for J2EE (OC4J) Standalone provides a complete Java 2 Enterprise Edition (J2EE) 1.3 environment written entirely in Java that executes on the Java virtual machine (JVM) of the standard Java Development Kit (JDK). OC4J is J2EE 1.3 certified and provides all the containers, APIs, and services that J2EE specifies. OC4J is based on technology licensed from Ironflare Corporation, which develops the Orion server--one of the leading J2EE containers, so the product and some of the documentation still contains some reference to the Orion server. OC4J supports and is certified for the standard J2EE APIs, as listed in Table 11.
Table 11 OC4J J2EE Support Version Supported 1.2 2.3 2.0 1.0 1.0 1.2
J2EE 1.3 Standard APIs JavaServer Pages (JSP) Servlets Enterprise JavaBeans (EJB) Java Transaction API (JTA) Java Message Service (JMS) Java Naming and Directory Interface (JNDI)
Configuration and Deployment
1-1
OC4J Installation
Table 11 (Cont.) OC4J J2EE Support J2EE 1.3 Standard APIs Java Mail Java Database Connectivity (JDBC) Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider J2EE Connector Architecture JAXP Version Supported 1.1.2 2.0 Extension 1.0 1.0 1.1
OC4J Standalone is for use by development and small-medium scale production deployments. Specifically, OC4J Standalone supports HTTP and HTTPS natively without the use of Oracle HTTP Server. It does not have support for load balancing, clustering, or management through Oracle Enterprise Manager 10g. To use those features, customers must install one of the Oracle Application Server installation types, such as J2EE + WebCache. The standalone version is supported in a single instance, single JVM, and single machine configuration. The OC4J documentation assumes that you have a basic understanding of Java programming, J2EE technology, and Web and EJB application technology. This includes deployment conventions such as the /WEB-INF and /META-INF directories.
OC4J Installation
OC4J is a lightweight container that is J2EE-compliant. It is configured with powerful and practical defaults and is ready to execute after installation. After downloading the oc4j_extended.zip file from OTN, unzip this file to install OC4J. The following sections describe how to do this:
Requirements Basic Installation Testing the Default Configuration
Requirements
You do not need to add anything to your CLASSPATH to run OC4J, because it loads the Java JAR and class files directly from the installation directory, from the lib/ subdirectory, and from the deployed applications EAR, WAR, or ejb-jar files.
Basic Installation
OC4J is distributed within a ZIP file named oc4j_extended.zip on OTN. After unzipping this file, follow instructions listed in the README.TXT. Install this ZIP file in any directory that is in the path. You must have a Java2 version Java executable in your $PATH, preferably version 1.3.1 or 1.4.1. To install OC4J, execute the following:
% % % % cd /your_directory unzip oc4j_extended.zip cd j2ee/home java -jar oc4j.jar -install
Enter an administrator password
1-2 Oracle Application Server Containers for J2EE Standalone User's Guide
Starting and Stopping OC4J
After the install is complete, the j2ee/home directory contains all the files necessary for running OC4J with a default configuration. The installation prompts you for an administration username and password, which is used for the administration console command-line tool.
Note:
Instead of executing oc4j.jar from the j2ee/home directory, you can set a $J2EE_HOME variable (for UNIX) or the %J2EE_HOME% variable (for Windows) to j2ee/home, so that in the command line and execute oc4j.jar from any directory. For example, in the UNIX environment use the following: % java -jar $J2EE_HOME/oc4j.jar
Testing the Default Configuration
OC4J is installed with a default configuration that includes a default Web site and a default application. These are provided so you can start and test OC4J immediately. Start OC4J by executing the following:
1.
Change directory to the OC4J installation directory (j2ee/home), and issue one of the following commands:
java -jar oc4j.jar This starts OC4J using the default configuration files, which are located in j2ee/home/config.
java -jar oc4j.jar -config /mypath/server.xml This starts OC4J using the server.xml file located in /mypath.
The server should output an initialization string with the version number.
2.
Test OC4J by accessing "http://hostname:8888/" from a Web browser. If you changed the default port number, access the Web server using "http://hostname:portnumber/".
For example, test the Web server by connecting a Web browser to http://hostname:8888/servlet/HelloWorldServlet, which should return a "Hello World" page. For more information on starting and stopping OC4J, see "Starting and Stopping OC4J" on page 1-3. For more information on configuration, see "Deploying Applications" on page 1-13.
Starting and Stopping OC4J
Starting OC4J Administering OC4J Shutting Down OC4J
Starting OC4J
OC4J is installed with a default configuration that includes a default Web site and a default application. Therefore, you can start OC4J immediately.
Configuration and Deployment
1-3
Starting and Stopping OC4J
Important:
Due to a logging implementation dependency issue, OC4J fails to start when using JDK 1.3. The solution to this problem is to remove or comment out the following entry in the ORACLE_ HOME/j2ee/home/config/server.xml configuration file:
<j2ee-logging-config path="./j2ee-logging.xml" />
To start OC4J in a standalone environment, issue the following command from the j2ee/home/ directory:
java -jar oc4j.jar options
This command starts OC4J using the default configuration files, which you can find in the j2ee/home/config directory. Options for this command are not necessary to start OC4J. However, if you want to exercise more control, use the options listed in "Options for the OC4J Server JAR" on page B-26 or issue the following command from the j2ee/home directory:
java -jar oc4j.jar -help
After OC4J launches, a message is displayed on the screen to note this fact.
Note:
Instead of executing oc4j.jar from the j2ee/home directory, you can set a $J2EE_HOME variable (for UNIX) or the %J2EE_HOME% variable (for Windows) to j2ee/home, so that in the command line and execute oc4j.jar from any directory. For example, in the UNIX environment use the following: % java -jar $J2EE_HOME/oc4j.jar
Administering OC4J
After starting the OC4J server, you can administer the server using the admin.jar command-line tool, which is located in <install_directory>/j2ee/home. To use the admin.jar command, see the following syntax:
java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin_id admin_password options
where the variables are as follows:
oc4j_host:oc4j_ormi_port--The host name and port of the OC4J server from which you want to deploy the application. The admin.jar tool uses the OC4J Remote Method Invocation (ORMI) protocol to communicate with the OC4J server. Therefore, the host name and port identified by these variables are defined in the rmi.xml file for the OC4J server to which you are directing the request. The default port number for the ORMI protocol is 23791. Configure both the host name and port number--if not using the default--in the rmi.xml file in the <rmi-server> element, as follows:
<rmi-server port="oc4j_ormi_port" host="oc4j_host">
admin_id admin_password--The administration identity and password. Specify this identity and password for the OC4J server in its principals.xml file.
1-4 Oracle Application Server Containers for J2EE Standalone User's Guide
Starting and Stopping OC4J
"Options for the OC4J Administration Management JAR" on page B-26 discusses the options for this tool.
Restarting OC4J
You can designate whether the task manager in OC4J automatically detects changes made to deployed applications. Once a change is detected, then OC4J reloads these applications automatically. In this case, you do not need to restart the server when redeploying an application. The check-for-updates attribute in the <application-server> element in the server.xml file defaults to true, which enables automatic deployment. If true, task manager checks for XML configuration file modifications. Thus, if you set this to false, you can disable automatic refreshing of the configuration to any new XML modifications. Also, setting this attribute to false stops the automatic deployment of any applications until you execute admin.jar -updateConfig. If set to false, you cause the XML configuration to refresh from the XML files and any necessary automatic deployment to occur by using the admin.jar -updateConfig option. If you enable automatic deployment, then you do not have to restart the OC4J process each time you make a modification to the application. However, enabling automatic deployment also effects your performance. Thus, it is recommended that you enable automatic deployment only in a development environment, not in a production environment. Even if you have automatic deployment enabled, it does not detect modifications in the global server XML configuration files. Thus, if you modify any of the container-level configuration files, such as data-sources.xml, rmi.xml, or principals.xml, you must restart the OC4J process for these modifications to be recognized. To restart OC4J using the default parameters, change to the installation root directory, and execute the following:
% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin admin_password -restart
This command connects to the OC4J RMI listener port and requests it to restart. It may not work if the JVM is not responding to signals or accepting RMI messages. In this case, stop the JVM in the UNIX environment with the following operating system command: kill process. In the Windows environment, access the Windows Task Manager to terminate the JVM.
Shutting Down OC4J
Shut down OC4J by executing the following:
% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin admin-password -shutdown
This command provides a graceful shutdown of the container. If it does not shut down the container, force a rapid shutdown by passing the force argument, as follows:
% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin admin-password -shutdown force
If this method does not work, then kill OC4J processes with your operating system commands or tool, depending on your system.
Configuration and Deployment
1-5
Creating the Development Directory
HTTP and RMI Communication
For HTTP applications, clients can send their requests directly to OC4J. The default port number is 8888. You can change this port number in the appropriate *-web-site.xml file, such as the http-web-site.xml file. For RMI-based applications--such as EJB and JMS--clients should send their requests directly to OC4J. The default RMI port is 23791. Modify this port number in the rmi.xml file. See "Configuring a Listener" on page 2-7 for directions.
Quick Start for JSPs and Servlets
To deploy Web applications on OC4J, do one of the following:
Place your servlet classes and JSP pages in the j2ee/home/default-web-app directory. Deploy J2EE applications using the admin.jar tool. The J2EE application must be archived in the EAR format.
Placing servlets and JSP pages in the default-web-app directory is the easiest method to deploy applications or to migrate J2EE applications from previous versions of OC4J. Do the following for quick deployment of servlets or JSPs:
1.
Place your servlet classes in the j2ee/home/default-web-app/WEB-INF/classes subdirectory--in a directory corresponding to their Java package. The servlet is accessible from URLs of the form: http://oc4j_host:8888/servlet/class-name For example, place the servlet class my.HelloServlet, as follows:
j2ee/home/default-web-app/Web-INF/classes/my/HelloServlet.class
Then it is accessible from the following URL:
http://oc4j_host:8888/servlet/my.HelloServlet 2.
Place JSP pages anywhere in the j2ee/home/default-web-app directory. They are accessible with URLs of the form: http://oc4j_host:8888/path-to-JSP For example, a JSP page in j2ee/home/default-web-app/examples/Hello.jsp is accessible as http://oc4j_host:8888/examples/Hello.jsp.
Creating the Development Directory
When developing your application, it is good practice to use consistent and meaningful naming conventions. As an example, you could develop your application as modules within a directory named after your application. All the subdirectories under this directory could be consistent with the structure for creating JAR, WAR, and EAR archives. Thus, when you have to archive the source, it is already in the required archive format. Figure 11 demonstrates this structure.
1-6 Oracle Application Server Containers for J2EE Standalone User's Guide
Configuring the FAQ Application Demo
Figure 11 Development Application Directory Structure
Consider the following points regarding Figure 11:
You cannot change the following directory names and XML filenames: META-INF, WEB-INF, application.xml, ejb-jar.xml, web.xml, and application-client.xml. Separate directories clearly distinguish modules of the enterprise Java application from each other. The application.xml file, which acts as the standard J2EE application descriptor file, defines these modules. The directories containing the separate modules (<ejb_module>, <web_ module>, and <client_module>) can have arbitrary names. However, these names must match the values in the standard J2EE application descriptor file--the local application.xml file. The top of the module represents the start of a search path for classes. As a result, classes belonging to packages are expected to be located in a nested directory structure beneath this point. For example, a reference to an EJB package class 'myapp.ejb.Demo' is expected to be located in appname/ejb_ module/myapp/ejb/Demo.class.
Configuring the FAQ Application Demo
This section describes how to configure the FAQ J2EE demo application, which provides support for managing Frequently Asked Questions (FAQs) and storing/retrieving these FAQs from an Oracle database. FAQs are broadly categorized into Specialization Areas. Each Specialization Area is further sub-categorized into Topics.
Configuration and Deployment
1-7
Configuring the FAQ Application Demo
Each FAQ can be associated with multiple Specialization Areas, where each area has one or more Topics associated with them. You can generate a list of FAQs (in HTML format) for a given Specialization Area for internal or external publication.
Internal: FAQs that are published for internal users only. These include all external and internal FAQs. External: FAQs that are published on external forums.
Within the demo, Areas, Topics, and FAQs are entered or updated in the database through Input/Update screens or through a OracleAS Web Services interface. Each Area, Topic and FAQ is uniquely identified by a primary key, which is automatically generated by the system. This application is a J2EE 1.3 compliant application, developed utilizing the following technologies:
HTML (including MS-HTML for creating a Rich-Text Editor) JavaScript Cascade Style Sheets Java Server Pages 1.2 Servlet 2.3 JSP Standard Tag Library (JSTL) 1.0 Oracle JSP 1.2 Utility Tag Libraries Enterprise JavaBeans 2.0 (using Local Interfaces, Abstract Classes, CMR and EJB-QL)
Entity Bean (CMP) Session (Facade) Bean (stateless)
Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider Oracle Application Server Web Services
The following sections detail how to configure and deploy the FAQ demo application. In addition, the last section demonstrates how these steps relate to any application that you may wish to configure and deploy to OC4J:
Environment Setup for FAQ Demo OC4J System Configuration for FAQ Demo Deploy the FAQ Demo Deployment Details Explained
Environment Setup for FAQ Demo
Before you configure OC4J and deploy the FAQ demo, you need to modify the back-end database to contain tables that are necessary for executing the FAQ demo.
Oracle Database
Create the database tables for the FAQ demo by executing the SQL table creation script CreateTables.sql script, which is located at http://<hostname>:8888/FAQApp/CreateTables.sql or can be downloaded
1-8 Oracle Application Server Containers for J2EE Standalone User's Guide
Configuring the FAQ Application Demo
with the rest of the FAQ application from OTN at http://www.oracle.com/technology/tech/java/oc4j/demos/904/index. html in the FAQApp.zip file. In an Oracle database environment, you can execute the SQL script through SQL*Plus, connecting to the database and schema where you want the tables to be installed and executing @CreateTables. Please refer to the Oracle database documentation for further instructions on how to use SQL*Plus, running install scripts, creating database users/schemas, and so on.
OC4J System Configuration for FAQ Demo
In order for the FAQ demo to execute properly, the following system modification must be implemented:
Modify the default data source, OracleDS, to point to the back-end database. Add the FAQ user to the jazn.com realm and assign it to the users role.
The directions for each of these steps are covered in the following sections:
Data Source Configuration Security Configuration
Data Source Configuration
In order to execute the FAQ application, you must have an Oracle database with the corresponding FAQ application database schema installed on it. The FAQ Application uses the default global data source named OracleDS that ships with the application server, which must be configured so that it connects to the database in which you created the FAQ tables.
Note:
An I/O exception is thrown if you do not update the global OracleDS data source appropriately.
If your back-end database uses the thin JDBC driver, is located at myhost:1521/MYSERVICE, and uses the username/password of faq/faq, then the j2ee/home/config/data-sources.xml file is modified to point to the database service at the URL jdbc:oracle:thin:@myhost:1521/MYSERVICE, as follows:
<data-source class="com.evermind.sql.DriverManagerDataSource" name="OracleDS" location="jdbc/OracleCoreDS" xa-location="jdbc/xa/OracleXADS" ejb-location="jdbc/OracleDS" connection-driver="oracle.jdbc.driver.OracleDriver" username="faq" password="faq" url="jdbc:oracle:thin:@myhost:1521/MYSERVICE" inactivity-timeout="30" />
Security Configuration
The FAQ demo uses Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider for authentication and user access control capabilities. An
Configuration and Deployment
1-9
Configuring the FAQ Application Demo
application user is added to the default jazn.com realm through the jazn.jar command line tool, as follows:
> java -jar jazn.jar -adduser jazn.com <username> <passwd> > java -jar jazn.jar -grantrole users jazn.com <username>
The previous adds your user (given the username and password) to the jazn.com realm and then grants the users role to the new user. See the Oracle Application Server Containers for J2EE Security Guide for complete information on using Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider as your security provider.
Deploy the FAQ Demo
Download the FAQ demo application from OTN at http://www.oracle.com/technology/tech/java/oc4j/demos/904/index. html in the FAQApp.zip file.
1. 2.
Unzip this file to a working directory, which is referred to as <FAQApp_Home>. Deploy the FAQ application using by either copying the EAR file to the j2ee/home/applications directory or by the admin.jar tool. The following sections explain each method. Start the OC4J server by executing java -jar oc4j.jar Execute the FAQ application in your browser, where the default port is 8888.
http://your_machine_name:8888/FAQApp
3. 4.
Deploy Using Automatic Deployment in a Development Environment
As discussed in "Restarting OC4J" on page 1-5), OC4J supports automatic deployment and redeployment of applications, which allows you to make changes to the application EAR file, which are picked up by the server without stopping and restarting OC4J. You enable this through the check-for-updates attribute in the server.xml file. When automatic deployment is enabled, simply modify the XML configuration files, rearchive the application with its XML files into an EAR file, and copy the EAR file to the applications directory. The OC4J server notices the modified date and will redeploy the application, as necessary.
WARNING: Automatic deployment should only be used in a development environment. The task manager that checks for updates can be time consuming. Turn off automatic deployment in a production environment by setting the check-for-updates attribute to false.
For the first deployment of the FAQ application (locally), do the following:
1. 2.
Copy the <FAQApp_Home>/faq/dist/FAQApp.ear file to the j2ee/home/applications directory. Modify the j2ee/home/config/server.xml and http-web-site.xml files to register the FAQ application in the j2ee/home/applications directory, as follows:
a.
In the j2ee/home/config/server.xml file, add the FAQApp entry, as follows:
1-10 Oracle Application Server Containers for J2EE Standalone User's Guide
Configuring the FAQ Application Demo
<application name="FAQApp" path="../applications/FAQApp.ear" />
This step deploys the FAQ application on OC4J. The path is relative to j2ee/home/config. Since the FAQApp.ear file is in j2ee/home/applications, this makes the path ../applications/FAQApp.ear. For full details on the server.xml configuration file, see "Elements in the server.xml File" on page B-6.
b.
In the j2ee/home/config/http-web-site.xml file, bind the FAQ Web application by adding the FAQApp entry, as follows:
<web-app application="FAQApp" name="FAQAppWeb" root="/FAQApp" />
This step makes FAQ accessible from the OC4J server. For full details on the http-web-site.xml configuration file, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide. For more information, see "Manually Adding Applications in a Development Environment" on page 2-7, "OC4J Automatic Deployment for Applications" on page 2-10, and "What Happens When You Deploy?" on page 1-17.
Deploy Using the Admin.JAR Tool in All Environments
In the production environment, you should set the check-for-updates attribute to false (see "Restarting OC4J" on page 1-5) and then use the admin.jar tool for deploying all applications. The admin.jar tool deploys the application and modifies all of the appropriate XML files. This provides for remote deployment. Use the admin.jar command-line tool for registration and deployment, as follows:
java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin welcome -deploy -file d:\j2ee\home\applications\FAQApp.ear -deploymentName FAQApp -targetPath applications/
This step creates the entry in the server.xml file for the FAQ application. For a complete description of the admin.jar command-line tool, see "Options for the OC4J Administration Management JAR" on page B-26. You can bind any Web application through the admin.jar tool, as follows:
java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin welcome -bindWebApp FAQApp FAQAppWeb http_web_site /FAQApp
This creates the <web-app> entry in the http-web-site.xml configuration file. For a complete description of the admin.jar command-line tool, see "Options for the OC4J Administration Management JAR" on page B-26. For more information on configuring and managing Web applications, see the http-web-site.xml file, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide .
Configuration and Deployment
1-11
Configuring the FAQ Application Demo
Deployment Details Explained
Although the development of J2EE applications is standardized and portable, the XML configuration files are not. You may have to configure multiple XML files before deploying any application to OC4J. The necessary server configuration depends on the services that your application uses. For example, if your application uses a database, you must configure its DataSource object in the data-sources.xml file. For basic applications, such as the FAQ demo, you configure the following OC4J XML files:
META-INF/application.xml--The standard J2EE application descriptor for the application is contained within the application.xml file. This file must be properly configured and included within the J2EE EAR file that is to be deployed. server.xml and http-web-site.xml--The application is registered in the server.xml file; the Web application and the context it uses are registered in the http-web-site.xml file (or any other *-web-site.xml file that you choose). data-sources.xml--You must configure the DataSource object in the data-sources.xml file for each database used within the application.
To create and deploy simple J2EE applications, perform the following basic steps:
Basic Step Create or obtain the application. Make any necessary server environment changes. Modify any application XML configuration files. Update the application standard J2EE application descriptor file. Build an EAR file including the application--if one does not already exist. Register the application in the appropriate server XML files. Configure the database used. FAQ Application Step Description Download the FAQApp.zip from OTN Set the JAVA_HOME variable All of the application XML files are provided for you in the FAQ ZIP file. The application.xml file is included in the FAQApp.EAR file. If you want to modify the FAQ demo, modify within the src directory, and use ANT to build an EAR file. Modify the server.xml and http-web-site.xml files. Modify the data-sources.xml file.
The following steps describe what modifications to make to deploy the FAQ demo application into OC4J.
1. 2. 3. 4.
We asked you to download the FAQ demo application from the Oracle OTN site. Make any necessary server environment changes. You must set the JAVA_HOME variable to the base directory of the Java 2 SDK. All of the application XML files, such as web.xml, are provided for you in the ZIP file, correctly configured. Update the standard J2EE application descriptor file. The application.xml in the FAQ demo application is provided for you in the ZIP file. OC4J uses the application.xml file as the standard J2EE application descriptor file. Build an EAR file including the application. You can modify the FAQ demo application and rebuild it using the ANT command. To rebuild and deploy the FAQ demo, execute the following:
ant deploy
5.
1-12 Oracle Application Server Containers for J2EE Standalone User's Guide
Deploying Applications
The ANT build.xml is included in the FAQ ZIP download. To learn more about the ANT file, go to the following Jakarta site:
http://jakarta.apache.org/ant/
If you do not want to rebuild, you can copy the FAQApp.ear from the ZIP file into j2ee/home/applications. This step places the FAQ application in the OC4J server.
6.
Configure the OC4J DataSource for an Oracle database. Modify the default data source, OracleDS, to point to your back-end database, with the correct URL, username, and password. Register the J2EE application in the server.xml file and its Web application in the http-web-site.xml. Start OC4J by executing the following command from the j2ee/home/ directory:
7. 8.
java -jar oc4j.jar
For a complete description of all the OC4J starting options, see "Starting OC4J" on page 1-3. Open your Web browser and then specify the following URL:
http://oc4j_host:8888/FAQApp
See "Overview of OC4J and J2EE XML Files" on page 2-1 for more information on OC4J XML configuration files.
Deploying Applications
This section describes how to deploy a J2EE application to the OC4J server and how to bind that application to the server so that you can access the application from OC4J.
Archive Application into an EAR File Deployment In a Production Environment Using ADMIN.JAR Verifying Deployment Impact of Undeploying/Redeploying an Application Impact of "Hot Deploying" an Application
Archive Application into an EAR File
Your J2EE application can contain the following modules:
Web applications The Web applications module (WAR files) includes servlets and JSP pages.
EJB applications The EJB applications module (EJB JAR files) includes Enterprise JavaBeans (EJBs).
Client application contained within a JAR file
Archive the JAR and WAR files that belong to an enterprise Java application into an EAR file for deployment to OC4J. The J2EE specifications define the layout for an EAR file. The internal layout of an EAR file should be as follows:
Configuration and Deployment
1-13
Deploying Applications
Archive Directory Format Archive these files using the JAR command in the appname directory, as follows:
% jar cvfM appname.ear .
Note that the application.xml file acts as a standard J2EE application descriptor file.
Deployment In a Production Environment Using ADMIN.JAR
OC4J contains a command-line deployment tool for deploying J2EE applications--the admin.jar command. The options for this command are listed in "Standalone OC4J Command-Line Options and Properties" on page B-26. Ensure that automatic deployment is disabled by setting the check-for-updates attribute to false (see "Restarting OC4J" on page 1-5). To deploy a J2EE application with the EAR file to a remote node, execute admin.jar, as follows:
java -jar admin.jar ormi://host:port username password -deploy -file filename -deploymentName app_name -targetPath path/destination
where
The host:port is the host and port of the OC4J server. The username password is the administration username and password for the OC4J server. The -file path/filename indicates the local directory and filename for the EAR file. The -deploymentName app_name variable is a user-defined name of the application. The -targetPath path/destination indicates what path on the server node in which to deploy the EAR file. Provide a target path to the directory where the EAR file is copied for deployment. The default path is the applications/ directory.
Note:
If you have a Web application within the EAR file, bind the Web application using the admin.jar -bindWebApp option.
This deployment step creates a new entry in server.xml for the application, as follows:
<application name=app_name path=path_EARfile auto-start="true" />
where
The name attribute is the name of the application. The path indicates the directory and filename for the EAR file. The auto-start attribute indicates if this application should be automatically restarted each time OC4J is restarted.
1-14 Oracle Application Server Containers for J2EE Standalone User's Guide
Deploying Applications
For a description of the elements in server.xml, see "Elements in the server.xml File" on page B-6.
Binding the Web Application
To make your J2EE Web application accessible from the OC4J Web server, bind the Web application to the OC4J server using the -bindWebApp option as follows:
java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port username password -bindWebApp app_name web_app_name web_site_name context_root
where the following are the values for -bindWebApp:
app_name is the application name, which is the same name used in -deploymentName on the -deploy option. In addition, note that this is the same name that is saved in the <application name=app_name /> attribute in the server.xml file. web_app_name is the name of the WAR file contained within the EAR file--without the .war extension. web_site_name is the name of the *-web-site.xml file that denotes the Web site to which this Web application should be bound. This is the file that will receive the Web application definition. context_root is the root context for the Web module. The Web context defines how the Web application is accessed.
This step creates an entry in the OC4J *-web-site.xml configuration file that is denoted in the web_site_name variable. For a listing of all the options for admin.jar, see "Options for the OC4J Administration Management JAR" on page B-26.
Deploy Your Application Manually in a Development Environment
To deploy your application in a development environment, you can modify the XML files by hand. Ensure that automatic deployment is enabled by setting check-for-updates attribute to true. In server.xml, add a new or modify the existing <application name=... path=... auto-start="true" /> entry for each J2EE application. The path should be the full directory path and EAR filename. For our employee example, add the following to the server.xml file:
<application name="employee" path="/private/applications/Employee.ear" auto-start="true" />
If you included a Web application portion, you must do the following to bind the Web application to the Web server. In *-web-site.xml, add a <web-app ...> entry for each Web application. The application attribute should be the same value as provided in the server.xml file. The name attribute should be the WAR file, without the WAR extension, for the Web application. For Web application binding for the employee Web application, add the following:
<web-app application="employee" name="Employee-web" root="/employee" />
Configuration and Deployment
1-15
Deploying Applications
Verifying Deployment
OC4J detects the addition of your application to server.xml. The OC4J server displays a message that your application has been deployed. After the message is displayed, you can invoke requests against your application.
Impact of Undeploying/Redeploying an Application
Undeploying a J2EE application from an OC4J instance results in the following:
The application is removed from the OC4J runtime and is no longer accessible. All bindings for the Web applications are removed from all the Web sites to which the Web modules were bound. All application files are removed from both the applications/ and application-deployments/ directories.
During a redeployment, OC4J removes the existing application (EAR/WAR) before redeploying the new EAR. This means, for example, that attempts to access an HTML file that was included in the previous application, but not the new one, will result in "File Not Found" errors. Also note that a redeployed WAR file overlays the previously expanded WAR, meaning that some older files may persist in the new deployment and will need to be deleted. For example, static HTML files from the previous deployment that are not included in the new WAR may continue to reside in the expanded WAR directory structure, and we would have to be manually deleted.
Impact of "Hot Deploying" an Application
The term hot deployment refers to the process of deploying archive files - EARs, WARs, JARs, etc. - and their associated XML descriptor files on a production application server without re-starting or "bouncing" the server. When an EAR is redeployed or "hot redeployed" on a running OC4J instance, the status of the classes loaded in the JVM from the previous application may vary. In some cases a classloader may recognize that a class or JAR file in the file system has changed, and reload the class or libary. In other cases whether a new class definition is loaded may depend on whether the JVM tuning allows the garbage collector to flush the existing class definition. Issues may also exist with respect to serialized objects containing session data. If the class related to a session object changes, it may not be possible to cast the generic session object back to the class, since the class has changed and its variables may occupy a different memory footprint. This may result in lost session data. Deploying a new Web module to an active OC4J instance also has a negative impact on exising sessions. Specifically, the HTTP sessions for every Web application running within the server instance will be lost by default. You can avoid this issue on non-clustered OC4J instances by defining a "persistence directory" in each Web application's orion-web.xml file. Existing HTTP sessions will be stored in this temporary location across application deployments. Specify a relative path to this directory as the value of the persistence-path attribute in the root <orion-web-app> element within each orion-web.xml file. For example:
<orion-web-app ... persistence-path="persistDir"
1-16 Oracle Application Server Containers for J2EE Standalone User's Guide
Undeploying Web Applications
...> </orion-web-app>
Note that this feature is not applicable for OC4J instances within a clustered environment.
What Happens When You Deploy?
Whether you deploy the application through the admin.jar command or by editing XML files, the following occurs: OC4J opens the EAR file and reads the descriptors.
1.
OC4J opens, parses the application.xml that exists in the EAR file. The application.xml file lists all of the modules contained within the EAR file. OC4J notes these modules and initializes the EAR environment. OC4J reads the module deployment descriptors for each module type: Web module, EJB module, connector module, or client module. The J2EE descriptors are read into memory. If OC4J-specific descriptors are included, these are also read into memory. The JAR and WAR file environments are initialized. OC4J notes any unconfigured items that have defaults and writes these defaults in the appropriate OC4J-specific deployment descriptor. Thus, if you did not provide an OC4J-specific deployment descriptor, you will notice that OC4J provides one written with certain defaults. If you did provide an OC4J-specific deployment descriptor, you may notice that OC4J added elements. OC4J reacts to the configuration details contained in both the J2EE deployment descriptors and any OC4J-specific deployment descriptors. OC4J notes any J2EE component configurations that require action on OC4J's part, such as wrapping beans with their interfaces. After defaults have been added and necessary actions have been taken, OC4J writes out the new module deployment descriptors to the application-deployments/ directory. These are the descriptors that OC4J uses when starting and restarting your application. But do not modify these descriptors. Always change your deployment descriptors in the "master" location. OC4J copies the EAR file to the "master" directory. This defaults to the applications/ directory. However, you can designate where the "master" directory is by the admin.jar -targetPath option.
Note:
2.
3.
4.
5.
6.
If you deploy this EAR file using admin.jar without removing the EAR file from the applications/ directory, the new deployment renames the EAR file prepended with an underscore. It does not copy over the EAR file. Instead, you can copy over the EAR file. OC4J notices the change in the timestamp and redeploys.
7.
Finally, OC4J updates the server.xml file with the notation that this application has been deployed.
Undeploying Web Applications
You can remove a J2EE Web application from the OC4J Web server using the -undeploy option with the admin.jar command-line tool. The syntax is as follows:
Configuration and Deployment
1-17
Undeploying Web Applications
java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin adminpassword -undeploy applicationName -keepFiles
This command removes the deployed J2EE application known as applicationName and results in the following:
The application is removed from the OC4J runtime. All bindings for the Web modules are removed from all the Web sites to which the Web modules were bound. The application files are removed from both the applications/ and application-deployments/ directories. If you do not want these files to be removed, use the -keepFiles switch.
1-18 Oracle Application Server Containers for J2EE Standalone User's Guide
2
Advanced Configuration and Development
This chapter provides information for administering OC4J in standalone mode for development purposes. Chapter 1, "Configuration and Deployment", discusses the easiest method for configuring, developing, and deploying a J2EE application. However, if you want to use other services, such as JMS, you must know how to manipulate the XML configuration files. This chapter discusses the following topics:
Overview of OC4J and J2EE XML Files Sharing Libraries Manually Adding Applications in a Development Environment Building and Deploying Within a Directory OC4J Automatic Deployment for Applications Changing XML Files After Deployment Designating a Parent of Your Application Developing Startup and Shutdown Classes Setting Performance Options Enabling OC4J Logging OC4J Debugging
Overview of OC4J and J2EE XML Files
This section contains the following topics:
XML Configuration File Overview XML File Interrelationships
XML Configuration File Overview
Because OC4J is configured solely through XML files, you must understand the role and method for a set of XML files. Each XML file exists to satisfy a certain role; thus, if you have need of that role, you will understand which XML file to modify and maintain. Figure 21 illustrates all the OC4J XML files and their respective roles.
Advanced Configuration and Development
2-1
Overview of OC4J and J2EE XML Files
OC4J server: All XML files within this box are used to set up this instance of the OC4J server. These files configure things such as listening ports, administration passwords, security, and other basic J2EE services. OC4J server configuration files exist under the j2ee/home/config/ directory -- These files configure the OC4J server and point to other key configuration files. The settings in the OC4J configuration files are not related to the deployed J2EE applications directly, but to the server itself.
Web site: These XML files configure listening ports, protocols, and Web contexts for the OC4J Web site. Application XML files: Each J2EE application type (EJB, servlet, JSP, connector) requires its own configuration (deployment) files. Each application type has one J2EE deployment descriptor and one OC4J-specific deployment descriptor, which is denoted with an "orion-" prefix. In addition, the following are global configuration files for all components in the application: The application.xml as the global application configuration file that contains common settings for all applications in this OC4J instance. The orion-application.xml file contains OC4J-specific global application information for all applications in this OC4J instance. The global-web-application.xml file contains OC4J-specific global Web application configuration information that contains common settings for all Web modules in this OC4J instance. The oc4j-connectors.xml file contains global connector configuration information.
Figure 21 OC4J and J2EE Application Files
OC4J Server XML Files Server Configuration server.xml principals.xml data-sources.xml rmi.xml jms.xml loadbalancer.xml Web Site *-web-site.xml
Application XML Files Global Configuration application.xml orion-application.xml global-web-application.xml oc4j-connectors.xml EJB ejb-jar.xml orion-ejb-jar.xml Web Module web.xml orion-web.xml
Client application-client.xml orion-application-client.xml
Connector ra.xml oc4j-ra.xml
2-2 Oracle Application Server Containers for J2EE Standalone User's Guide
Overview of OC4J and J2EE XML Files
Note: Each deployed application uses an application.xml as the standard J2EE application descriptor file. That XML file is local to the application and separate from the application.xml that exists in the j2ee/home/config directory. The j2ee/home/config/application.xml file configures options that are applied to all applications deployed in this OC4J server instance.
Table 21 describes the role and function for each XML file that was displayed in the preceding figure.
Table 21 OC4J Features and Components Features/Components OC4J overall server configuration. Configures the server and points to the XML files that add to this file, such as jms.xml for JMS support. The listing of other XML files enables the services to be configured in separate files, but the server.xml file denotes that they be used for the OC4J configuration. OC4J security configuration for the type of security required for accessing the server. OC4J data source configuration for all databases used by applications within OC4J. OC4J RMI port configuration and RMI tunneling over HTTP. OC4J JMS configuration for Destination topics and queues that are used by JMS and MDBs in OC4J. OC4J Web site definition. Each Web site is defined within its own XML file. It is a good practice to name each XML file based on the root element name, <web-site>. For example, *-web-site.xml could be my-web-site.xml. Normally, the global Web site definition is in http-web-site.xml. You must specify each Web site XML file in its own web-site path statement contained within the server.xml file. J2EE application standard J2EE application descriptor file and configuration files.
XML Configuration File server.xml
principals.xml data-sources.xml rmi.xml jms.xml
*-web-site.xml
application.xml orion-application.xml
The global application.xml file exists in the j2ee/home/config directory and contains common settings for all applications in this OC4J instance. This file defines the location of the security XML definition file--principals.xml. This is a different XML file than the local application.xml files. The local application.xml file defines the J2EE EAR file, which contains the J2EE application modules. This file exists within the J2EE application EAR file. The orion-application.xml file is the OC4J-specific definitions for all applications.
Advanced Configuration and Development
2-3
Overview of OC4J and J2EE XML Files
Table 21 (Cont.) OC4J Features and Components XML Configuration File global-web-application.xml web.xml orion-web.xml Features/Components J2EE Web application configuration files.
global-web-application.xml is an OC4J-specific file for configuring servlets that are bound to all Web sites. web.xml and orion-web.xml for each Web application.
The web.xml files are used to define the Web application deployment parameters and are included in the WAR file. In addition, you can specify the URL pattern for servlets and JSPs in this file. For example, servlet is defined in the <servlet> element, and its URL pattern is defined in the <servlet-mapping> element. ejb-jar.xml orion-ejb-jar.xml J2EE EJB application configuration files. The ejb-jar.xml files are used to define the EJB deployment descriptors and are included in the EJB JAR file.
application-client.xml J2EE client application configuration files. orion-application-client.xml oc4j-connectors.xml ra.xml oc4j-ra.xml Connector configuration files.
The oc4j-connectors.xml file contains global OC4J-specific configuration for connectors. The ra.xml file contains J2EE configuration. The oc4j-ra.xml file contains OC4J-specific configuration.
XML File Interrelationships
Some of these XML files are interrelated. That is, some of these XML files reference other XML files--both OC4J configuration and J2EE application (see Figure 23). Here are the interrelated files:
server.xml--contains references to the following: All *-web-site files for each Web site for this OC4J server, including the default http-web-site.xml file. The location of each of the other OC4J server configuration files, except principals.xml, which is defined in the global application.xml, shown in Figure 21 The location of each application.xml file for each J2EE application that has been deployed in OC4J
http-web-site.xml--references applications by name, as defined in the server.xml file. And this file references an application-specific EAR file. application.xml--contains a reference to the principals.xml file.
The server.xml file is the keystone that contains references to most of the files used within the OC4J server. Figure 22 shows the XML files that can be referenced in the server.xml file:
2-4 Oracle Application Server Containers for J2EE Standalone User's Guide
Overview of OC4J and J2EE XML Files
Figure 22 XML Files Referenced Within server.xml
...j2ee/home/config/server.xml rmi.xml jms.xml application.xml data-sources.xml jazn-data.xml global-web-application.xml default-web-site.xml
O_1060
Figure 23 demonstrates how the server.xml points to other XML configuration files. For each XML file, the location can be the full path or a path relative to the location of where the server.xml file exists. In addition, the name of the XML file can be any name, as long as the contents of the file conform to the appropriate DTD.
The <rmi-config> element denotes the name and location of the rmi.xml file. The <jms-config> element denotes the name and location of the jms.xml file. The <global-application> element denotes the name and location of the global application.xml file. The <global-web-app-config> element denotes the name and location of the global-web-application.xml file. The <web-site> element denotes the name and location of one *-web-site.xml file. Since you can have multiple Web sites, you can have multiple <web-site> entries.
In addition to pointing to the OC4J server configuration files, the server.xml file describes the applications that have been deployed to this OC4J server. You can deploy applications through the admin.jar command using the -deploy option or by modifying the server.xml file directly. Each deployed application is denoted by the <application> element. See "Manually Adding Applications in a Development Environment" on page 2-7 for more information on directly editing the server.xml file.
Advanced Configuration and Development
2-5
Sharing Libraries
Figure 23 Server.xml File and Related XML Files
server.xml
<rmi...> rmi.xml
<jms...>
jms.xml
<global-application..path="application.xml"/>
application.xml
<global-web-app-config path="global-web-application.xml"/>
global-web-application.xml
<web-site path="./default-web-site.xml"/>
default-web-site.xml
<application name="bank_application".../>
bank_application
<application name="inventory_application".../>
inventory_application
Other elements for server.xml are described in "Elements in the server.xml File" on page B-6.
Sharing Libraries
If you have libraries that you want to share among applications, add a <library> element in the global application.xml file, indicating the directory where you are placing the libraries, as follows: Windows:
<library path="d:\oc4j\j2ee\home\applib\"/>
UNIX:
<library path="/private/oc4j/j2ee/home/applib/"/>
For each directory to be included, use a separate <library> element on a separate line, as follows:
<library path="/private/oc4j/j2ee/home/applib/"/> <library path="/private/oc4j/j2ee/home/mylibrary/"/>
As a default, a <library> element exists in the global application.xml file with the j2ee/home/applib directory. Instead of modifying the <library> element to contain other directories, you could move your libraries into the applib directory. However, note that adding libraries to this directory increases the size of OC4J and effects the performance as all libraries are searched for unknown classes. Use this with discretion.
2-6 Oracle Application Server Containers for J2EE Standalone User's Guide
O_1010
Manually Adding Applications in a Development Environment
Note: The default j2ee/home/applib directory is not created when OC4J is installed. If you want to add shared libraries to this directory, you must first create it before adding your libraries.
If you can, you should keep your shared libraries local to the application through the orion-application.xml file deployed with the application. You can add <library> elements in the orion-application.xml file for the application to indicate where the libraries are located, which are used only within the application.
Manually Adding Applications in a Development Environment
When you are in a development environment, it is easier to modify XML files than to use the admin.jar command for each iteration of development. The following sections help you understand how to modify your XML configuration files:
Configuring a Listener Configuring J2EE Applications
Configuring a Listener
Each OC4J server is configured to listen on HTTP or RMI protocols for incoming requests. Each OC4J Web server is configured within its own *-web-site.xml file.
HTTP protocol listener--HTTP clients can access an OC4J HTTP listener directly. This involves configuring an http-web-site.xml file, which indicates the HTTP listener port. The default HTTP port is 8888. The following shows the entry in the http-web-site.xml for an HTTP listener with a port number of 8888:
<web-site host="oc4j_host" port="8888" protocol="http" display-name="Default OC4J WebSite">
RMI protocol listener--EJB clients and the OC4J tools, such as admin.jar, access the OC4J server through a configured RMI port. This involves configuring the rmi.xml file. The default RMI port is 23791. The following shows the default RMI port number configured in the rmi.xml file:
<rmi-server port="23791" >
Configuring J2EE Applications
To configure and deploy your J2EE applications, modify the server.xml and http-web-site.xml files with your application information.
In server.xml, add a new or modify the existing <application name=... path=... auto-start="true" /> entry for each application that you want automatically started when OC4J starts. The path points to either the location of the EAR file to be deployed or the exploded directory where the application has been built. See "Deployment In a Production Environment Using ADMIN.JAR" on page 1-14 or "Building and Deploying Within a Directory" on page 2-8 for more information. In http-web-site.xml, add a <web-app...> entry for each Web application you want bound to the Web site upon OC4J startup. Because the name attribute is the WAR filename (without the .war extension), you must have one line for each WAR file included in your J2EE application. For Web application binding using a WAR file, add the following:
Advanced Configuration and Development 2-7
Building and Deploying Within a Directory
<web-app application="myapp" name="myapp-web" root="/myapp" />
The application attribute is the name provided in the server.xml as the application name. The name attribute is the name of the WAR file, without the .WAR extension. The root attribute defines the root context for the application off of the Web site. For example, if you defined your Web site as "http://oc4j_ host:8888", then to initiate the application, point your browser at "http://oc4j_host:8888/myapp".
Note:
Wait for automatic startup to complete before trying to access the client. The client fails on lookup if it tries to access before the completion of these processes.
Building and Deploying Within a Directory
When developing applications, you want to quickly modify, compile, and execute your classes. OC4J can automatically deploy your applications as you are developing them within an expanded directory format. OC4J automatically deploys applications if the timestamp of the top directory, noted by appname in Development Application Directory Structure, changes. This is the directory that server.xml knows as the "master" location. The application must be placed in the "master" directory in the same hierarchical format as necessary for JAR, WAR, and EAR files. For example, if appname is the directory where your J2EE application resides, Figure 24 displays the necessary directory structure.
2-8 Oracle Application Server Containers for J2EE Standalone User's Guide
Building and Deploying Within a Directory
Figure 24 Development Application Directory Structure
Development Application Directory Structure
To deploy EJB or complex J2EE applications in an expanded directory format, complete the following steps:
1.
Place the files in any directory. Figure 24 demonstrates an application placed into j2ee/home/applications/appname/. The directory structure below appname is similar to that used within an EAR file, as follows:
a.
Replace the EJB JAR file name, Web application WAR file name, client JAR file name, and Resource Adapter Archive (RAR) file name with a directory name of your choosing to represent the separate modules. Figure 24 demonstrates these directory names by ejb_module/, web_module/, client_module/, and connector_module/. Place the classes for each module within the appropriate directory structure that maps to their package structure.
b. 2.
Modify the server.xml, application.xml, and *-web-site.xml files. The server.xml and *-web-site.xml files are located in j2ee/home/config directory, while the application.xml is under j2ee/home/applications/<appname>/META-INF directory. Modify these files as follows:
In server.xml, add a new or modify the existing <application name=... path=... auto-start="true" /> element for each J2EE application. The path points to the "master" application directory. In Figure 24, this is j2ee/home/applications/appname/.
Advanced Configuration and Development
2-9
OC4J Automatic Deployment for Applications
You can specify the path in one of two manners: * Specifying the full path from root to the parent directory. In the example in Figure 24, if appname is "myapp", then the fully-qualified path is as follows:
<application_name="myapp" path="/private/j2ee/home/applications/myapp" auto-start="true" />
*
Specifying the relative path. The path is relative to where the server.xml file exists to where the parent directory lives. In the example in Figure 24, if appname is "myapp", then the relative path is as follows:
<application_name="myapp" path="../applications/myapp" auto-start="true" />
In application.xml, modify the <module> elements to contain the directory names for each module--not JAR or WAR files. You must modify the <web-uri>, the <ejb>, and the <client> elements in the application.xml file to designate the directories where these modules exist. The path included in these elements should be relative to the "master" directory and the parent of the WEB-INF or META-INF directories in each of these application types. For example, if the web_module/ directory in Figure 24 was "myapp-web/", then the following example designates this as the Web module directory within the <web-uri> element as follows:
<module> <web> <web-uri>myapp-web</web-uri> </web> </module>
In the *-web-site.xml file, add a <web-app...> element for each Web application. This is important, because it binds the Web application within the Web site. The application attribute value should be the same value as that provided in the server.xml file. The name attribute should be the directory for the Web application. Note that the directory path given in the name element follows the same rules as for the path in the <web-uri> element in the application.xml file. To bind the"myapp" Web application, add the following:
<web-app application="myapp" name="myapp-web" root="/myapp" />
Note:
You achieve better performance if you are deploying with an EAR file. During execution, the entire EAR file is loaded into memory and indexed. This is faster than reading in each class from the development directory when necessary.
OC4J Automatic Deployment for Applications
OC4J automatically deploys an application if the timestamp on an EAR file has changed. Restarting OC4J to deploy or redeploy applications is not necessary.
2-10 Oracle Application Server Containers for J2EE Standalone User's Guide
Changing XML Files After Deployment
Automatic deployment is not enabled in all cases, but deployment occurs in the following cases:
changes to EAR files are checked If you change the EAR file, OC4J automatically detects the change. OC4J detects the timestamp change and redeploys the application.
change in timestamp of certain XML files in the exploded directory format (The appname directory) that is discussed in "Building and Deploying Within a Directory" on page 2-8. For automatic deployment of exploded directory applications, you must do the following:
1.
Modify the classes in the <module> and touch its J2EE deployment descriptor to change the timestamp on the XML file. For example, if you modify servlet classes, you must touch its web.xml file. This notifies OC4J that changes occurred in this <module>. Touch the application.xml of this application. Changing the timestamp of the application.xml starts the automatic deployment. Once started, OC4J checks which modules to redeploy by noticing which module deployment descriptors have timestamp changes.
2.
When OC4J does not check for updates, redeploy by either using the admin.jar command-line tool or restarting the OC4J server manually. See "Options for the OC4J Administration Management JAR" on page B-26 for a description of the -deploy option.
Changing XML Files After Deployment
Whenever you deploy an application, OC4J automatically generates the OC4J-specific XML files with the default elements. If you want to change these files or add to the existing XML files, you must copy the XML files to where your original development directory for the application and change it in this location. If you change the XML file within the deployed location, OC4J simply overwrites these changes when the application is deployed again. The changes only stay constant when changed in the development directories. For all OC4J-specific XML files, you can add these files within the recommended development structure as shown in Figure 25.
Advanced Configuration and Development 2-11
Designating a Parent of Your Application
Figure 25 Development Application Directory Structure
Designating a Parent of Your Application
A child application can see the namespace of its parent application. Thus, setting up an application as a parent is used to share services among children. The default parent is the global application. To set up an application as a parent of another, you can do one of the following:
Use the -parent option of the admin.jar command when deploying the originating application. This option allows you to designate what application will be the parent of the deploying application. Specify the parent in the application definition line in the server.xml file. Each application is defined by an <application> element in the server.xml file. In this element, a parent attribute designates the parent application.
<application ... parent="applicationWithCommonClasses" .../>
Developing Startup and Shutdown Classes
You can develop classes that are called after OC4J initializes or before OC4J terminates. Startup classes can start services and perform functions after OC4J initiates; shutdown classes can terminate these services and perform functions before OC4J terminates. The oc4j.jar must be in the Java CLASSPATH when you compile these classes. OC4J deploys and executes the OC4J startup and shutdown classes based on configuration of these classes in the server.xml file.
2-12 Oracle Application Server Containers for J2EE Standalone User's Guide
Developing Startup and Shutdown Classes
OC4J Startup Classes OC4J Shutdown Classes
OC4J Startup Classes
Startup classes are executed only once after OC4J initializes. They are not re-executed everytime the server.xml file is touched. Your startup class implements the com.evermind.server.OC4JStartup interface that contains two methods--preDeploy and postDeploy--in which you can implement code for starting services or performing other initialization routines.
The preDeploy method executes before any OC4J application initialization. The postDeploy method executes after all OC4J applications initialize.
Each method requires two arguments--a Hashtable that is populated from the configuration and a JNDI Context to which you can bind to process values contained within the Context. Both methods return a String, which is currently ignored. Once created, you must configure the startup class within the <startup-classes> element in the server.xml file. Each OC4JStartup class is defined in a single <startup-class> element within the <startup-classes> element. Each <startup-class> defines the following:
The name of the class that implements the com.evermind.server.OC4JStartup interface. Whether a failure is fatal. If considered fatal, then when an exception is thrown, OC4J logs the exception and exits. If not considered fatal, then OC4J logs the exception and continues. Default is not fatal. The order of execution where each startup class receives an integer number that designates in what order the classes are executed. The initialization parameters that contain key-value pairs, of type String, which OC4J takes, which are provided within the input Hashtable argument. The names for the key-value pairs must be unique, as JNDI is used to bind each value to its name.
In the <init-library path="../[xxx]" /> element in the server.xml file, configure the directory where the startup class resides, or the directory and JAR filename where the class is archived. The path attribute can be fully-qualified or relative to j2ee/home/config.
Example 21 Startup Class Example
The configuration for the TestStartup class is contained within a <startup-class> element in the server.xml file. The configuration defines the following:
The failure-is-fatal attribute is true, so that an exception causes OC4J to exit. The execution-order is 0, so that this is the first startup class to execute. Two initialization key-value pairs defined, of type String, which will be populated in the Hashtable, of the following:
"oracle.test.startup" "true" "startup.oracle.year" "2002"
Advanced Configuration and Development 2-13
Developing Startup and Shutdown Classes
Note:
The names of the key-value pairs must be unique in all startup and shutdown classes, as JNDI binds the name to its value.
Thus, configure the following in the server.xml file to define the TestStartup class:
<startup-classes> <startup-class classname="TestStartup" failure-is-fatal="true"> <execution-order>0</execution-order> <init-param> <param-name>oracle.test.startup</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>startup.oracle.year</param-name> <param-value>2002</param-value> </init-param> </startup-class> </startup-classes>
The container provides the two initialization kay-value pairs within the input Hashtable parameter to the startup class. The following example shows TestStartup, which implements the com.evermind.server.OC4JStartup interface. The preDeploy method retrieves the key-value pairs from the Hashtable and prints them out. The postDeploy method is a null method. The oc4j.jar must be in the Java CLASSPATH when you compile TestStartup.
import com.evermind.server.OC4JStartup; import javax.naming.*; import java.util.*; public class TestStartup implements OC4JStartup { public String preDeploy(Hashtable args, Context context) throws Exception { // bind each argument using its name Enumeration keys = args.keys(); while(keys.hasMoreElements()) { String key = (String)keys.nextElement(); String value = (String)args.get(key); System.out.println("prop: " + key + " value: " + args.get(key)); context.bind(key, value); } return "ok"; } public String postDeploy(Hashtable args, Context context) throws Exception { return null; } }
Assuming that the TestStartup class is archived in "../app1/startup.jar", modify the <init-library> element in the server.xml file as follows:
<init-library path="../app1/startup.jar" />
2-14 Oracle Application Server Containers for J2EE Standalone User's Guide
Setting Performance Options
When you start OC4J, the preDeploy method is executed before any application is initialized. OC4J populates the JNDI context with the values from the Hashtable. If TestStartup throws an exception, then OC4J exits since the failure-is-fatal attribute was set to TRUE.
OC4J Shutdown Classes
Shutdown classes are executed before OC4J terminates. Your shutdown class implements the com.evermind.server.OC4JShutdown interface that contains two methods--preUndeploy and postUndeploy--in which you can implement code for shutting down services or perform other termination routines.
The preUndeploy method executes before any OC4J application terminates. The postUndeploy method executes after all OC4J applications terminates.
Each method requires two arguments--a Hashtable that is populated from the configuration and a JNDI Context to which you can bind to process values contained within the Context. The implementation and configuration is identical to the shutdown classes as described in "OC4J Startup Classes" on page 2-13 with the exception that the configuration is defined within the <shutdown-classes> and <shutdown-class> elements and there is no failure-is-fatal attribute. Thus, the configuration for a TestShutdown class would be as follows:
<shutdown-classes> <shutdown-class classname="TestShutdown"> <execution-order>0</execution-order> <init-param> <param-name>oracle.test.shutdown</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>shutdown.oracle.year</param-name> <param-value>2002</param-value> </init-param> </shutdown-class> </shutdown-classes>
Assuming that the TestShutdown class is archived in "../app1/shutdown.jar", add another <init-library> element in the server.xml file as follows:
<init-library path="../app1/shutdown.jar" />
Setting Performance Options
Most performance settings are discussed in the Oracle Application Server Performance Guide. You can manage these performance settings yourself from either the OC4J command-line option or by editing the appropriate XML file element.
Performance Command-Line Options Thread Pool Settings Statement Caching Task Manager Granularity
Advanced Configuration and Development 2-15
Setting Performance Options
Performance Command-Line Options
Each -D command-line option, except for the dedicated.rmicontext option, defaults to the recommended setting. However, you can modify these options by providing each -D command-line option as an OC4J option. See the "Standalone OC4J Command-Line Options and Properties" on page B-26 for an example.
dedicated.rmicontext=true/false. The default value is false. This replaces the deprecated dedicated.connection setting. When two or more clients in the same process retrieve an InitialContext, OC4J returns a cached context. Thus, each client receives the same InitialContext, which is assigned to the process. Server lookup, which results in server load balancing, happens only if the client retrieves its own InitialContext. If you set dedicated.rmicontext=true, then each client receives its own InitialContext instead of a shared context. When each client has its own InitialContext, then the clients can be load balanced. This parameter is for the client. You can also set this in the JNDI properties.
oracle.dms.sensors=[none, normal, heavy, all]. You can set the value for Oracle Application Server built-in performance metrics to the following: None (off), normal (medium amount of metrics), heavy (high number of metrics), or all (all possible metrics). The default is normal.This parameter should be set on the OC4J server. The previous method for turning on these performance metrics, oracle.dms.gate=true/false, is replaced by the oracle.dms.sensors variable. However, if you still use oracle.dms.gate, then setting this variable to false is equivalent to setting oracle.dms.sensors=none. DefineColumnType=true/false. The default is false. Set this to true if you are using an Oracle JDBC driver that is prior to 9.2. For these drivers, setting this variable to true avoids a round-trip when executing a select over the Oracle JDBC driver. This parameter should be set on the OC4J server. When you change the value of this option and restart OC4J, it is only valid for applications deployed after the change. Any applications deployed before the change are not affected. When true, the DefineColumnType extension saves a round trip to the database that would otherwise be necessary to describe the table. When the Oracle JDBC driver performs a query, it first uses a round trip to a database to determine the types that it should use for the columns of the result set. Then, when JDBC receives data from the query, it converts the data, as necessary, as it populates the result set. When you specify column types for a query with the DefineColumnType extension set to true, you avoid the first round trip to the Oracle database. The server, which is optimized to do so, performs any necessary type conversions.
Thread Pool Settings
Thread pools create and maintain a "queue" of threads for use by an OC4J process. Re-using existing threads rather than creating new threads on demand improves performance and reduces the burden on the JVM and underlying operating system. By default, a single thread pool is created at OC4J startup. New threads are created and added to the pool on an as-needed basis. As each thread is released, it is returned to the pool to wait until it is needed by a new request. Idle threads In the pool are used
first before a new thread is spawned.
Threads in the pool are automatically destroyed after 10 minutes of inactivity. There is no limit on the number of threads that can be created in this configuration.
2-16 Oracle Application Server Containers for J2EE Standalone User's Guide
Setting Performance Options
The default configuration should by sufficient for most OC4J usage scenarios. However, you can optionally modify the single thread pool created by default through the min, max, queue, and keepAlive attributes of the <global-thread-pool> element in the server.xml file. Alternatively, you can create two thread pools using <global-thread-pool>, with different types of threads divided among the pools:
The worker thread pool contains worker threads used in processing RMI , HTTP and AJP requests, as well as MDB listener threads. These are process-intensive and use database resources. The connection thread pool contains threads such as listener threads, JDBC connection threads, RMI server and HTTP server connection threads, and background threads. These threads are typically not process intensive.
To create two pools, you must configure the min, max, queue, and keepAlive attributes for the worker thread pool and the cx-min, cx-max, cx-queue, and cx-keepAlive attributes for the connection thread pool. All of these attributes must be configured if creating pools; otherwise you will see the following error message:
Error initializing server: Invalid Thread Pool parameter: null
See Table 22 on page 2-17 for descriptions of the attributes of <global-thread-pool>. The following example initializes two thread pools for the OC4J process. Each contains a minimum of 10 threads and maximum of 100 threads. The number of requests outstanding in each queue can be 200 requests. Also, idle threads are kept alive for 700 seconds. The thread pool information is printed at startup.
<application-server ...> ... <global-thread-pool min="10" max="100" queue="200" keepAlive="700000" cx-min="10" cx-max="100" cx-queue="200" cx-keepAlive="700000" debug="true"/> ... </application-server>
Table 22 below describes the attributes of the <global-thread-pool> element. Note that this element is not included in server.xml by default.
Table 22 Attribute min Attributes of <global-thread-pool> Description The minimum number of threads to create in the pool. By default, a minimum number of threads are preallocated and placed in the thread pool when the container starts. If you add the <global-thread-element> element to server.xml, the default value is set to 20. The minimum value that can be specified is 10. max The maximum number of threads that can be created in the pool. New threads are spawned if the maximum size is not reached and if there are no idle threads. Idle threads are used first before a new thread is spawned. The default is 40. queue The maximum number of requests that can be kept in the queue. The default is 80.
Advanced Configuration and Development 2-17
Setting Performance Options
Table 22 (Cont.) Attributes of <global-thread-pool> Attribute keepAlive Description The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. After the timeout is reached, the thread is destroyed. To never destroy threads, set to -1. The default is 600000 milliseconds (10 minutes), which is also the minimum value allowed if not -1. cx-min The minimum number of threads to create in the connection thread pool. The minimum value that can be specified is 10. cx-max cx-queue cx-keepAlive The maximum number of threads that can be created in the connection pool. The default is 40. The maximum number of threads that can be kept in the queue in the connection pool. The default is 80. The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. After the timeout is reached, the thread is destroyed. To never destroy threads, set to -1. The default is 600000 milliseconds (10 minutes), which is also the minimum value allowed if not -1. debug If true, print the application server thread pool information to the console at startup. The default is false.
Additional notes on thread pool configuration:
The queue attributes should be at least twice the size of the maximum number of threads. The minimum and maximum number of worker threads should be a multiple of the number of CPUs installed on your machine. However, this number should be small; the more threads you have, the more burden you put on the operating system and the garbage collector. The cx-min and cx-max attributes are relative to the number of the physical connections you have at any point in time. The cx-queue handles bursts in connection traffic.
Statement Caching
You can cache database statements, which prevents the overhead of repeated cursor creation and repeated statement parsing and creation. In the DataSource configuration, you enable JDBC statement caching, which caches executable statements that are used repeatedly. A JDBC statement cache is associated with a particular physical connection. See Oracle9i JDBC Developer's Guide and Reference for more information on statement caching. You can dynamically enable and disable statement caching programmatically through the setStmtCacheSize() method of your connection object or through the stmt-cache-size XML attribute in the DataSource configuration. An integer value is expected with the size of the cache. The cache size you specify is the maximum number of statements in the cache. The user determines how many distinct statements the application issues to the database. Then, the user sets the size of the cache to this number. If you do not specify this attribute or set it to zero, this cache is disabled.
2-18 Oracle Application Server Containers for J2EE Standalone User's Guide
Enabling OC4J Logging
Example 22 Statement Caching
The following XML sets the statement cache size to 200 statements.
<data-source> ... stmt-cache-size="200" </data-source>
Task Manager Granularity
The task manager is a background process that performs cleanup. However, the task manager can be expensive. You can manage when the task manager performs its duties through the taskmanager-granularity attribute in server.xml. This element sets how often the task manager is kicked off for cleanup. Value is in milliseconds. Default is 1000 milliseconds.
<application-server ... taskmanager-granularity="60000" ...>
Enabling OC4J Logging
OC4J logs messages both to standard error, standard out, and several log files for OC4J services and deployed applications.
Viewing OC4J System and Application Log Messages: This section describes the separate log files for OC4J sub-systems and deployed applications. You can manage how large these files can be and where they are located. Redirecting Standard Out and Standard Error: This section describes how to forward standard out and standard error messages to a log file.
Note: Also, OC4J supports Jakarta log4j. See the "Open Source Frameworks and Utilities" appendix in the Oracle Application Server Containers for J2EE Servlet Developer's Guide.
Viewing OC4J System and Application Log Messages
Each OC4J process has a set of log files, as shown in Table 23. If there are multiple processes running for an OC4J instance, there is a multiple set of log files.
Table 23 List of Log Files Generated for OC4J Description Scope Configuration File orion-application. xml application.xml
Default Log File Name application.log global-application .log jms.log rmi.log server.log
All events, errors, and exceptions One log file for each for a deployed application. application deployed. All common events, errors, and exceptions related to applications. All JMS events and errors. All RMI events and errors. All events not associated with a particular sub-system or an application. This logs history of server startup, shutdown internal server errors. Logs all accesses to the Web site. All applications, including the default application. JMS sub-system RMI sub-system server-wide
jms.xml rmi.xml server.xml
web-access.log
Each Web site
http-web-site.xml
Advanced Configuration and Development 2-19
Enabling OC4J Logging
There are two types of log files:
Text Log Files: The messages logged in these files are text-based and not in XML format. You can read these messages with any editor. This is the default. Normally, those who use OC4J standalone would benefit from viewing their log messages in a text format. Oracle Diagnostic Logging (ODL) Log Files: The messages logged in these files use an XML format that can be read by a GUI tool, such as the Oracle Enterprise Manager 10g GUI. We recommend that you use this format for your logging when you are using OC4J within Oracle Application Server.
Text Log Files
Full text logging is still available in OC4J. Primarily, you should use text logging within OC4J standalone. It is easier to read within any editor, as it is not in XML format. The text logging facility separates messages out in alignment with the XML files. However, instead of writing to multiple log files of the same size, all messages for that component are written into a single file. The text logging does not have any imposed limits or log rollover. Instead, the log files will continue to grow, unless you stop OC4J, remove the file, and restart OC4J to start the log files over. You can overrun your disk space if you do not monitor your log files. This is only feasible in a standalone, development environment. Text messaging is the default and is configured in the XML files in Table 23. Text messaging is enabled in the <file> subelement the <log> element of the XML files, except the http-web-site.xml file. For the http-web-site.xml file, the text messaging is enabled with the <access-log> element. To turn off text messaging, eliminate or comment out the <file> or <access-log> element. If you do not remove this line and enable ODL logging, you will have both logging facilities turned on. The location and filename for text messaging does have defaults, as shown in Table 24, but you can specify the location and filename within the path attribute of the <log> or <access-log> elements. Table 24 shows the default location for the log files for a standalone OC4J. You can modify the location and names of these files by modifying the configuration files described in Table 23.
Table 24 Log File application.log global-application.log jms.log rmi.log server.log web-access.log OC4J Standalone Log File Locations Default Location install_dir/j2ee/home/application-deployments/<application-name> install_dir/j2ee/home/log install_dir/j2ee/home/log install_dir/j2ee/home/log install_dir/j2ee/home/log The location is configurable from *-web-site.xml with the <access-log> element, as follows: <access-log path="../log/http-web-access.log" />
The location of all of the above log files can be specified, except the web-access.log file, using the <log> element in the respective configuration files. You can specify either absolute paths or paths relative to the j2ee/home/config directory. For example, specify the server log file in the server.xml configuration file, as follows:
<log> 2-20 Oracle Application Server Containers for J2EE Standalone User's Guide
Enabling OC4J Logging
<file path="../log/my-server.log" /> </log>
You can also specify an absolute path for the location of the log file, as follows:
<log> <file path="d:\log-files\my-server.log" /> </log>
Oracle Diagnostic Logging (ODL) Log Files
The ODL log entries are each written out in XML format in its respective log file. Each XML message can be read through your own XML reader. The advantages for ODL logging is that the log files and the directory have a maximum limit. When the limit is reached, the log files are overwritten. When you enable ODL logging, each new message goes into the current log file, named log.xml. When the log file is full--that is, the log file size maximum is reached--then it is copied to an archival log file, named logN.xml, where N is a number starting at one. When the last log file is full, the following occurs:
1. 2.
The least recent log file is erased to provide space in the directory. The log.xml file is written to the latest logN.xml file, where N increments by one over the most recent log file.
Thus, your log files are constantly rolling over and do not encroach on your disk space. Within each XML file listed in Table 23, you enable ODL logging by uncommenting the ODL configuration line, as follows:
Uncomment the <odl> element within the <log> element in all XML files listed in Table 23, except for the http-web-site.xml file. Add the <odl-access-log> element in the http-web-site.xml file.
The attributes that you can configure are:
path: Path and folder name of the log folder for this area. You can use an absolute path or a path relative to where the configuration XML file exists, which is normally in the j2ee/home/config directory. This denotes where the log files will reside for the feature that the XML configuration file is concerned with. For example, modifying this element in the server.xml file denotes where the server log files are written. max-file-size: The maximum size in KB of each individual log file. max-directory-size: The maximum size of the directory in KB.
New files are created within the directory, until the maximum directory size is reached. Each log file is equal to or less than the maximum specified in the attributes. Thus, to specify log files of 1000 KB and a maximum of 10,000 KB for the directory in the <install-dir>/j2ee/home/log/server directory in the server.xml file, configure the following:
<log> <odl path="../log/server/" max-file-size="1000" max-directory-size="10000" /> </log>
When OC4J is executing, all log messages that are server oriented are logged in the <install-dir>/j2ee/home/log/server directory.
Advanced Configuration and Development 2-21
Enabling OC4J Logging
The XML message that is logged is of the following format:
<MESSAGE> <HEADER> <TSTZ_ORIGINATING>2002-11-12T15:02:07.051-08:00</TSTZ_ORIGINATING> <COMPONENT_ID>oc4j</COMPONENT_ID> <MSG_TYPE TYPE="ERROR"></MSG_TYPE> <MSG_LEVEL>1</MSG_LEVEL> <HOST_ID>myhost</HOST_ID> <HOST_NWADDR>001.11.22.33</HOST_NWADDR> <PROCESS_ID>null-Thread[Orion Launcher,5,main]</PROCESS_ID> <USER_ID>dpda</USER_ID> </HEADER> <PAYLOAD> <MSG_TEXT>java.lang.NullPointerException at com.evermind.server.ApplicationServer.setConfig(ApplicationServer.java:1070) at com.evermind.server.ApplicationServerLauncher.run (ApplicationServerLauncher.java:93) at java.lang.Thread.run(Unknown Source) </MSG_TEXT> </PAYLOAD> </MESSAGE/>
You can have both the ODL and text logging turned on. To save on disk space, you should turn off one of these options. If you decide to enable ODL logging, turn off the text logging functionality by commenting out the <file> subelement of the <log> element for all XML files except the http-web-site.xml file. For the http-web-site.xml file, turn off the text logging by commenting out the <access-log> element.
Redirecting Standard Out and Standard Error
Many developers use the System.out.println() and System.err.println() methods in their applications to generate debug information. Normally, the output from these method calls are printed to the console where the OC4J process is started. However, you can specify command-line options when starting OC4J to direct the STDOUT and STDERR output directly to files. The -out and -err parameters inform OC4J where to direct the error messages. The following startup command includes and example of the -out and -err parameters:
$ java -jar oc4j.jar -out d:\log-files\oc4j.out -err d:\log-files\oc4j.err
In this case, all information written to STDOUT and STDERR is printed to the files d:\log-files\oc4j.out and d:\log-files\oc4j.err respectively.
Disabling Access Logging for a Web Application
In the OC4J 10.1.2 implementation, there is new functionality in Web site XML files to disable OC4J access logging (used to log requests to the Web site) on a per-module basis. In general, text-based access logging is enabled for a Web site through the <access-log> subelement of the <web-site> element in the Web site XML file (such as default-web-site.xml or http-web-site.xml). Alternatively, Oracle Diagnostic Logging ("ODL-based access logging") is enabled for a Web site through the <odl-access-log> subelement of the <web-site> element. As of the 10.1.2 release, you can disable text-based logging or ODL-based logging (as applicable) for a particular Web application (module) through the new access-log attribute of the <web-app> element for that Web application. The <web-app>
2-22 Oracle Application Server Containers for J2EE Standalone User's Guide
OC4J Debugging
element is another subelement of <web-site>. A setting of access-log="false" for a Web application overrides any <access-log> or <odl-access-log> element to disable logging during the operation of that Web application. The following example disables logging for the dms0 module of the default application, but leaves text-based logging enabled for the admin_web module:
<web-site ... > ... <web-app application="default" name="dms0" root="/dms0" access-log="false" /> <web-app application="default" name="admin_web" root="/adminoc4j" /> <access-log path="../log/http-web-access.log" /> ... </web-site>
Notes: The default setting is access-log="true". With this setting, functionality is the same as for previous releases, with logging being determined solely through the presence or absence of an <access-log> or <odl-access-log> element.
If there is no <access-log> or <odl-access-log> element in a Web site XML file, then logging is disabled anyway and access-log="false" for an application has no additional effect. See the 10.1.2 release of the Oracle Application Server Containers for J2EE Servlet Developer's Guide for related information about access logging.
OC4J Debugging
OC4J provides several debug properties for generating additional information on the operations performed by the various sub-systems of OC4J. These debug properties can be set for a particular sub-system while starting up OC4J.
Note:
Turning on excessive debug options can slow down the execution of your applications and use large amounts of disk space with the contents of the log files.
The following table provides useful debug options available with OC4J. These debug options have two states either true or false. By default these are set to false. For a complete list of debug properties, see "OC4J System Properties" on page B-33.
Table 25 HTTP Debugging Options Description of Option Provides information about HTTP session events Provides information about each HTTP request Prints all HTTP errors Default: false. If true, turns on the trace HTTP method.
HTTP Debugging http.session.debug http.request.debug http.error.debug http.method.trace.allow
Advanced Configuration and Development 2-23
OC4J Debugging
Table 26
JDBC Debugging Options Description of Option Provides verbose information on creation of data source and connections using Data Sources and connections released to the pool, and so on, Provides very verbose information when JDBC calls are made
JDBC Debugging datasource.verbose
jdbc.debug
Table 27
RMI Debugging Options Description of Options Prints RMI debug information Provides very verbose information on RMI calls
RMI Debugging rmi.debug rmi.verbose
Table 28
OracleAS Web Services Debugging Options Description of Options Turns on Web Services debugging
OracleAS Web Services Debugging ws.debug
For example, if you want to generate debug information on HTTP session events then you start OC4J, as follows:
java -Dhttp.session.debug=true -jar oc4j.jar
After OC4J is started with a specific debug option, debug information is generated and routed to standard output. In the above example, you would see HTTP session information on your OC4J console, as follows:
Oracle Application Server Containers for J2EE initialized Created session with id '36c04d8a1cd64ef2b6a9ba6e2ac6637e' at Mon Apr 15 12:24:20 PDT 2002, secure-only: false Created session with id '36c04d8a1cd64ef2b6a9ba6e2ac6637e' at Mon APR 15 12:36:06 PDT 2002, secure-only: false Invalidating session with id '36c04d8a1cd64ef2b6a9ba6e2ac6637e' at Mon APR 15 12:44:32 PDT 2002 (created at Mon APR 15 12:24:23 PDT 2002) due to timeout
If you want to save this debug information, then you can redirect your standard output to a file using the -out or -err command-line options, as follows:
java -Dhttp.session.debug=true -jar oc4j.jar -out oc4j.out -err oc4j.err
In addition to the specific sub-system switches, you can also start OC4J with a supplied verbosity level. The verbosity level is an integer between 1 and 10. The higher the verbosity level, the more information that is printed in the console. You specify the verbosity level with the -verbosity OC4J option in the OC4J command-line options. The following examples show the output with and without verbosity:
Example 23 Error Messages Displayed Without Veribosity D:\oc4j903\j2ee\home>java -jar oc4j.jar Oracle Application Server Containers for J2EE initialized Example 24 Error Messages Displayed With Verbosity Level of 10 D:\oc4j903\j2ee\home>java -jar oc4j.jar -verbosity 10 Application default (default) initialized...
2-24 Oracle Application Server Containers for J2EE Standalone User's Guide
OC4J Debugging
Binding EJB work.ejb.WorkHours to work.ejb.WorkHours... Application work (work) initialized... Application serv23 (Servlet 2.3 New Features Demo) initialized... Web-App default:defaultWebApp (0.0.0.0/0.0.0.0:8888) started... Oracle Application Server Containers for J2EE initialized
Servlet Debugging Example
You deployed a Web application to OC4J that is having some problems with servlets. You are losing the client session when you use a pre-configured data source to make database connection. You want to know what OC4J is doing when the servlet is accessing the data source. In order to generate the debug information on HTTP Session and data source usage, you must set two debug options - http.session.debug and datasource.verbose to true.
java -Dhttp.session.debug=true -Ddatasource.verbose=true -jar oc4j.jar
Then, re-execute your servlet and see the following type of debug information in the standard output for the OC4J process:
DataSource logwriter activated... jdbc:oracle:thin:@localhost:1521/MYSERVICE: Started jdbc:oracle:thin:@localhost:1521/MYSERVICE: Started Oracle Application Server Containers for J2EE initialized Created session with id '4fa5eb1b9a564869a426e8544963754f' at Tue APR 23 16:22:56 PDT 2002, secure-only: false Created new physical connection: XA XA OC4J Pooled jdbc:oracle:thin:@localhost:1521/MYSERVICE null: Connection XA XA OC4J Pooled jdbc:oracle:thin:@localhost:1521/MYSERVICE allocated (Pool size: 0) jdbc:oracle:thin:@localhost:1521/MYSERVICE: Opened connection Created new physical connection: Pooled oracle.jdbc.driver.OracleConnection@5f18 Pooled jdbc:oracle:thin:@localhost:1521/MYSERVICE: Connection Pooled oracle.jdbc.driver.OracleConnection@5f1832 allocated (Pool size: 0) Pooled jdbc:oracle:thin:@localhost:1521/MYSERVICE: Releasing connection Pooled oracle.jdbc.driver.OracleConnection@5f1832 to pool (Pool size: 1) null: Releasing connection XA XA OC4J Pooled jdbc:oracle:thin:@localhost:1521/MYSERVICE to pool (Pool size: 1) OC4J Pooled jdbc:oracle:thin:@localhost:1521/MYSERVICE: Cache timeout, closing connection (Pool size: 0) com.evermind.sql.OrionCMTDataSource/default/jdbc/OracleDS: Cache timeout, closing connection (Pool size: 0)
Advanced Configuration and Development 2-25
OC4J Debugging
2-26 Oracle Application Server Containers for J2EE Standalone User's Guide
3
Configuring Security
OC4J security employs a user manager to authenticate and authorize users and groups that attempt to access a J2EE application. User managers differ in performance and are employed based on the security you require. Confidentiality through encryption is supplied with SSL. This chapter describes the following topics:
Overview of Security Functions Authentication Authorization Plugging In a User Manager Confidentiality Through SSL
For a broader description of Oracle Application Server security, see the Oracle Application Server Security Guide and the Oracle Application Server Containers for J2EE Security Guide.
Overview of Security Functions
OC4J security is based on a two-step process. First, a user or group attempting to access a J2EE application is authenticated, and then it is authorized. Authentication and authorization are provided under various user managers, such as the JAZNUserManager and XMLUserManager classes. The JAZNUserManager class is the default and offers the best security. The XMLUserManager is the simplest method for security. The JAZNUserManager leverages the OracleAS JAAS Provider as the security infrastructure for OC4J by using either the Lightweight Directory Access Protocol (LDAP)-based or the XML-based provider type. The XMLUserManager is configured using a file, so the passwords are visible. See "Plugging In a User Manager" on page 3-8 for details on the OracleAS JAAS Provider, provider types, and user managers. Also, see the Oracle Application Server Containers for J2EE Security Guide for details on the OracleAS JAAS Provider and provider types.
Note:
The default user manager was changed from the XMLUserManager to the JAZNUserManager.
Authentication and authorization, along with OC4J confidentiality, are introduced below:
Authentication: Verifies the identity and credentials of a user.
Configuring Security 3-1
Authentication
Defines users and groups in a user repository. A user repository is employed by a user manager to verify the identity of a user or group attempting to access a J2EE application. A user repository can be a file or a directory server, depending on your environment. The Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider LDAP user manager and the XMLUserManager are two examples of user repositories. Although the J2EE application determines which client can access the application, it is the user manager, employing the user name and password, that verifies the client's identity, based on information in the user repository.
Authorization: Permits or denies users and groups access to an application. Specifies authorization for users and groups (identities) in the J2EE and OC4J-specific deployment descriptors. J2EE and OC4J-specific deployment descriptors indicate what roles are needed to access the different parts of the application. Roles are the logical identities that each application uses to indicate access rights to its different objects. The OC4J-specific deployment descriptors provide a mapping between the logical roles and the users and groups known by OC4J.
Confidentiality Through SSL: Ensures encrypted communications. Use Secure Sockets Layer (SSL) over HTTP for encrypted communication.
Authentication
Authentication verifies that the identity and credentials of a user are valid. The J2EE application determines which user can use the application. However, it is the user manager, employing the user name and password, that verifies the user's identity based on information in the user repository. Authentication is distinct from authorization, which is the process of giving a user access to a J2EE application, based on his identity. OC4J security authenticates two types of clients: HTTP and Enterprise JavaBeans (EJBs). This section describes each of these along with setting up users and groups.
Specifying Users and Groups
OC4J supports the definition of users and groups--either shared by all deployed applications or specific to a given application.
Shared users and groups are listed in the user repository, whose location is specified in the global config/application.xml file. Application-specific users and groups are listed in the application-specific user repository, whose location is specified in the orion-application.xml file of that application.
The way you define users and groups depends on what user manager you employ. For example, because the Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider(OracleAS JAAS Provider) uses roles instead of groups, the JAZNUserManager XML-based user repository, jazn-data.xml, has a different structure from the XMLUserManager user repository, principals.xml. In addition, in a JAZNUserManager user repository, passwords are encrypted, unlike in principals.xml. The following sections offer examples of how to specify users and groups under the JAZNUserManager and XMLUserManager classes. See "Plugging In a User Manager" on page 3-8 for additional details on these classes.
3-2 Oracle Application Server Containers for J2EE Standalone User's Guide
Authentication
Example: Specifying Users and Groups in jazn-data.xml
The following XML from the JAZNUserManager user repository configuration file, jazn-data.xml, shows how to define OracleAS JAAS Provider roles (groups) and users. It defines a group named allusers and a user named guest.
<role> <name>allusers</name> <members> <member> <type>user</type> <name>guest</name> </member> </members> </role>
Unlike the XML from the XMLUserManager user repository configuration file, principals.xml, you can encrypt the password under the JAZNUserManager.
<user> <name>guest</name> <description>The default user</description> <credentials>wEE6aA==</credentials> </user>
Note:
See the Oracle Application Server Containers for J2EE Security Guide for more information on setting up the jazn-data.xml file.
Example: Specifying Users and Groups in principals.xml
The following XML from the principals.xml file (the user repository configuration file for the XMLUserManager class) shows how to define a group named allusers and a user named guest with password welcome. The guest user is made a member of the allusers group. If you want to use the XMLUserManager class instead of the JAZNUserManager class, you must modify the global application.xml file, if modifying for all applications, or the orion-application.xml file, if using the XMLUserManager class only for a specific application. Add the following line:
<principals path="./principals.xml" />
where the path points to the location of the principals.xml file. Also, you must remove or comment out the <jazn provider> element in this file.
Note:
You can hide the password through password indirection. See the Oracle Application Server Containers for J2EE Security Guide for a description of password indirection.
<principals> <groups> <group name="allusers"> <description>Group for all normal users</description> <permission name="rmi:login" /> <permission name="com.evermind.server.rmi.RMIPermission" /> </group> ....other groups...
Configuring Security
3-3
Authentication
</groups> <users> <user username="guest" password="welcome"> <description>Guest user</description> <group-membership group="allusers" /> </user> </users> </principals>
Authenticating HTTP Clients
OC4J requests the client to authenticate itself when accessing protected URLs. You can achieve authentication through a user name and password, or in the case of SSL, through an SSL certificate. Although in most cases where authentication is required, the user is prompted to enter a user name and password. If you decide to use an SSL certificate to authenticate the client, see "Confidentiality Through SSL" on page 3-13 for directions on how to set up your client certificate and server keystore.
Authenticating EJB Clients
When you access EJBs in OC4J, you must pass valid credentials to this server.
Standalone clients define their credentials in the jndi.properties file, either deployed with the EAR file or in the InitialContext object. Servlets or JavaBeans running within OC4J pass their credentials within the InitialContext object, which is created to look up the remote EJBs.
Setting JNDI Properties
If the client exists within the same application as the target, or the target exists within its parent, you do not need a JNDI properties file. If not, you must initialize your JNDI properties either within a jndi.properties file, in the system properties, or within your implementation, before the JNDI call. The following sections discuss these three options:
No JNDI Properties JNDI Properties File JNDI Properties Within Implementation
No JNDI Properties A servlet that exists in the same application with the target bean automatically accesses the JNDI properties for the node. Therefore, accessing the EJB is simple, because no JNDI properties are required.
//Get the Initial Context for the JNDI lookup for a local EJB InitialContext ic = new InitialContext(); //Retrieve the Home interface using JNDI lookup Object empObject = ic.lookup("java:comp/env/employeeBean");
This is also true if the target bean is in an application that has been deployed as this application's parent. To specify parents, use the -parent option of the admin.jar command when deploying the originating application. JNDI Properties File If you are setting the JNDI properties within the jndi.properties file, set the properties as follows. Ensure that this file is accessible from the CLASSPATH.
3-4 Oracle Application Server Containers for J2EE Standalone User's Guide
Authentication
Factory
java.naming.factory.initial= com.evermind.server.ApplicationClientInitialContextFactory
Location The ORMI default port number is 23791, which you can modify in j2ee/home/config/rmi.xml. Therefore, set the URL in the jndi.properties, in one of two ways:
java.naming.provider.url=ormi://hostname/application-name
- or java.naming.provider.url=ormi://hostname:23791/application-name
Security When you access EJBs in OC4J, you must pass valid credentials to this server. Standalone clients define their credentials in the jndi.properties file deployed with the code of the client.
java.naming.security.principal=username java.naming.security.credentials=password
JNDI Properties Within Implementation Set the properties with the same values, but with different syntax. For example, JavaBeans running within the container pass their credentials within the InitialContext, which is created to look up the remote EJBs. To pass JNDI properties within the Hashtable environment, set these as shown below:
Hashtable env = new Hashtable(); env.put("java.naming.provider.url", "ormi://myhost/ejbsamples"); env.put("java.naming.factory.initial", "com.evermind.server.ApplicationClientInitialContextFactory"); env.put(Context.SECURITY_PRINCIPAL, "guest"); env.put(Context.SECURITY_CREDENTIALS, "welcome"); Context ic = new InitialContext (env); Object homeObject = ic.lookup("java:comp/env/employeeBean"); // Narrow the reference to a TemplateHome. EmployeeHome empHome = (EmployeeHome) PortableRemoteObject.narrow(homeObject, EmployeeHome.class);
Using the Initial Context Factory Classes
For most clients, set the initial context factory class to ApplicationClientInitialContextFactory. If you are not using a logical name defined in the <ejb-ref> in your XML configuration file, then you must provide the actual JNDI name of the target bean. In this case, you can use a different initial context factory class, the com.evermind.server.RMIInitialContextFactory class.
Example 31 Servlet Accessing EJB in Remote OC4J Instance
The following servlet uses the JNDI name for the target bean: /cmpapp/employeeBean. Thus, this servlet must provide the JNDI properties in an RMIInitialContext object, instead of the ApplicationClientInitialContext object. The environment is initialized as follows:
Configuring Security
3-5
Authorization
The INITIAL_CONTEXT_FACTORY is initialized to a RMIInitialContextFactory. Instead of creating a new InitialContext, it is retrieved. The actual JNDI name is used in the lookup.
Hashtable env = new Hashtable(); env.put(Context.PROVIDER_URL, "ormi://myhost/cmpapp"); env.put(Context.SECURITY_PRINCIPAL, "admin"); env.put(Context.SECURITY_CREDENTIALS, "welcome"); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.evermind.server.rmi.RMIInitialContextFactory"); Context ic = new com.evermind.server.rmi.RMIInitialContextFactory(). getInitialContext(env); Object homeObject = ic.lookup("/cmpapp/employeeBean"); // Narrow the reference to a TemplateHome. EmployeeHome empHome = (EmployeeHome) PortableRemoteObject.narrow(homeObject, EmployeeHome.class);
Authorization
Authorization is the process of granting or denying a user access to a J2EE application based on its identity. Authorization is distinct from authentication, which is the process of verifying that a user is valid. Specify authorization for users and groups in the J2EE and OC4J-specific deployment descriptors. The J2EE deployment descriptor is where you specify the access rules for using logical roles. The OC4J-specific deployment descriptor is where you map logical roles to actual users and groups, which are defined in a user repository. The following sections describe how to define users, groups, and roles:
Specifying Logical Roles in a J2EE Application Mapping Logical Roles to Users and Groups
Specifying Logical Roles in a J2EE Application
Specify the logical roles that your application uses in the XML deployment descriptors. Depending on the application component type, update one of the following with the logical roles:
web.xml for the Web component ejb-jar.xml for the EJB component application.xml for the application
In each of these deployment descriptors, the roles are defined by an XML element named <security-role>.
Example 32 EJB JAR Security Role Definition
The following steps describe the XML necessary to create a logical role named VISITOR in the ejb-jar.xml deployment descriptor.
1.
Define the logical security role, VISITOR, in the <security-role> element.
3-6 Oracle Application Server Containers for J2EE Standalone User's Guide
Authorization
<security-role> <description>A role for every user</description> <role-name>VISITOR</role-name> </security-role> 2.
Define the bean and methods that this role can access in the <method-permission> element.
<method-permission> <description>VISITOR role needed for CustomerBean methods</description> <role-name>VISITOR</role-name> <method> <ejb-name>customerbean</ejb-name> <method-name>*</method-name> </method> </method-permission>
Mapping Logical Roles to Users and Groups
Map logical roles defined in the application deployment descriptors to actual users and groups defined in a user repository. The mapping is specified in the OC4J-specific deployment descriptor with a <security-role-mapping> element. Figure 31 illustrates this mapping.
Figure 31 Mapping Logical Roles to Users and Groups Defined in jazn-data.xml
<security_role>
<security_role>
application.xml ejb_jar.xml web.xml
<security_role_mapping>
<security_role_mapping>
orion_application.xml orion_ejb_jar.xml orion_web.xml
<group>
<group>
jazn-data.xml and principals.xml
O_1011
<user>
<user>
<user>
Note:
The security role mapping layer, either defined in the principals.xml or jazn-data.xml file, is bypassed if the following conditions are true: The name of the security role and group (or roles, as in the case of jazn-data.xml) are the same. No security role mapping is specified.
Example 33 Mapping Logical Role to Actual Role
This example maps the logical role VISITOR to the allusers group in the orion-ejb-jar.xml file. Any user that can log in as part of this group is considered
Configuring Security
3-7
Plugging In a User Manager
to have the VISITOR role and can therefore execute the methods of customerbean. This role is mapped to the allusers group, which is defined in the User Manager configuration file--the jazn-data.xml file.
<security-role-mapping name="VISITOR"> <group name="allusers" /> </security-role-mapping>
Note:
You can map a logical role to a single group or to several
groups.
Plugging In a User Manager
Any user manager class providing OC4J security is an implementation of the com.evermind.security.UserManager interface. This includes any custom user managers you create. User manager classes manage users, groups, and passwords with such methods as createUser(), getUser(), and getGroup(). Table 31 lists the user managers that you can employ in OC4J security.
Table 31 User Managers and Their User Repositories Available to OC4J User Repository
User Manager oracle.security.jazn.oc4j.JAZNUserManager
using the XML-based provider type-- jazn-data.xml using the LDAP-based provider type--OID
com.evermind.server.XMLUserManager Custom user manager
principals.xml user-provided user repository
By default, OC4J reads the user names, groups, and passwords from the JAZNUserManager user repository, jazn-data.xml. In order for OC4J to employ any user manager, you must specify the name of the user manager class in one of the following XML files:
orion-application.xml--file for a single application config/application.xml--global configuration file for all applications in the server
The following sections describe how to configure each User Manager type:
Using the JAZNUserManager Class Using the XMLUserManager Class Creating Your Own User Manager
Using the JAZNUserManager Class
The primary purpose of the JAZNUserManager class is to leverage the OracleAS JAAS Provider as the security infrastructure for OC4J. For a complete description of the OracleAS JAAS Provider, see the Oracle Application Server Containers for J2EE Security Guide. By integrating the OracleAS JAAS Provider with OC4J, the following benefits can be achieved:
Single Sign-on (SSO)/mod_osso integration
3-8 Oracle Application Server Containers for J2EE Standalone User's Guide
Plugging In a User Manager
SSL/mod_ossl integration OID integration (using the LDAP-based provider type) Fine-grained access control using Java2 permissions run-as identity support, delegation support (from servlet to EJB) Secure file-based storage of passwords (using the XML-based provider type)
Use the JAZNUserManager class if you want OC4J security that has secure, centralized storage, retrieval, and administration of OracleAS JAAS Provider data. This data consists of realm (user and roles) and OracleAS JAAS Provider policy (permissions) information. Figure 32 illustrates the architecture of OC4J security under the JAZNUserManager class. The JAZNUserManager class can use two types of OracleAS JAAS Providers for OC4J security. Use the provider type that is appropriate for your environment:
LDAP-based For centralized storage of information in a directory. The user repository is OID.
XML-based For lightweight storage of information in an XML file. The user repository is the jazn-data.xml file.
Figure 32 OC4J Security Architecture Under the JAZNUserManager Class
Oracle HTTP Server
OC4J
JAZNUserManager
LDAP-based provider type Oracle Internet Directory user repository
XML-based provider type jazn-data.xml user repository
O_1013
JAAS provider
In OC4J, you can configure your application(s) to use the JAZNUserManager class by adding the <jazn> or <user-manager> element in your OC4J-specific configuration file (config/application.xml or orion-application.xml).
Using the JAZNUserManager Class with the LDAP-Based Provider Type
The LDAP-based provider type delegates user and group management functionality to the Delegated Administrative Service (DAS) from OID.
Configuring Security 3-9
Plugging In a User Manager
The following examples from an OC4J-specific configuration file have OC4J employ the JAZNUserManager class as the user manager with the LDAP-based provider type.
<jazn provider="LDAP" default-realm="sample_subrealm" location="ldap://myoid:389" />
- or <user-manager class="oracle.security.jazn.oc4j.JAZNUserManager"> <property name="provider.type" value="LDAP" /> <property name="realm.default" value="sample_subrealm" /> <property name="ldap.service" value="ldap://myoid:389" /> </user-manager>
Notes: If you specify both the <user-manager> element and the <jazn> element, then the <jazn> element is ignored.
Using the JAZNUserManager Class with the XML-Based Provider Type
The XML-based provider type is a fast, lightweight implementation of the OracleAS JAAS Provider API. This provider type uses XML to store user names and encrypted passwords. The following examples from an OC4J-specific configuration file have OC4J employ the JAZNUserManager class as the user manager with the XML-based provider type. The user repository is located at .../j2ee/home/jazn/config/jazn-data.xml. Because there is only one realm in the data file, the specification of realm.default is not needed.
<jazn location=".../j2ee/home/config/jazn-data.xml" provider="XML" />
- or <user-manager class="oracle.security.jazn.oc4j.JAZNUserManager"> <property name="provider.type" value="XML" /> <property name="xml.store.fs.jazn" value=".../j2ee/home/config/jazn-data.xml" /> </user-manager>
Notes: If you specify both the <user-manager> element and the <jazn> element, then the <jazn> element is ignored.
Using the XMLUserManager Class
The XMLUserManager is a file-based security model, where all of your users, roles, groups, and passwords are stored in principals.xml. This is not secure as your passwords could be in the clear. However, if you want to use the XMLUserManager class instead of the JAZNUserManager class, you must modify the global application.xml file, if modifying for all applications, or the orion-application.xml file, if using the XMLUserManager class only for a specific application. Add the following line:
<principals path="./principals.xml" />
where the path points to the location of the principals.xml file. Also, you must remove or comment out the <jazn> element in this file. If you do not remove or
3-10 Oracle Application Server Containers for J2EE Standalone User's Guide
Plugging In a User Manager
comment out the <jazn> element, then whichever element is specified first is the User Manager for the applications. For example, if you have the following:
<principals path="./principals.xml" /> <jazn provider="XML" location=".../j2ee/home/config/jazn-data.xml" />
In this case, the <principals> element appears first, so the XMLUserManager is the security manager.
Creating Your Own User Manager
If none of the user managers supplied by OC4J are suitable for your specific user authentication needs, then you can create your own user manager and configure OC4J to use it. To create your own user manager, complete the following steps:
1.
Write a custom user manager. Your custom user manager class must implement the com.evermind.security.UserManager interface. Table 32 describes the methods of this interface.
Table 32 Method
Methods of the UserManager Interface Description Adds a group to the set of default groups, of which all users of the user manager are members.
void addDefaultGroup (java.lang.String name)
java.lang.String name - the name of the group being added to the default group
Group createGroup (java.lang.String name)
Creates a new group. If the group already exists, a java.lang.InstantiationException is thrown.
java.lang.String name - the name of the new group
User createUser (java.lang.String username, java.lang.String password)
Creates a new user.
java.lang.String username - the new user name java.lang.String password - the new user password
User getAdminUser() User getAnonymousUser() java.util.Set getDefaultGroups() Group getGroup(java.lang.String name)
Returns the default admin user or null if there is none. Returns the default anonymous user or null if none exists. Returns the set of default groups for the user manager. Returns the group with the specified name or null if none exists.
java.lang.String name - the name of the specified group
int getGroupCount()
Returns the number of users contained in the user manager. Throws UnsupportedOperationException if not supported. Returns a list of groups (between the specified indexes) contained in the user manager. Throws UnsupportedOperationException if not supported. Returns the parent manager of the user manager.
java.util.List getGroups (int start,int max) UserManager getParent()
Configuring Security 3-11
Plugging In a User Manager
Table 32 (Cont.) Methods of the UserManager Interface Method User getUser (java.lang.String username) User getUser (java.lang.String issuerDN, java.math.BigInteger serial) User getUser (java.security.cert.X509Certificate certificate) int getUserCount() Description Returns the user with the specified user name or null if there is no match. Returns the user associated with this certificate or null if either certificates are not supported or there is no user associated with this certificate. Returns the user associated with this certificate or null if either certificates are not supported or there is no user associated with this certificate. Returns the number of users contained in this manager. Throws UnsupportedOperationException if not supported. Returns a list of users (between the specified indexes) contained in this manager. Throws UnsupportedOperationException if not supported. Instantiates the user manager with the specified settings. Throws java.lang.InstantiationException if any errors occur. Removes the specified group from the user manager and returns true if the operation is successful. Removes the specified user from the user manager and returns true if the operation is successful. Sets the parent user manager if one exists. This method is called only on a nested user manager. A user manager can delegate work to its parent user manager. 2.
java.util.List getUsers (int start,int max) void init (java.util.Properties properties) boolean remove(Group group) boolean remove(User user) void setParent (UserManager parent)
Plug the user manager into your application. For a single application, specify the custom user manager in the <user-manager> element of the orion-application.xml file. For all applications in the server, specify the custom user manager in the <user-manager> element of the config/application.xml file.
3.
Define your users and groups. See "Specifying Users and Groups" on page 3-2.
4.
Create security constraints in your Web application. See "Authorization" on page 3-6.
Example 34 Using the DataSourceUserManager Class
The following example of the DataSourceUserManager class is a custom user manager and it implements the UserManager interface. Within its methods, the DataSourceUserManager class manages the users in a database specified by the DataSource interface. To configure a custom user manager, you specific the classname in the class attribute of the <user-manager> element in either the global application.xml file or the orion-application.xml file. Then, you can specify input parameters and values through the name/value attributes of one or more <property> elements.
3-12 Oracle Application Server Containers for J2EE Standalone User's Guide
Confidentiality Through SSL
For our DataSourceUserManager example, it requires that the table name and columns are defined in the <property> element name/value pairs. This example sets up the following input parameters:
Data source that specifies the database where the tables reside Table for user names and passwords Table for user and group association
A typical registration of the user manager for an application can be specified in orion-application.xml, as follows:
<user-manager class="com.evermind.sql.DataSourceUserManager"> <property name="dataSource" value="jdbc/OracleCoreDS" /> <property name="table" value="j2ee_users" /> <property name="usernameField" value="username" /> <property name="passwordField" value="password" /> <property name="groupMembershipTableName" value="second_table" /> <property name="groupMembershipGroupFieldName" value="group" /> <property name="groupMembershipUserNameFieldName" value="userId" /> </user-manager>
The <user-manager> property elements define the input parameters into the UserManager class. It assumes that the tables that these refer to already exist in the database. The user manager is a hierarchical implementation with a parent-child relationship. The parent of the DataSourceUserManager class is the default file-based XMLUserManager class, which uses the principals.xml user repository. However, you can change the parent with the setParent() method. The sample DataSourceUserManager class invokes parent.getGroups() to retrieve all the available groups from its parent, the XMLUserManager.
Confidentiality Through SSL
OC4J supports Secure Socket Layer (SSL) communication between the client and a standalone OC4J, using HTTPS. The following sections document SSL in detail:
Overview of Using SSL for OC4J Standalone Configuration of OC4J for SSL HTTPS Common Problems and Solutions
Overview of Using SSL for OC4J Standalone
The following sections describe security features and discuss how to use them with OC4J standalone:
Overview of SSL Keys and Certificates Using Certificates with OC4J Standalone
Overview of SSL Keys and Certificates
In SSL communication between two entities, each entity (or at least the server) has an associated public key and a private key. During communication, each entity uses its own private key, together with the public key of the other party, to ensure that they can communicate with each other. If one entity encrypts data using its private key, then
Configuring Security 3-13
Confidentiality Through SSL
the other party can decrypt the data by only by using the public key of the originating entity. If one entity encrypts data using the public key of the other party, then that party can decrypt the data only by using its own private key. Each key is a number, with the private key of an entity being kept secret by that entity, and the public key of an entity being publicized to any other parties with which secure communication might be necessary. A certificate is a digitally signed statement from a recognized issuer that verifies the public key of an entity. Such an issuer is referred to as a certificate authority (CA). An issued certificate is typically associated with a root certificate. This association, or "chaining", of certificates establishes a chain of trust. An issuer might have its own root certificate, and will chain any certificates it issues to its own root certificate. Functionally, a certificate acts as a container for keys, holding private keys (as applicable), public keys, and associated signatures. A single certificate file can contain an entire chain of certificates. A keystore is used for storage of certificates, including the certificates of all trusted parties. Through its keystore, an entity, such as OC4J, can authenticate itself to other parties. A keystore is a java.security.KeyStore instance that you can create and manipulate using the keytool utility, provided with the Sun Microsystems JDK. Go to the following site for information about keytool:
http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html
During secure communication between the client and OC4J, the following functionality is executed:
The link (all communications) between the two is encrypted. OC4J is authenticated to the client through a security challenge and response. A "secret key" is securely exchanged and used for the encryption of the link. Optionally, if OC4J is in client-authentication mode, the client is authenticated to OC4J.
Using Certificates with OC4J Standalone
The steps for using keys and certificates for SSL communication in OC4J are as follows. These are server-level steps, typically executed prior to deployment of an application that will require secure communication, perhaps when you first set up OC4J.
1. 2.
Use keytool to generate a private key, public key, and unsigned certificate.You can place this information into either a new keystore or an existing keystore. Obtain a signature for the certificate, using either of the following two approaches.
You can generate your own signature by using keytool to "self-sign" the certificate. This is appropriate if your only clients will trust you as, in effect, your own certificate authority. You can obtain a signature from a recognized certificate authority through the following steps: Using the certificate from Step 1, use keytool to generate a certificate request, which is a request to have the certificate signed by a certificate authority. Submit the certificate request to a certificate authority.
a. b.
3-14 Oracle Application Server Containers for J2EE Standalone User's Guide
Confidentiality Through SSL
c.
Receive the signature from the certificate authority and import it into the keystore, again using keytool. In the keystore, the signature will be matched with the associated certificate.
The process for requesting and receiving signatures is up to the particular certificate authority you use. You can go to the Web site of any certificate authority for information. Any browser should have a list of trusted certificate authorities. Here are the Web addresses for VeriSign and Thawte (acquired by VeriSign), for example:
http://www.verisign.com/ http://www.thawte.com/
In addition, Oracle provides a certificate authority, where each certificate is recognized only by Oracle applications. The Oracle Certificate Authority (OCA) allows customers to create and issue certificates for themselves and their users, although these certificates would likely be unrecognized outside a customer's organization without prior arrangements. See the Oracle Application Server Security Guide for information about OCA.
Configuration of OC4J for SSL
For secure communication between a client and OC4J, configuration is required on OC4J standalone. You are required to provide a certificate on the client-side only if you configure client-authentication. In the http-web-site.xml file of OC4J (or other Web site XML file, as appropriate), you must specify appropriate SSL settings under the <web-site> element.
1.
Turn on the secure flag to specify secure communication, as follows:
<web-site ... protocol="http" secure="true" ... > ... </web-site>
Setting secure="true" specifies that the HTTP protocol is to use an SSL socket.
2.
Use the <ssl-config> subelement and its keystore and keystore-password attributes to specify the directory path and password for the keystore, as follows:
<web-site ... secure="true" ... > ... <ssl-config keystore="path_and_file" keystore-password="pwd" /> </web-site>
The <ssl-config> element is required whenever the secure flag is set to "true". The path_and_file value can indicate either an absolute or relative directory path and includes the file name.
Note:
You can hide the password through password indirection. See Oracle Application Server Containers for J2EE Security Guide for a description of password indirection.
3.
Optionally, turn on the needs-client-auth flag, an attribute of the <ssl-config> element, to specify that client authentication is required, as follows:
<web-site ... secure="true" ... > Configuring Security 3-15
Confidentiality Through SSL
... <ssl-config keystore="path_and_file" keystore-password="pwd" needs-client-auth="true" /> </web-site>
This step sets up a mode where OC4J accepts or rejects a client entity for secure communication, depending on its identity. The needs-client-auth attribute instructs OC4J to request the client certificate chain upon connection. If the root certificate of the client is recognized, then the client is accepted. The keystore specified in the <ssl-config> element must contain the certificates of any clients that are authorized to connect to OC4J through HTTPS.
4.
Optionally, specify each application in the Web site as shared. The shared attribute of the <web-app> element indicates whether multiple bindings (different Web sites, or ports, and context roots) can be shared. Supported values are "true" and "false" (default). Sharing implies the sharing of everything that makes up a Web application, including sessions, servlet instances, and context values. A typical use for this mode is to share a Web application between an HTTP site and an HTTPS site at the same context path, when SSL is required for some but not all of the communications. Performance is improved by encrypting only sensitive information, rather than all information. If an HTTPS Web application is marked as shared, then instead of using the SSL certificate to track the session, the cookie is used to track the session. This is beneficial in that the SSL certificiate uses 50K to store each certificate when tracking it, which sometimes results in an "out of memory" problem for the session before the session times out. This could possibly make the Web application less secure, but might be necessary to work around issues such as SSL session timeouts not being properly supported in some browsers.
5.
Optionally, set the cookie domain if shared is true and the default ports are not used. When the client interacts with a Web server over separate ports, the cookie believes that each separate port denotes a separate Web site. If you use the default ports of 80 for HTTP and 443 for HTTPS, the client recognizes these as two different ports of the same Web site and creates only a single cookie. However, if you use non-default ports, the client does not recognize these ports as part of the same Web site and will create separate cookies for each port, unless you specify the cookie domain. Cookie domains track the client's communication across multiple servers within a DNS domain. If you use non-default ports for a shared environment with HTTP and HTTPS, set the cookie-domain attribute in the <session-tracking> element in the orion-web.xml file for the application. The cookie-domain attribute contains the DNS domain with at least two components of the domain name provided.
<session-tracking cookie-domain=".oracle.com" />
Example 35 HTTPS Communication With Client Authentication
The following configures a Web site for HTTPS secure communication with client authentication:
<web-site display-name="OC4J Web Site" protocol="http" secure="true" > <default-web-app application="default" name="defaultWebApp" /> <access-log path="../log/default-web-access.log" /> <ssl-config keystore="../keystore" keystore-password="welcome" needs-client-auth="true" /> 3-16 Oracle Application Server Containers for J2EE Standalone User's Guide
Confidentiality Through SSL
</web-site>
Only the portions in bold are specific to security. The protocol value is always "http" for HTTP communication, whether or not you use secure communication. A protocol value of http with secure="false" indicates HTTP protocol; http with secure="true" indicates HTTPS protocol. Then, configure the news application to accept both HTTP and HTTPS connections:
<web-app application="news" name="news-web" root="/news" shared="true" />
This Web site uses the default port numbers for HTTP and HTTPS communication. If it did not, you would also add the cookie-domain attribute.
<session-tracking cookie-domain=".oracle.com" />
For more information about elements and attributes of the <web-site>, <web-app>, and <session-tracking> elements, see the XML Appendix in the Oracle Application Server Containers for J2EE Servlet Developer's Guide.
Example 36 Creating an SSL Certificate and Configuring HTTPS
The following example uses keytool to create a test certificate and shows all of the XML configuration necessary for HTTPS to work. To create a valid certificate for use in production environments, see the keytool documentation.
1.
Install the correct JDK Ensure that JDK 1.3.x is installed. This is required for SSL with OC4J. Set the JAVA_HOME to the JDK 1.3 directory. Ensure that the JDK 1.3.x JAVA_HOME/bin is at the beginning of your path. This may be achieved by doing the following: UNIX
$ PATH=/usr/opt/java130/bin:$PATH $ export $PATH $ java -version java version "1.3.0"
Windows
set PATH=d:\jdk131\bin;%PATH%
Ensure that this JDK version is set as the current version in your Windows registry. In the Windows Registry Editor under HKEY_LOCAL_ MACHINE/SOFTWARE/JavaSoft/Java Development Kit, set 'CurrentVersion' to 1.3 (or later).
2.
Request a certificate
a. b.
Change directory to ORACLE_HOME/j2ee Create a keystore with an RSA private/public keypair using the keytool command. In our example, we generate a keystore to reside in a file named 'mykeystore', which has a password of '123456' and is valid for 21 days, using the 'RSA' key pair generation algorithm with the following syntax:
keytool -genkey -keyalg "RSA" -keystore mykeystore -storepass 123456 -validity 21
Where:
the keystore option sets the filename where the keys are stored
Configuring Security 3-17
Confidentiality Through SSL
the storepass option sets the password for protecting the keystore the validity option sets number of days the certificate is valid
The keytool prompts you for more information, as follows:
keytool -genkey -keyalg "RSA" -keystore mykeystore -storepass 123456 -validity 21 What is your first and last name? [Unknown]: Test User What is the name of your organizational unit? [Unknown]: Support What is the name of your organization? [Unknown]: Oracle What is the name of your City or Locality? [Unknown]: Redwood Shores What is the name of your State or Province? [Unknown]: CA What is the two-letter country code for this unit? [Unknown]: US Is <CN=Test User, OU=Support, O=Oracle, L=Reading, ST=Berkshire, C=GB> correct? [no]: yes Enter key password for <mykey> (RETURN if same as keystore password):
Note:
To determine your 'two-letter country code', use the ISO country code list at the following URL: http://www.bcpl.net/~jspath/isocodes.html.
The mykeystore file is created in the current directory. The default alias of the key is mykey.
3. 4.
If you do not have a secure-web-site.xml file, then copy the http-web-site.xml to $J2EE_HOME/config/secure-web-site.xml. Edit secure-web-site.xml with the following elements:
a.
Add secure="true" to the <web-site> element, as follows:
<web-site port="8888" display-name="Default Oracle Application Server Containers for J2EE Web Site" secure="true">
b.
Add the following new line inside the <web-site> element to define the keystore and the password.
<ssl-config keystore="<Your-Keystore>" keystore-password="<Your-Password>" />
Where <Your-Keystore> is the full path to the keystore and <Your-Password> is the keystore password. In our example, this is as follows:
<!-- Enable SSL --> <ssl-config keystore="../../keystore" keystore-password="123456"/>
Note:
The keystore path is relative to where the XML file resides.
3-18 Oracle Application Server Containers for J2EE Standalone User's Guide
Confidentiality Through SSL
c.
Change the web-site port number, to use an available port. For example, the default for SSL ports is 443, so change the Web site port attribute to port="4443". To use the default of 443, you have to be a super user. Now save the changes to secure-web-site.xml.
d. 5.
If you did not have the secure-web-site.xml file, then edit server.xml to point to the secure-web-site.xml file.
a.
Uncomment or add the following line in the file server.xml so that the secure-web-site.xml file is read.
<web-site path="./secure-web-site.xml" />
Note:
Even on Windows, you use a forward slash and not a back slash in the XML files.
b. 6.
Save the changes to server.xml.
Stop and re-start OC4J to initialize the secure-web-site.xml file additions. Test the SSL port by accessing the site in a browser on the SSL port. If successful, you will be asked to accept the certificate, since it is not signed by an accepted authority.
When completed, OC4J listens for SSL requests on one port and non-SSL requests on another. You can disable either SSL requests or non-SSL requests, by commenting out the appropriate *web-site.xml in the server.xml configuration file.
<web-site path="./secure-web-site.xml" /> - comment out this to remove SSL <default-site path="./http-web-site.xml" /> - comment out this to remove non-SSL
Requesting Client Authentication with OC4J Standalone
OC4J supports a "client-authentication" mode in which the server explicitly requests authentication from the client before the server will communicate with the client. In this case, the client must have its own certificate. The client authenticates itself by sending a certificate and a certificate chain that ends with a root certificate. OC4J can be configured to accept only root certificates from a specified list in establishing a chain of trust back to the client. A certificate that OC4J trusts is called a trust point. This is the first certificate that OC4J encounters in the chain from the client that matches one in its own keystore. There are three ways to configure trust:
The client certificate is in the keystore. One of the intermediate certificate authority certificates in the client's chain is in the keystore. The root certificate authority certificate in the client's chain is in the keystore.
OC4J verifies that the entire certificate chain up to and including the trust point is valid to prevent any forged certificates. If you request client authentication with the needs-client-auth attribute, perform the following:
1.
Decide which of the certificates in the client's chain is to be your trust point. Ensure that you either have control of the issue of certificates using this trust point or that you trust the certificate authority as an issuer.
Configuring Security 3-19
Confidentiality Through SSL
2. 3. 4.
Import the intermediate or root certificate in the server keystore as a trust point for authentication of the client certificate. If you do not want OC4J to have access to certain trust points, make sure that these trust points are not in the keystore. Execute the preceding steps to create the client certificate, which includes the intermediate or root certificate installed in the server. If you wish to trust another certificate authority, obtain a certificate from that authority. Save the certificate in a file on the client. Provide the certificate on the client initiation of the HTTPS connection.
a. b.
5. 6.
If the client is a browser, set the certificate in the client browser security area. If the client is a Java client, you must programmatically present the client certificate and the certificate chain when initiating the HTTPS connection.
HTTPS Common Problems and Solutions
The following errors may occur when using SSL certificates: Keytool Error: java.security.cert.CertificateException: Unsupported encoding Cause: You cannot allow trailing whitespace in the keytool. Action: Delete all trailing whitespace. If the error still occurs, add a new line in your certificate reply file. Keytool Error: KeyPairGenerator not available Cause: You are probably using a keytool from an older JDK. Action: Use the keytool from the latest JDK on your system. To ensure that you are using the latest JDK, specify the full path for this JDK. Keytool Error: Failed to establish chain from reply Cause: The keytool cannot locate the root CA certificates in your keystore; thus, the keytool cannot build the certificate chain from your server key to the trusted root certificate authority. Action: Execute the following:
keytool -keystore keystore -import -alias cacert -file cacert.cer (keytool -keystore keystore -import -alias intercert -file inter.cer)
If you use an intermediate CA keytool, then execute the following:
keystore keystore -genkey -keyalg RSA -alias serverkey keytool -keystore keystore -certreq -file my.host.com.csr
Get the certificate from the Certificate Signing Request, then execute the following:
keytool -keystore keystore -import -file my.host.com.cer -alias serverkey
IllegalArgumentException: Mixing secure and non-secure sites on the same ip + port Cause: You cannot configure SSL and non-SSL web-sites to listen on the same port and IP address. Action: Check to see that different ports are assigned within secure-web-site.xml and http-web-site.xml files.
3-20 Oracle Application Server Containers for J2EE Standalone User's Guide
Confidentiality Through SSL
Keytool does not work on HP-UX Cause: On HP-UX, it has been reported that the 'keytool' does not work with the RSA option. Action: Generate the key on another platform and FTP it to the HP-UX server.
General SSL Debugging
You can get more debug information from the JSSE implementation. To get a list of options, start OC4J with:
java -Djavax.net.debug=help -jar oc4j.jar
Or, if you want to turn on full verbosity, use:
java -Djavax.net.debug=all -jar oc4j.jar
Both options will display:
Browser request header Server HTTP header Server HTTP body (HTML served) Content length (before and after encryption) SSL version
For UNIX, you could use the startup scripts in NOTE 150215.1 'Scripts to Administer OC4J on Unix Platforms', and amend these.
Configuring Security 3-21
Confidentiality Through SSL
3-22 Oracle Application Server Containers for J2EE Standalone User's Guide
A
Troubleshooting OC4J
This appendix describes common problems that you may encounter when using OC4J and explains how to resolve them. It includes the following topics:
Problems and Solutions Need More Help?
Problems and Solutions
This section describes common problems and solutions. It contains the following topics:
Unable to Start OC4J When Using JDK 1.3 Unable to Restart OC4J After Abnormal Termination When OracleAS JMS is Active Stateful Replication Not Consistent Across OC4J instances Using A Non-Certified Version of the JDK for OC4J Only java.lang.OutOfMemory Errors Thrown When Running OC4J Connection Timeouts Through a Stateful Firewall Affect System Performance OPMN-Managed OC4J Unable to Access EJB Resources Via the Default RMI Port Application Performance Impacted by JVM Garbage Collection Pauses Invalid or Unneeded Library Elements Degrade Performance JSP Error: Tag Not Registered JSP Error: Zero-Length Class File JSP Error: Illegal use of <when>-style tag without <choose> as its direct parent
Unable to Start OC4J When Using JDK 1.3
Problem OC4J fails to start when using JDK 1.3. Solution The failure to start is caused by a logging implementation dependency issue. The solution to this problem is to remove or comment out the following entry in ORACLE_ HOME/j2ee/home/config/server.xml:
<j2ee-logging-config path="./j2ee-logging.xml" /> Troubleshooting OC4J A-1
Problems and Solutions
Unable to Restart OC4J After Abnormal Termination When OracleAS JMS is Active
Problem When persistence is enabled in OracleAS JMS, the JMS server creates persistent queues/topics. It also creates lock files (.lock) associated with these queues/topics in the /persistence directory. If the JVM is terminated abnormally, such as with kill -9, the lock files are not deleted. This creates a condition in which OC4J cannot be restarted. Solution Manually delete all .lock files from the /persistence directory.
Stateful Replication Not Consistent Across OC4J instances
Problem The common scenario is that failover is seen from OC4J instance A to instance B, but not back again from B to A. Solution OC4J does not require stateful replication to be set up globally for all applications, but instead allows each Web module to configure replication through the <cluster-config> element in its orion-web.xml descriptor file. Ensure that this element is populated correctly in each Web module's descriptor. Note that OPMN-managed OC4J only supports clustering at the global level, and not at the application/module level.
Using A Non-Certified Version of the JDK for OC4J Only
Problem In this scenario, you wish to use a later version of the JDK with OC4J than the version certified for use with all Oracle Application Server components. However, using a later version of the JDK globally for all components increases the risk of breaking certification. Solution To use the later JDK version with OC4J only, specify its location in the <java-bin> element in the opmn.xml configuration file. For example:
<module-data> <category id="start-parameters"> <data id="java-bin" value="/myjavalocation/jdk/bin/java"/> </category> </module-data>
java.lang.OutOfMemory Errors Thrown When Running OC4J
Problem This error indicates that the heap size of the Java instance is lower than the memory required by applications running within OC4J.
A-2 Oracle Application Server Containers for J2EE Standalone User's Guide
Problems and Solutions
Solution Increase the heap size by setting -Xmx to the desired amount of memory in the <java-option> element in opmn.xml:
<module-data> <category id="start-parameters"> <data id="java-options" value="-Xmx256M" /> </category> </module-data>
Alternatively, you can set a system property at OC4J startup:
java -Xmx256M -jar oc4j.jar
If running under Unix/Linux, verify that ulimit settings allow the JVM process to allocate this much memory.
Connection Timeouts Through a Stateful Firewall Affect System Performance
Problem To improve performance the mod_oc4j component in each Oracle HTTP Server process maintains open TCP connections to the AJP port within each OC4J instance it sends requests to. In situations where a firewall exists between OHS and OC4J, packages sent via AJP are rejected if the connections can be idle for periods in excess of the inactivity timeout of stateful firewalls. However, the AJP socket is not closed; as long as the socket remains open, the worker thread is tied to it and is never returned to the thread pool. OC4J will continue to create more threads, and will eventually exhaust system resources. Solution The OHS TCP connection must be kept "alive" to avoid firewall timeout issues. This can be accomplished using a combination of OC4J configuration parameters and Apache runtime properties. Set the following parameters in the httpd.conf or mod_oc4j.conf configuration files. Note that the value of Oc4jConnTimeout sets the length of inactivity, in seconds, before the session is considered inactive. Oc4jUserKeepalive on Oc4jConnTimeout 12000 (or a similar value) Also set the following AJP property at OC4J startup to enable OC4J to close AJP sockets in the event that a connection between OHS and OC4J is dropped due to a firewall timeout:
ajp.keepalive=true
For example:
java -Dajp.keepalive=true -jar oc4j.jar
Troubleshooting OC4J
A-3
Problems and Solutions
OPMN-Managed OC4J Unable to Access EJB Resources Via the Default RMI Port
Problem OC4J cannot access EJB resources via the default RMI port when running as a component of Oracle Application Server. Solution The most common cause is that a user more familiar with Standalone OC4J is reading the RMI port from rmi.xml, unaware that the value specified in this file is not used in an OPMN-managed Oracle Application Server environment. OPMN-managed OC4J instances use dynamic RMI port assignments. The port value ranges are specified in the <port> element in opmn.xml or are determined using dynamic opmn:ormi lookup from the application client. See the Oracle Process Manager and Notification Server Administrator's Guide for more information.
Application Performance Impacted by JVM Garbage Collection Pauses
Problem An application running on OC4J appears unresponsive, with simple requests experiencing noticeable delays. The cause is that the JVM has crossed the low memory threshold and is running a full garbage collection to free up memory. Solution Consider using the incremental low pause collector, which avoids long major garbage collection pauses by doing portions of the major collection work at each minor collection. This collector (also known as the train collector) collects portions of the tenured generation - a memory pool holding objects that are typically collected in a major collection - at each minor collection. The result is shorter pauses spread over many minor collections. Note that the incremental collector is even slower than the default tenured generation collector when considering overall throughput. To use the incremental collector, the -Xincgc option must be passed in on the Java command line at application startup. Set the initial and maximum size of the young generation (object pool) to the same value using the XX:NewSize and -XX:MaxNewSize options. Set the initial and the maximum Java heap sizes to the same value using the -Xms and -Xmx options. For example, to use this collector with a server with 1GB of physical memory:
java -server -Xincgc -XX:NewSize=64m -XX:MaxNewSize=64m -Xms512m -Xmx512m
For more information on garbage collection tuning, read "Tuning Garbage Collection with the 1.4.2 JavaTM Virtual Machine" which is available at http://java.sun.com/docs/hotspot/gc1.4.2/
A-4 Oracle Application Server Containers for J2EE Standalone User's Guide
Problems and Solutions
Invalid or Unneeded Library Elements Degrade Performance
Problem If the OC4J process memory is growing consistently during program execution, then you may have references to invalid symbolic links in your global application.xml file. This problem is usually characterized by a growth in the C heap and not a growth in Java object memory, as one would see with a more traditional Java object memory leak. OC4J loads all resources defined in the application.xml file. If these links are invalid, then the C heap continues to grow, causing OC4J to run out of memory. Solution Ensure that all symbolic links are valid in application.xml, and restart OC4J. In addition, keep the number of JAR files OC4J is configured to load to a minimum. Eliminate all unused JAR files from the configuration and from the directories OC4J is configured to search. OC4J searches all JAR files for classes and resources, thereby causing the file cache to use extra memory and processor time. You can control the loading more precisely if your <library> elements in the application.xml file point to the individual JAR and ZIP files that are needed, instead of to the directories where they reside.
JSP Error: Tag Not Registered
Problem This error occurs when a JSP attempts to call a tag that cannot be found within the OC4J server. The problem typically arises when one or more additional "well-known tag library locations" have been incompletely defined within OC4J. Solution Defining a well-known tag library location is a two-step process:
The directory is defined in the jsp-taglib-locations attribute of the of the <orion-web-app> element in the global-web-application.xml file; and The directory is added to the path attribute of the <library> element in the application.xml.
The error typically indicates that the second step was not completed. Alternatively, you can copy the JAR file containing the tag library to the default well-known tag library location, which is ORACLE_ HOME/j2ee/home/jsp/lib/taglib/.
JSP Error: Zero-Length Class File
Problem This error occurs when OC4J attempts to serve a JSP that failed to compile into a Java class. The cause is that the Java compiler either could not be loaded or ran out of memory, resulting in a 0 byte .class file.
Troubleshooting OC4J
A-5
Need More Help?
Solution Delete the 0 byte .class file. The class will be compiled the next time the JSP is requested.
JSP Error: Illegal use of <when>-style tag without <choose> as its direct parent
Problem This error occurs when OC4J fails to serve a requested JSP that includes a JSP Standard Tag Library (JSTL) tag--in this case, the <choose> tag. The likely cause is that more than one version of the JSTL exists within the OC4J instance. Solution Delete the version of the JSTL installed by default with OC4J. This library is packaged as the standard.jar file in the ORACLE_HOME/j2ee/home/jsp/lib/taglib directory.
Need More Help?
You can search for additional solutions on the following Oracle support-oriented Web sites:
Oracle Application Server Release Notes, available on the Oracle Technology Network at http://www.oracle.com/technology/documentation/index.html Oracle MetaLink, available at http://metalink.oracle.com
If you still cannot find a solution for the problem you are facing, please log a service request.
A-6 Oracle Application Server Containers for J2EE Standalone User's Guide
B
Additional Information
This appendix contains complete information about the following topics:
Description of XML File Contents Elements in the server.xml File Elements in the application.xml File Elements in the orion-application.xml File Elements in the application-client.xml File Elements in the orion-application-client.xml File Standalone OC4J Command-Line Options and Properties OC4J System Properties Configuration and Deployment Examples
Description of XML File Contents
OC4J uses configuration and deployment XML files. The following sections describe each of these files and their function.
OC4J Configuration XML Files
This section describes the following XML files, which are necessary for OC4J configuration:
server.xml http-web-site.xml jazn-data.xml principals.xml data-sources.xml jms.xml rmi.xml
server.xml
This file contains the configuration for the application server. The server.xml file is the root configuration file--it contains references to other configuration files. In this file, specify the following:
Additional Information B-1
Description of XML File Contents
Library path, which is located in the application deployment descriptor Global application, global Web application, and default Web site served Maximum number of HTTP connections the server allows Logging settings Java compiler settings Transaction time-out SMTP host Location of the data-sources.xml configuration Location of the configuration for JMS and RMI Location of the default and additional Web sites Specify these locations by adding entries that list the location of the Web site configuration files. You can have multiple Web sites. The http-web-site.xml file defines a default Web site; therefore, there is only one of these XML files. All other Web sites are defined in web-site.xml configuration files. Register each Web site within the server.xml file, as follows:
<web-site path="./http-web-site.xml" /> <web-site path="./another-web-site.xml" />
Note:
The path that is designated is relative to the config/ directory.
Pointers to all applications for the container to deploy and execute Specify the applications that run on the container in the server.xml file. You can have as many application directories as you want, and they do not have to be located under the OC4J installation directory.
http-web-site.xml
This file contains the configuration for a Web site. In the http-web-site.xml file, specify the following:
Host name or IP address, virtual host settings for this site, listener ports, and security using SSL Default Web application for this site Additional Web applications for this site Access-log format Settings for user Web applications (for /~user/ sites) SSL configuration
jazn-data.xml
This file contains security information for the OC4J server. It defines the user and group configuration for employing the default JAZNUserManager. In the jazn-data.xml file, specify the following:
Username and passwords Name and description of users, groups, and roles
B-2 Oracle Application Server Containers for J2EE Standalone User's Guide
Description of XML File Contents
principals.xml
This file contains security information for the OC4J server. It defines the user and group configuration for employing the XMLUserManager, which is no longer the default security manager. In the principals.xml file, specify the following:
Username and password for the client-admin console Name and description of users/groups, and real name and password for users Optional X.509 certificates for users
data-sources.xml
This file contains configuration for the data sources that are used. In addition, it contains information on how to retrieve JDBC connections. In the data-sources.xml file, specify the following:
JDBC driver JDBC URL JNDI paths to which to bind the data source Username/password for the data source Database schema to use Inactivity time-out Maximum number of connections allowed to the database
Note:
Database schemas are used to make auto-generated SQL work with different database systems. OC4J contains an XML file format for specifying properties, such as type-mappings and reserved words. OC4J comes with database schemas for MS SQL Server/MS Access, Oracle, and Sybase. You can edit these or make new schemas for your DBMS.
jms.xml
This file contains the configuration for the OC4J Java Message Service (JMS) implementation. In the jms.xml file, specify the following:
Host name or IP address, and port number to which the JMS server binds Settings for queues and topics to be bound in the JNDI tree Log settings
rmi.xml
This file contains configuration for the Remote Method Invocation (RMI) system. It contains the setting for the RMI listener, which provides remote access for EJBs. In the rmi.xml file, specify the following:
Host name or IP address, and port number to which the RMI server binds Remote servers to which to communicate Log settings
Additional Information B-3
Description of XML File Contents
J2EE Deployment XML Files
The OC4J-specific deployment XML files contain deployment information for different components. If you do not create the OC4J-specific files, they are automatically generated when the application is deployed. You can edit OC4J-specific deployment XML files manually. OC4J uses these files to map environment entries, resources references, and security-roles to actual deployment-specific values. This section describes the following XML files necessary for J2EE application deployment:
The J2EE application.xml File The OC4J-Specific orion-application.xml File The J2EE ejb-jar.xml File The OC4J-Specific orion-ejb-jar.xml File The J2EE web.xml File The OC4J-Specific orion-web.xml File The J2EE application-client.xml File The OC4J-Specific orion-application-client.xml File
The J2EE application.xml File
This file identifies the Web or EJB applications that are contained within the J2EE application. See "Elements in the application.xml File" on page B-14 for a list of the elements.
The OC4J-Specific orion-application.xml File
This file configures the global application. In the orion-application.xml file, specify the following:
Whether to auto-create and auto-delete tables for CMP beans Which default data source to use with CMP beans Security role mappings Which user manager is the default for security JNDI namespace-access rules (authorization)
See "Elements in the orion-application.xml File" on page B-16 for a list of the elements.
The J2EE ejb-jar.xml File
This file defines the deployment parameters for the EJBs in this JAR file. See the Sun Microsystems EJB specification for a description of these elements.
The OC4J-Specific orion-ejb-jar.xml File
This file is the OC4J-specific deployment descriptor for EJBs. In the orion-ejb-jar.xml file, specify the following:
Time-out settings Transaction retry settings Session persistence settings Transaction isolation settings
B-4 Oracle Application Server Containers for J2EE Standalone User's Guide
Description of XML File Contents
CMP mappings OR mappings Finder method specifications JNDI mappings Minimum and maximum instance pool settings resource reference mappings
See the appendix in the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide for description of the elements.
The J2EE web.xml File
This file contains deployment information about the servlets and JSPs in this application. See the Sun Microsystems specifications for a description of these elements.
The OC4J-Specific orion-web.xml File
This is the OC4J-specific deployment descriptor for mapping Web settings. This XML file contains the following:
Auto-reloading (including modification-check time-interval) Buffering Charsets Development mode Directory browsing Document root Locales Web timeouts Virtual directories Session tracking JNDI mappings Classloading priority for Web applications
See the appendix in the Oracle Application Server Containers for J2EE Servlet Developer's Guide for description of the elements.
The J2EE application-client.xml File
This file contains JNDI information for accessing the server application and other client information. See "Elements in the application-client.xml File" on page B-21 for a list of the elements.
The OC4J-Specific orion-application-client.xml File
This OC4J-specific deployment file is for the client application. It contains JNDI mappings and entries for the client. See "Elements in the orion-application-client.xml File" on page B-24 for a list of the elements.
Additional Information B-5
Elements in the server.xml File
Elements in the server.xml File
The server.xml file is where you perform the following tasks:
Configure OC4J Reference other configuration files Specify your J2EE application(s)
Configure OC4J
Configuring the OC4J server includes defining the following elements in the server.xml file:
Library path Global application, the global Web application, and the default Web site Maximum number of HTTP connections the server allows Logging settings Java compiler settings Transaction time-out SMTP host
Reference Other Configuration Files
Referencing other configuration files in the server.xml file includes specifying the following:
data-sources.xml location jazn-data.xml location jms.xml and rmi.xml locations
Several XML files and directories are defined in the server.xml file. The path to these files or directories can be relative or absolute. If relative, the path should be relative to the location of the server.xml file.
<application-server> Element Description
The top level element of the server.xml file is the <application-server> element. <application-server> This element contains the configuration for an application server. Attributes:
application-auto-deploy-directory=".../applications/auto" --Specifies the directory from which EAR files are automatically detected and deployed by the running OC4J server. In addition, it performs the Web application binding for the default Web site. auto-start-applications="true|false"--If set to true, all applications defined in the <applications> elements are automatically started when the OC4J server is started. If set to false, the applications are not started unless their auto-start attribute is set to true. The default for auto-start-applications is true.
B-6 Oracle Application Server Containers for J2EE Standalone User's Guide
Elements in the server.xml File
application-directory=".../applications"-- Specifies a directory in which to store applications (EAR files). If none is specified (the default), OC4J stores the information in j2ee/home/applications. deployment-directory=".../application-deployments"--Specifies the master location where applications that are contained in EAR files are deployed. The location defaults to j2ee/home/application-deployments/. connector-directory--The location and file name of the oc4j-connectors.xml file. check-for-updates="true|false"--Default in standalone OC4J is "true". If true, task manager checks for XML configuration file modifications. Thus, if you set to false, you can disable automatic refreshing of the configuration to any new XML modifications. Also, setting this attribute to false stops the automatic deployment of any applications until you execute admin.jar -updateConfig. If set to false, you cause the XML configuration to refresh from the XML files and any necessary automatic deployment to occur by using the admin.jar -updateConfig option. recovery-procedure="automatic|prompt|ignore"-- Specifies how the EJB container recovers a global transaction (JTA) if an error occurs in the middle of the transaction. If a CMP bean is in the middle of a global transaction when an error occurs, then the EJB container saves the transactional state to a file. The next time OC4J is started, these attributes specify how to recover the JTA transaction. automatic -- automatically attempts recovery (the default) prompt -- prompts the user (system in/out) You may notice a prompt for recovery even if no CMP beans were executing. This is caused by the OC4J server asking for permission to see whether there is anything to recover. ignore -- ignores recovery (useful in development environments or if you are never executing a CMP entity bean)
taskmanager-granularity=milliseconds. The task manager is a background process that performs cleanup. However, the task manager can be expensive. You can manage when the task manager performs its duties through this attribute, which sets how often the task manager is kicked off for cleanup. Value is in milliseconds. Default is 1000 milliseconds.
Elements Contained Within <application-server>
Within the <application-server> element, the following elements, which are listed alphabetically and not by DTD ordering, can be configured: <application> An application is a entity with its own set of users, Web applications, and EJB JAR files. Attributes:
auto-start="true|false" -- Specifies whether the application should be automatically started when the OC4J server starts. The default is true. Setting auto-start to false is useful if you have multiple applications installed and want them to start on demand. This can improve general server startup time and resource usage. deployment-directory=".../application-deployments/myapp" -- Specifies a directory to store application deployment information. If none is
Additional Information B-7
Elements in the server.xml File
specified (the default), OC4J looks in the global deployment-directory, and if none exists there, it stores the information inside the EAR file. The path can be relative or absolute. If relative, the path should be relative to the location of the server.xml file.
name="anApplication" -- Specifies the name used to reference the application. parent="anotherApplication" -- The name of the optional parent application. The default is the global application. Children see the namespace of its parent application. This is used to share services such as EJBs among multiple applications. path=".../applications/myApplication.ear" /> -- The path to the EAR file containing the application code. In this example, the EAR file is named myApplication.ear.
<compiler> This element is deprecated for version 9.0.4 and forward. See the <java-compiler> element for the alternative. For previous releases, it specifies an alternative compiler (such as Jikes) for EJB/JSP compiling. Attributes:
classpath="/my/rt.jar" -- Specifies an alternative/additional classpath when compiling. Some compilers need an additional classpath (such as Jikes, which needs the rt.jar file of the Java 2 VM to be included). executable="jikes" /> -- The name of the compiler executable to use, such as Jikes or JVC.
<cluster> Cluster settings for this server. Attribute:
id="123" /> -- The unique cluster ID of the server.
<execution-order> Defines the ordering of how the startup classes are executed. Value is an integer. OC4J loads from 0 on up. If duplicate numbers, OC4J chooses the ordering for those classes. <global-application> The default application for this server. This acts as a parent to other applications in terms of object visibility. Attributes:
name="default" -- Specifies the application. path=".../application.xml" /> -- Specifies the path to the global application.xml file, which contains the settings for the default application. An application.xml file exists for each application as the standard J2EE application descriptor file, which is different than this file. This application.xml may have the same name, but it exists to provide global settings for all J2EE applications.
<global-thread-pool> You can specify unbounded, one, or two thread pools for an OC4J process through this element. If you do not specify this element, then an infinite number of threads can be created. See "Thread Pool Settings" on page 2-16 for a full description.
B-8 Oracle Application Server Containers for J2EE Standalone User's Guide
Elements in the server.xml File
Attributes:
min --The minimum number of threads that OC4J can simultaneously execute. By default, a minimum number of threads are preallocated and placed in the thread pool when the container starts. Value is an integer. The default is 20. The minimum value you can set this to is 10. max --The maximum number of threads that OC4J can simultaneously execute. New threads are spawned if the maximum size is not reached and if there are no idle threads. Idle threads are used first before a new thread is spawned. Value is an integer. The default is 40. queue --The maximum number of requests that can be kept in the queue. Value is an integer. The default is 80. keepAlive --The number of milliseconds to keep a thread alive (idle) while waiting for a new request. This timeout designates how long an idle thread remains alive. If the timeout is reached, the thread is destroyed. The minimum time is a minute. Time is set in milliseconds. To never destroy threads, set this timeout to a negative one. Value is a long. The default is 600000 milliseconds.
cx-min --The minimum number of connection threads that OC4J can simultaneously execute. Value is an integer. The default is 20. The minimum value you can set this to is 10. cx-max --The maximum number of connection threads that OC4J can simultaneously execute. Value is an integer. The default is 40. cx-queue --The maximum number of connection requests that can be kept in the queue. Value is an integer. The default is 80. cx-keepAlive --The number of milliseconds to keep a connection thread alive (idle) while waiting for a new request. This timeout designates how long an idle thread remains alive. If the timeout is reached, the thread is destroyed. The minimum time is a minute. Time is set in milliseconds. To never destroy threads, set this timeout to a negative one. Value is a long. The default is 600000 milliseconds.
debug --If true, print the application server thread pool information at startup. The default is false.
<global-web-app-config> Attributes:
path-- The path where the web-application.xml file is located.
path=".../web-application.xml" />
<init-library> Attributes:
path-- The path in which the startup and shutdown classes are located. The path indicates the directory in which the class resides or the directory and JAR filename of the JAR where the class is archived. If more than one directory or JAR file exists, then supply an <init-library> element for each directory and JAR filename.
<init-library path="../xxx">
<init-param>
Additional Information B-9
Elements in the server.xml File
Attributes:
Defines the key-value pairs of the parameters to pass into the startup class.
<javacache-config> Attributes:
path--Specifies the path to the javacache.xml file.
<javacache-config path="../../../javacache/admin/javacache.xml" />
<java-compiler> You can specify an alternative compiler--either in or out of process--for your JSP and EJB compilation. The default compiler is an out of process javac compiler found in the JDK bin directory. Attributes:
name--Specify the name of the compiler to use. Valid compiler names are as follows: for in-process compilers--modern, classic, javac or ojc for out-of-process compilers (forked)--modern, javac, ojc, or jikes These names are defined as follows: * * * * * javac--the standard compiler name for all JDKs. classic--the standard compiler of JDK 1.1/1.2. modern--the standard compiler of JDK 1.3/1.4. jikes--the Jikes compiler. ojc--The Oracle Java compiler.
in-process--If true, the compiler is to run in process. If false, the compiler runs out of the process. Most compilers can execute both in and out of the process. The exceptions are as follows: The classic compiler cannot run out of the process; thus, the in-process attribute is always true. The jikes compiler cannot run in process; thus, the in-process attribute is always false.
encoding--Specify the type of character encoding for the source file, such as UTF-8, EUCJIS, or SJIS. Encoding is only supported by the javac compiler. The default is determined by the language version of the JVM that is installed. bindir--Provide the absolute path to the compiler directory. You do not need to specify this attribute for javac, modern, or classic as the JDK bin directory is searched for this compiler. The syntax is specific to the operating system platform: Sun Microsystems Solaris example--If you are using jikes, which is in /usr/local/bin/jikes, then specify the following:
name="jikes" bindir="/usr/local/bin"
Windows example--To specify jikes, which is located in c:\jdk1.3.1\bin\jikes.exe, specify the following:
B-10 Oracle Application Server Containers for J2EE Standalone User's Guide
Elements in the server.xml File
name="jikes" bindir="c:\\jdk1.3.1\\bin"
extdirs--Specifies extension directories that the compilation uses to compile against. The default is your JDK extension directories. Multiple directories can be specified, each separated by a colon. Each JAR archive in the specified directories are searched for class files. You can specify certain directories to be searched by modifying the -Djava.ext.dirs system property. The jikes compiler requires that extension directories are specified in either this attribute or in the -Djava.ext.dirs system property.
The following are four examples of how to define alternate compilers in this element:
<java-compiler name="jikes" bindir="C:\java\jikes\bin" in-process="false" /> <java-compiler name="ojc" bindir="C:\java\jdev\jdev\bin" in-process="false"/> <java-compiler name="classic" in-process="true" /> <java-compiler name="modern" in-process="true" />
<jms-config> Attribute:
path-- Specifies the path to the jms.xml file.
path=".../jms.xml"
<log> <file> Attribute:
path=".../log/server.log" -- Specifies a relative or absolute path to a file where log events are stored.
<mail> An e-mail address where log events are forwarded. You must also specify a valid mail-session if you use this option. Attribute:
address="[e-mail]" -- Specifies the mail address.
<odl> The ODL log entries are each written out in XML format in its respective log file. The log files have a maximum limit. When the limit is reached, the log files are overwritten. When you enable ODL logging, each message goes into its respective log file, named logN.xml, where N is a number starting at one. The first log message starts the log file, log1.xml. When the log file size maximum is reached, the second log file is opened to continue the logging, log2.xml. When the last logfile is full, the first log file, log1.xml is erased and a new one is opened for the new messages. Thus, your log files are constantly rolling over and do not encroach on your disk space. Attributes:
path: Path and folder name of the log folder for this area. You can use an absolute path or a path relative to where the configuration XML file exists, which is normally in the j2ee/home/config directory. This denotes where the log files will reside for the feature that the XML configuration file is concerned with. For
Additional Information B-11
Elements in the server.xml File
example, modifying this element in the server.xml file denotes where the server log files are written.
max-file-size: The maximum size in KB of each individual log file. max-directory-size: The maximum size of the directory in KB. The default directory size is 10 MB.
New files are created within the directory, until the maximum directory size is reached. Each log file is equal to or less than the maximum specified in the attributes. <max-http-connections> Used to define the maximum number of concurrent connections any given Web site can accept at a single point in time. If text exists inside the tag, it is used as a redirect-URL when the limit is reached. Attributes:
max-connections-queue-timeout="10" -- When the maximum number of connections are reached, this is the number of seconds that can pass before the connections are dropped and a message is returned to the client stating that the server is either busy or connections will be redirected. The default is 10 seconds. socket-backlog -- The number of connections to queue up before denying connections at the socket level. The default is 30. value -- The maximum number of connections.
<metric-collector> The <metric-collector> element specifies that OC4J sends a metric between 0 and 100, inclusive, to mod_oc4j so that mod_oc4j can make routing decisions to load-balance incoming requests to a list of available OC4J instances. The metric sent has a relative value only, where 0 means that the OC4J instance is very busy and 100 means that the OC4J instance is available (not busy). When configured for metric load balancing, mod_oc4j routes first to the OC4J instance with the greater value. The metric sent from OC4J to mod_oc4j is used only when metric-based load balancing is specified for mod_oc4j and when OC4J runs in an Oracle Application Server environment. If you specify metric-based load balancing in mod_oc4j and do not specify the <metric-collector> element in server.xml, then mod_oc4j expects OC4J to send metrics, but OC4J does not send metrics. In this case, mod_oc4j reports the following warning message:
No run time metrics for oc4j(opmnid=%s) in notification Oc4jSelectMethod is configured to use run time metrics, please make sure OC4J side is configured accordingly. Default to 50.
In this case, mod_oc4j uses the value 50 for each of the OC4J processes and continues. Likewise, if you specify the <metric-collector> element in server.xml, but do not specify metric-based load balancing in mod_oc4j, then OC4J sends metrics but mod_oc4j is not configured to receive metrics. In this case, mod_oc4j ignores the metrics and uses whatever the configured method is for load balancing. You specify the load balancing method with Oc4jSelectMethod. If no Oc4jSelectMethod is specified, then mod_oc4j uses the default, which is roundrobin. The <metric-collector> element takes the following attribute: classname. The classname attribute defines an interface for gathering and calculating a server-wide metric. Use oracle.oc4j.server.DMSMetricCollector for the
B-12 Oracle Application Server Containers for J2EE Standalone User's Guide
Elements in the server.xml File
classname attribute when using a DMS-noun-based metric collector. A DMSMetricCollector instance takes several parameters. Details for the values for these parameters are available in the Oracle Application Server 10g Performance Guide. For example:
<metric-collector classname="oracle.oc4j.server.DMSMetricCollector"> <init-param> <param-name> dms-noun </param-name> <param-value> /oc4j/default/WEBs/processRequest.time </param-value> </init-param> <init-param> <param-name> history-proportion </param-name> <param-value> 0.2 </param-value> </init-param> <init-param> <param-name> debug </param-name> <param-value> false </param-value> </init-param> </metric-collector>
For details on using the <metric-collector> element and using metric-based load balancing with mod_oc4j, see the Oracle Application Server 10g Performance Guide. <rmi-config> Attribute:
path-- Specifies the path to the rmi.xml file.
path=".../rmi.xml"
<sep-config> The <sep-config> element in this file specifies the pathname, normally internal-settings.xml, for the server extension provider properties. Attribute:
path--The path of the server extension provider properties.
<sfsb-config> Passivation for stateful session beans is automatically done, unless you set the enable-passivation attribute for this element to false. For more information on stateful session bean passivation, see the Advanced chapter in the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide. Attribute
Additional Information
B-13
Elements in the application.xml File
enable-passivation--Default is true, which means that stateful session bean passivation occurs. If you have a situation where your stateful session beans are not in a state to be passivated, set this attribute to false.
<shutdown-classes> Shutdown classes can be defined by the user, and are executed after undeployment, but before the core services are stopped. <shutdown-class> Each startup class is defined within the <startup-class> element. Attributes:
classname--The classname of the user-defined startup class.
<startup-classes> Startup classes can be defined by the user, and will be executed after the core services (JMS, RMI) are started, but before applications are deployed. The shutdown classes are executed after undeployment, but before the core services are stopped. <startup-class> Each startup class is defined within the <startup-class> element. Attributes:
classname--The classname of the user-defined startup class. failure-is-fatal--If true, if an exception is thrown, then OC4J logs the exception and exit. If false, OC4J logs the exception and then continues. Default is false.
<transaction-config> Transaction configuration for the server. Attribute:
timeout="30000" -- Specifies the maximum amount of time (in milliseconds) that a transaction can take to finish before it is rolled back due to a timeout. The default value is 30000. This timeout will be a default timeout for all transactions that are started in OC4J. You can change it by using the dynamic API--UserTransaction.setTransactionTimeout(milliseconds).
<web-site> Attribute:
path-- The path to a *web-site.xml file that defines a Web site. For each Web site, you must specify a separate *web-site.xml file. This example shows that a Web site is defined in the my-web-site.xml file.
path=".../my-web-site.xml"
Elements in the application.xml File
This section provides an overview of the J2EE application deployment descriptor file.
<application> Element Description
The top level element of the application.xml file is the <application> element.
B-14 Oracle Application Server Containers for J2EE Standalone User's Guide
Elements in the application.xml File
Elements Contained Within <application>
Within the <application> element, the following elements, which are listed alphabetically and not by DTD ordering, can be configured: <alt-dd>path/to/dd</alt-dd> The alt-dd element specifies an optional URI to the post-assembly version of the deployment descriptor file for a particular J2EE module. The URI must specify the full pathname of the deployment descriptor file relative to the application's root directory. If alt-dd is not specified, the deployer must read the deployment descriptor from the default location and file name required by the respective component specification. <connector>context</connector> The connector element specifies the URI of a resource adapter archive file, relative to the top level of the aplication package. <context-root>thedir/</context-root> The context-root element specifies the context root of a web application. <description>A description.</description> The description element provides a human readable description of the application. The description element should include any information that the application assembler wants to provide the deployer. <display-name>The name.</display-name> The display-name element specifies an application name. The application name is assigned to the application by the application assembler and is used to identify the application to the deployer at deployment time. <ejb>pathToEJB.jar</ejb> The ejb element specifies the URI of a EJB JAR, relative to the top level of the application package. <icon> The icon element contains a small-icon and a large-icon element which specify the location within the application for a small and large image used to represent the application in a GUI tool. <java>pathToClient.jar</java> The java element specifies the URI of a Java application client module, relative to the top level of the application package. <large-icon>path/to/icon.gif</large-icon> The large-icon element contains the location within the application of a file containing a large (32x32 pixel) icon image. The image must be either GIF or JPEG format and the filename must end with the extension of ".gif" or ".jpg". <module> The module element represents a single J2EE module and contains an EJB, Java, or Web element, which indicates the module type and contains a path to the module file, and an optional alt-dd element, which specifies an optional URI to the post-assembly version of the deployment descriptor. The application deployment descriptor must have one module element for each J2EE module in the application package. <role-name>nameOfRole</role-name>
Additional Information
B-15
Elements in the orion-application.xml File
The name of the role. <security-role> The security-role element contains the definition of a security role which is global to the application. The definition consists of a description of the security role, and the security role name. The descriptions at this level override those in the component level security role definitions and must be the descriptions tool display to the deployer. <small-icon>path/to/icon.gif</small-icon> The small-icon element contains the location within the application of a file containing a small (16x16 pixel) icon image. The image must be either GIF or JPEG format and the filename must end with the extension of ".gif" or ".jpg". <web> The web element contains the web-uri and context-root of a Web application module. <web-uri>pathTo.war</web-uri> The web-uri element specifies the URI of a web application file, relative to the top level of the application package.
Elements in the orion-application.xml File
This section describes the OC4J-specific application deployment descriptor file.
<orion-application> Element Description
The top level element of the orion-application.xml file is the <orion-application> element. Attributes:
autocreate-tables - Whether or not to automatically create database tables for CMP beans in this application. The default is true. autodelete-tables - Whether or not to automatically delete old database tables for CMP beans when redeploying in this application. The default is false. default-data-source - The default data source to use if other than server default. This must point to a valid CMT data source for this application if specified. deployment-version - The version of OC4J that this JAR was deployed against, if it is not matching the current version then it will be redeployed. This is an internal server value; do not edit. treat-zero-as-null - Whether or not to treat read zero's as null's when they represent primary keys. The default is false.
Elements Contained Within <orion-application>
Within the <orion-application> element, the following elements, which are listed alphabetically and not by DTD ordering, can be configured: <argument value="theValue" /> An argument used when invoking the client. Attribute:
B-16 Oracle Application Server Containers for J2EE Standalone User's Guide
Elements in the orion-application.xml File
value - The value of the argument.
<arguments> A list of arguments to used when invoking the application client if starting it in-process (auto-start="true"). <client-module auto-start="true|false" deployment-time="073fc2ab513bc3ce" path="myappclient.jar" user="theUser"> An application client module of the application. An application client is a GUI or console-based standalone client that interacts with the server. Attributes:
auto-start - Whether or not to auto-start the client (in-process) at server startup. The default is false. deployment-time - Last deploy time attribute. Internal to OC4J; do not edit. path - The path (relative to the enterprise archive or absolute) to the application-client. user - User to run the client as if run in-process (autostart="true"). Must be specified if auto-start is activated.
<commit-coordinator> Configure the two-phase commit engine. <commit-class class="com.evermind.server.OracleTwoPhaseCommitDriver" /> Attribute:
class - Configures the OracleTwoPhaseCommitDriver class for two-phase commit engines.
<connectors path="./oc4j-connectors.xml" /> Attribute:
path - The name and path of the oc4j-connectors.xml file. If no <connectors> element is specified, then the default path is <oc4j>/j2ee/home/connectors/rarname./oc4j-connectors.xml.
<data-sources path="./data-sources.xml" /> Attribute:
path - The path.
<description>A short description</description> A short description of this component. <ejb-module path="myEjbs.jar" remote="true|false" /> An EJB JAR module of the application. Attributes:
path - The path (relative to the enterprise archive or absolute) to the ejb-jar. remote - true/false value stating whether or not to activate the EJB instances on this node or to look them up remotely from another server. The default is false.
<file path="../log/server.log" />
Additional Information
B-17
Elements in the orion-application.xml File
A relative/absolute path to log events to. Attribute:
path - The path to the log file.
<group name="theGroup" /> A group that this security-role-mapping implies. That is, all members of the specified group are included in this role. Attribute:
name - The name of the group.
<jazn provider="XML" location="./jazn-data.xml" /> Configure the OracleAS JAAS Provider to use the XML-based provider type. Attributes:
provider - XML location - Path to file. For example: ./jazn-data.xml This can be an absolute path, or a path relative to the jazn.xml file, where the OracleAS JAAS Provider first looks for the jazn-data.xml in the directory containing the jazn.xml file. Optional if jazn.xml file configured, otherwise Required persistence - Values can be NONE (Do not persist changes), ALL (Persist changes after every modification), VM_EXIT - (Default- Persist changes when VM exits) default-realm - A realm name. For example: sample_subrealm. Optional if only one realm is configured.
<jazn-web-app auth-method="SSO" runas-mode="false" doasprivileged-mode="true" /> The filter element of JAZNUserManager. Attributes:
Set auth-method to SSO (single sign-on). If you do not set this parameter, it defaults to null. The runas-mode and doasprivileged-mode settings are described in Table B1. See the Oracle Application Server Containers for J2EE Security Guide for more information.
Table B1
runas-mode and doasprivileged-mode Settings If doasprivileged-mode Is Set To... true (default) Then... Subject.doAsPrivileged in a privilegedExceptionAction block that calls chain.doFilter (myrequest,response) Subject.doAs in a privilegedExceptionAction block that calls chain.doFilter (myrequest,response) chain.doFilter (myrequest,response) chain.doFilter (myrequest,response)
If runas-mode is Set To... true
true
false
false (default) false
true false
<library path="../lib/" />
B-18 Oracle Application Server Containers for J2EE Standalone User's Guide
Elements in the orion-application.xml File
A relative/absolute path/URL to a directory or a JAR/ZIP to add as a library-path for this server. Directories are scanned for JARS/ZIP files to include at startup. Attribute:
path - The path.
<log> Logging settings. <odl> The ODL log entries are each written out in XML format in its respective log file. The log files have a maximum limit. When the limit is reached, the log files are overwritten. When you enable ODL logging, each message goes into its respective log file, named logN.xml, where N is a number starting at one. The first log message starts the log file, log1.xml. When the log file size maximum is reached, the second log file is opened to continue the logging, log2.xml. When the last logfile is full, the first log file, log1.xml is erased and a new one is opened for the new messages. Thus, your log files are constantly rolling over and do not encroach on your disk space. Attributes:
path: Path and folder name of the log folder for this area. You can use an absolute path or a path relative to where the configuration XML file exists, which is normally in the j2ee/home/config directory. This denotes where the log files will reside for the feature that the XML configuration file is concerned with. For example, modifying this element in the server.xml file denotes where the server log files are written. max-file-size: The maximum size in KB of each individual log file. max-directory-size: The maximum size of the directory in KB. The default directory size is 10 MB.
New files are created within the directory, until the maximum directory size is reached. Each log file is equal to or less than the maximum specified in the attributes. <mail address="[e-mail]" /> An e-mail address to log events to. A valid mail-session also needs to be specified if this option is used. Attribute:
address - The mail-address.
<mail-session location="mail/TheSession" smtp-host="smtp.server.com"> The session SMTP-server host (if using SMTP). Attributes:
location - The location in the namespace to store the session at. smtp-host - The session SMTP-server host (if using SMTP).
<namespace-access> Namespace (naming context) security policy for RMI clients. <namespace-resource root="the/path"> A resource with a specific security setting.
Additional Information B-19
Elements in the orion-application.xml File
Attribute:
root - The root of the part of the namespaec that this rule applies to.
<password-manager> Specifies the UserManager that is used for the lookup of hidden passwords. If omitted, the current UserManager is used for authentication and authorization. For example, you can use a OracleAS JAAS Provider LDAP UserManager for the overall UserManager, but use a OracleAS JAAS Provider XML UserManager for checking hidding passwords. To identify a UserManager, provide a <jazn> element definition within this element, as follows:
<password-manager> <jazn ...> </password-manager>
<persistence path="./persistence" /> A relative (to the application root) or absolute path to a directory where application state should be stored across restarts. Attribute:
path - The path (relative to the enterprise archive or absolute) to the persistence directory.
<principals path="principals.xml" /> Attribute:
path - The path (relative to the enterprise archive or absolute) to the principals file.
<property name="theName" value="theValue" /> Contains a name/value pair initialization param. Attributes:
name - The name of the parameter. value - The value of the parameter.
<read-access> The read-access policy. <resource-provider> Define a JMS resource provider. To add a custom <resource-provider>, add the following to your orion-application.xml file:
<resource-provider class="providerClassName" name="JNDI name"> <description> description </description> <property name="name" value="value" /> </resource-provider>
In place of the user-replaceable constructs (those in italics) in the preceding code, do the following:
Replace the value providerClassName of the class attribute with the name of the resource-provider class.
B-20 Oracle Application Server Containers for J2EE Standalone User's Guide
Elements in the application-client.xml File
Replace the value JNDI name of the name attribute with a name by which to identify the resource provider. This name will be used in finding the resource provider in the application's JNDI as "java:comp/resource/name/". Replace the value description of the description element with a description of the specific resource provider. Replace the values name and value of the corresponding attributes with the same name in any property elements that the specific resource provider needs to be given as parameters.
<security-role-mapping impliesAll="true|false" name="theRole"> The runtime mapping (to groups and users) of a role. Maps to a security-role of the same name in the assembly descriptor. Attributes:
impliesAll - Whether or not this mapping implies all users. The default is false. name - The name of the role
<user name="theUser" /> A user that this security-role-mapping implies. Attribute:
name - The name of the user.
<user-manager class="com.name.of.TheUserManager" display-name="Friendly UserManager name"> Specifies an optional user-manager to use. For example, user-managers are com.evermind.sql.DataSourceUserManager, com.evermind.ejb.EJBUserManager, and so on. These are used to integrate existing systems and provide custom user-managers for Web applications. Attributes:
class - The fully qualified classname of the user-manager. display-name - A descriptive name for this UserManager instance.
<web-module id="myWebApp" path="myWebApp.war" /> A Web application module of the application. Each Web application can be installed on any site and in any context on those sites (for instance http://www.myserver.com/myapp/). Attributes:
id - The name used to reference this web-application when used in web-sites etc. path - The path (relative to the enterprise archive or absolute) to the web-application.
<write-access> The write access policy.
Elements in the application-client.xml File
This section describes the J2EE application client deployment descriptor file.
Additional Information
B-21
Elements in the application-client.xml File
<application-client> Element Description
The top level element of the application-client.xml file is the <application-client> element.
<application-client>
The application-client element is the root element of an application client deployment descriptor. The application client deployment descriptor describes the EJB components and external resources referenced by the application client.
Elements Contained Within <application-client>
Within the <application-client> element, the following elements, which are listed alphabetically and not by DTD ordering, can be configured: <callback-handler> The callback-handler element names a class provided by the application. The class must have a no args constructor and must implement the javax.security.auth.callback.CallbackHandler interface. The class will be instantiated by the application client container and used by the container to collect authentication information from the user. <description>The description</description> A short description. <display-name>The name</display-name> The display-name element contains a short name that is intended to be displayed by tools. <ejb-link>EmployeeRecord</ejb-link> The ejb-link element is used in the ejb-ref element to specify that an EJB reference is linked to an enterprise bean in the encompassing J2EE Application package. The value of the ejb-link element must be the ejb-name of an enterprise bean in the same J2EE Application package. <ejb-ref> The ejb-ref element is used for the declaration of a reference to an enterprise bean's home. The declaration consists of an optional description; the EJB reference name used in the code of the referencing application client; the expected type of the referenced enterprise bean; the expected home and remote interfaces of the referenced enterprise bean; and an optional ejb-link information. The optional ejb-link element is used to specify the referenced enterprise bean. <ejb-ref-name>ejb/Payroll</ejb-ref-name> The ejb-ref-name element contains the name of an EJB reference. The EJB reference is an entry in the enterprise bean's environment. It is recommended that name is prefixed with "ejb/". <ejb-ref-type>Entity/Session</ejb-ref-type> The ejb-ref-type element contains the expected type of the referenced enterprise bean. The ejb-ref-type element must be one of the following: Entity Session <env-entry> The env-entry element contains the declaration of an Enterprise JavaBean's environment entries. The declaration consists of an optional description, the name of the environment entry, and an optional value.
B-22 Oracle Application Server Containers for J2EE Standalone User's Guide
Elements in the application-client.xml File
<env-entry-name>minAmount</env-entry-name> The env-entry-name element contains the name of an Enterprise JavaBean's environment entry. <env-entry-type>java.lang.String</env-entry-type> The env-entry-type element contains the fully-qualified Java type of the environment entry value ...