10g (9.0.4)
Part Number B10321-01
 Home |
 Contents |
 Index |
| Oracle Application Server Containers for J2EE Servlet Developer's Guide 10g (9.0.4) Part Number B10321-01 |
|
This chapter provides an overview of OC4J configuration, packaging, and deployment for servlet developers, primarily in an OC4J standalone environment. It includes the following sections:
Because this is a developer's guide, much of it is intended for use in an OC4J standalone environment, which is convenient for application development stages. OC4J standalone consists of a single OC4J instance outside the Oracle Application Server environment. Most of this chapter is specific to configuration and deployment in a standalone environment, where you are developing on the same system you are deploying to.
When your application is ready for enterprise use, you can deploy it to the Oracle Application Server environment. This chapter provides an overview of deployment and configuration in Oracle Application Server, and Chapter 7, "Configuration with Enterprise Manager", provides additional information . Your primary information source for using OC4J in an Oracle Application Server environment, however, should be the Oracle Application Server Containers for J2EE User's Guide.
The following sections provide some overview:
Many OC4J features discussed in this manual, particularly in this chapter, are for use in OC4J standalone only, during development. In Oracle Application Server, which offers enterprise management features for large-scale production environments, it is critical to maintain controls to prevent actions that might compromise the server during operation. Because this is not such a concern while you are developing in a standalone environment, there are fewer restrictions on what you can or should do in OC4J standalone.
OC4J standalone provides the admin.jar command-line utility for deploying, configuring, and managing applications. It is also possible, especially for early testing, to manually deploy files and manually update configuration files. In particular, for initial testing, there is an OC4J default Web application that you can use for individual servlet files, JSP pages, and dependency classes.
|
Note:
Key |
For initial considerations when using OC4J standalone for development, including use of the OC4J development flag to trigger automatic recompilation and reloading of modified servlets, see "OC4J Standalone for Development".
In an enterprise production environment, OC4J is contained within Oracle Application Server, which takes over management of the J2EE enterprise systems. Oracle Application Server can oversee multiple clustered OC4J processes and is managed through the Oracle Enterprise Manager. Through Enterprise Manager, you can manage and configure your OC4J processes across multiple application server instances and hosts. Thus, you cannot locally manage your OC4J process by using the admin.jar tool or by manually updating configuration files, because this would conflict with the management provided by Enterprise Manager.
Table 5-1 summarizes OC4J deployment and configuration features, comparing OC4J standalone to OC4J in Oracle Application Server.
Table 5-2 summarizes OC4J features and practices relating to Web sites, again comparing OC4J standalone to OC4J in Oracle Application Server.
OC4J supports the standard J2EE application structure and deployment vehicles. This includes the use of an EAR file to deploy a complete J2EE application, which might include Web modules, EJB modules, application client modules, and resource adapter modules (used for connector factories). There can be zero or more of each type of module. It is also possible to use an independent WAR file to deploy an independent Web application. (For a complete application that includes a Web module, the WAR file is included inside the EAR file.) For more information about these features, refer to the Sun Microsystems Java 2 Platform Enterprise Edition Specification and the Java Servlet Specification. These are available at the following Web sites:
http://java.sun.com/j2ee/docs.html http://jcp.org/aboutJava/communityprocess/first/jsr053/index.html
Before deploying a J2EE application, you must complete the following steps:
application.xml and web.xml, and, as desired, create OC4J descriptors, such as orion-application.xml and orion-web.xml. If you do not create the OC4J descriptors, they will be generated automatically during deployment of a J2EE application, which is sufficient if you do not need anything beyond default settings.
orion-application.xml, place it with application.xml. If you provide orion-web.xml, place it with web.xml. Although it is possible to deploy loose files into the appropriate directory structure, it is more typical to deploy applications in EAR or WAR files. See "Application Packaging".
After you have packaged your application, there are several scenarios for deployment, as discussed later in this chapter.
In an OC4J standalone environment, your options include the following:
In an Oracle Application Server environment, use Enterprise Manager to deploy and configure your applications. See "Overview of OC4J Deployment and Configuration in Oracle Application Server".
|
Note: You can also use an IDE, such as Oracle JDeveloper, for developing, packaging, deploying, and configuring your application. See "Oracle JDeveloper Support for Servlet Development" for an introduction and overview. |
This discussion considers two modes of operation when deploying and configuring applications for OC4J. One can be called supported client mode, using tools provided by Oracle for either OC4J standalone or Oracle Application Server. The other, used during development and testing phases and in OC4J standalone only, can be called expert mode. In expert mode, you are manipulating files directly--manually placing EAR files, WAR files, or loose files on the system, and manually updating configuration descriptors. These modes are summarized in the following table.
| OC4J Standalone | OC4J in Oracle Application Server | |
|---|---|---|
| Supported Client Mode |
|
Enterprise Manager or |
| Expert Mode |
Direct manipulation of server files |
Not applicable/appropriate |
In expert mode, you are operating outside the safeguards and constraints of the OC4J and Oracle Application Server tools.
In OC4J standalone, Oracle generally assumes that you will either deploy with admin.jar and not manually update files, or you will manually update files and not deploy with admin.jar. Crossing between these scenarios might cause unpredictable results.
In Oracle Application Server, do not try to directly manipulate server files. The Oracle Application Server Distributed Configuration Management subsystem (DCM) maintains a repository of configuration information. This repository--not configuration files on the file system--contains the true configuration settings. Enterprise Manager and the dcmctl command-line tool work in concert with DCM so that the configuration repository is properly updated when you use either of these tools.
There are several categories and levels of configuration files--both OC4J-specific and J2EE-standard, and both global and application-level--for configuring OC4J and an OC4J application.
While developing and testing your application in an OC4J standalone environment, you can manipulate these configuration files either manually or through the admin.jar utility, which OC4J provides. For example, the admin.jar -deploy command automatically updates server.xml to add the specified J2EE application to OC4J, and the admin.jar -bindWebApp command automatically updates the specified Web site XML file to bind the specified Web module to the Web site.
Key admin.jar commands are discussed later in this chapter, where applicable. See the Oracle Application Server Containers for J2EE Stand Alone User's Guide for further details about the admin.jar utility.
The following sections introduce OC4J and application configuration files:
Refer to the following for additional information:
You can divide the OC4J and J2EE configuration files into five categories:
The global files can affect anything running on the OC4J server and can establish defaults for both J2EE and OC4J-specific features at the application level and the Web-site level. The J2EE files can override any defaults for standard J2EE features and establish additional J2EE-standard settings. The OC4J-specific application-level files can override defaults in the corresponding global files, override settings in the corresponding J2EE files, and add OC4J-specific features and settings.
Of particular interest to servlet developers are the top-level OC4J server configuration file (server.xml), the application descriptors (OC4J global, J2EE application-level, and OC4J application-level), the Web descriptors (OC4J global, J2EE application-level, and OC4J application-level), and the OC4J Web site descriptors. Each of these topics is discussed in more detail shortly.
Server-level and global configuration files are located in the j2ee/home/config directory by default. OC4J looks there for the server.xml file, and server.xml in turn specifies the locations of the other server-level and global files (by default, the same directory). In OC4J standalone, the configuration file directory is configurable through the java -config command-line option.
The following discussion summarizes the preceding five configuration file categories.
The server.xml file is located in the j2ee/home/config directory and specifies locations of the other server configuration files and the Web site configuration files, which are also in j2ee/home/config by default.
The files in this category are OC4J-specific, configuring different aspects of the OC4J server.
server.xml: This parent file for all OC4J configuration includes elements pointing to other server-level and global configuration files, all Web sites on the server, and all applications on the server (including the OC4J default application). See "OC4J Top-Level Server Configuration File: server.xml" below.
jazn.xml: This configuration file for Oracle Application Server Java Authentication and Authorization Service (OracleAS JAAS Provider) specifies the directory path to the server-level jazn-data.xml file.
jazn-data.xml: This server-level JAAS file contains user name and role information for the XML-based provider. There is also an application-level version. This file is not used if OracleAS JAAS Provider uses the LDAP-based provider instead.
data-sources.xml: This file contains data source definitions for database connections.
rmi.xml: This file contains configuration features for remote method invocation.
jms.xml: This file contains configuration features for the Java Message Service.
Files in this category are OC4J-specific, defining settings for OC4J global features such as the default application and determining default settings for corresponding application-level configuration files.
application.xml: This file is the OC4J-specific global application descriptor. See "OC4J and J2EE Application Descriptors".
global-web-application.xml: This is the OC4J-specific global Web descriptor. See "OC4J and J2EE Web Descriptors".
oc4j-connectors.xml: This is the OC4J-specific global descriptor for resource adapters (for connector factories).
Each Web site that is recognized by the server has a Web site XML file to configure it. In Oracle Application Server, there is just one Web site. In OC4J standalone, there is typically one Web site, but you might use a second Web site for "shared" applications, for example, where some communication is through HTTP and some through HTTPS. It is also possible for there to be no Web sites, if the OC4J instance is not used for Web modules. See "OC4J Web Site Descriptors".
default-web-site.xml: This is the default Web site descriptor in an Oracle Application Server environment.
http-web-site.xml: This is the default Web site descriptor in an OC4J standalone environment.
J2EE configuration files are included within the standard application structure. If you include OC4J application-level configuration files in your EAR or WAR file, they also go within the application structure. See "J2EE Application Structure". Upon deployment of a J2EE application, the OC4J files are either copied (if you included them) or generated (if you did not include them) in the deployment directory, typically under j2ee/home/application-deployments.
Files in this category are all application-level and are defined by the J2EE specification.
application.xml: This is the J2EE-standard application descriptor. See "OC4J and J2EE Application Descriptors".
web.xml: This file is the J2EE-standard Web descriptor. See "OC4J and J2EE Web Descriptors".
ejb-jar.xml: This file is the J2EE-standard EJB descriptor.
application-client.xml: This file is the J2EE-standard descriptor for application clients.
ra.xml: This file is the J2EE-standard descriptor for resource adapters (for connector factories).
Files in this category are OC4J-specific at the application level. They configure OC4J-specific functionality to complement standard functionality from the corresponding J2EE descriptor, and override default settings from the corresponding server-level or global descriptor.
orion-application.xml: This file is the OC4J-specific application descriptor. See "OC4J and J2EE Application Descriptors".
orion-web.xml: This file is the OC4J-specific Web descriptor. See "OC4J and J2EE Web Descriptors".
orion-ejb-jar.xml: This file is the OC4J-specific EJB descriptor.
jazn-data.xml: This application-level JAAS file contains user name and role information for the XML-based provider. There is also a server-level version. This file is not used if OracleAS JAAS Provider uses the LDAP-based provider instead.
orion-application-client.xml: This file is the OC4J-specific descriptor for application clients.
oc4j-ra.xml: This file is the OC4J-specific descriptor for resource adapters (for connector factories).
See the following documents for more information about the preceding descriptors:
server.xml and load balancing
The OC4J server.xml file, located in the OC4J j2ee/home/config directory by default, is the starting point for configuration of the OC4J server and all J2EE applications, Web applications, and Web sites for the server. In particular, note the following:
<application-server> element specify, among other things, the target directory for deployed EAR files and where they are unpacked (determined by the application-directory setting), and the target directory for copied or generated OC4J descriptors (determined by the deployment-directory setting).
|
Note:
A key |
<global-application> element specifies the OC4J global application, otherwise known as the default application, which, by default, is the parent of all other applications. The name attribute defines its name; the path attribute specifies what to use as the OC4J global application descriptor. See "OC4J Default Application and Default Web Application" for a discussion of the OC4J default application.
<global-web-app-config> element, through its path attribute, specifies what to use as the OC4J global Web application descriptor.
<web-site> element for each Web site recognized by the server, with the path attribute specifying what to use as the corresponding Web site XML file. OC4J comes with one such element already configured.
<application> element for each J2EE application deployed to the server. The name attribute specifies the desired J2EE application name. The path attribute reflects where the EAR file is deployed and unpacked, or where application files exist that have already been unpacked (or were manually placed). In either case, the name attribute is typically the same as the EAR file name without the .ear extension. In the first case, the path attribute specifies the full path to the EAR file, including the EAR file name. In the second case, the path attribute specifies the top-level directory of the extracted files.
<rmi-config> element, through its path attribute, specifies what to use as the OC4J RMI descriptor.
<jms-config> element, through its path attribute, specifies what to use as the OC4J JMS descriptor.
The server.xml file is discussed in detail in the Oracle Application Server Containers for J2EE User's Guide, but an example is also provided here:
<?xml version="1.0"?> <!DOCTYPE application-server PUBLIC "-//Evermind//DTD Orion Application-server//EN" "http://xmlns.oracle.com/ias/dtds/application-server.dtd"> <application-server application-directory="../applications" deployment-directory="../application-deployments" connector-directory="../connectors" > <rmi-config path="./rmi.xml" /> <jms-config path="./jms.xml" /> <log> <file path="../log/server.log" /> </log> <transaction-config timeout="250000" /> <global-application name="default" path="application.xml" /> <application name="petstore" path="../applications/petstore.ear" ... /> <global-web-app-config path="global-web-application.xml" /> <web-site default="true" path="./default-web-site.xml" /> <web-site path="../myconfig/my-web-site.xml" /> <cluster id="-1406559522" /> </application-server>
Figure 5-1, which follows, illustrates the mappings between the server.xml file, other XML files including Web site XML files, and J2EE EAR files. Note that in this figure, the <application> elements in server.xml point to top-level directories of extracted EAR files, as opposed to intact EAR files.
An application descriptor specifies the components of a J2EE application, such as EJB and Web modules, and can specify additional configuration for the application as well.
There are three categories of application descriptors to consider in using OC4J. The following sections discuss each of them, then summarize their relationships to each other:
The server.xml file points to the application descriptor of each application on OC4J, either directly or indirectly. In the case of a typical J2EE application, server.xml points to the EAR file (or extracted EAR top-level directory) and, therefore, to the application.xml file that the EAR file contains. In the case of the OC4J global application, the server.xml file points directly to the OC4J global application descriptor.
See the Oracle Application Server Containers for J2EE User's Guide for more information about application descriptors in OC4J.
The J2EE standard defines the concept and DTD of an application descriptor, called application.xml, that you must include in the /META-INF directory of the EAR file of a J2EE application. The application descriptor acts as a manifest of the modules contained in the application, possibly with additional configuration information as well, and in some development environments can be created automatically for you.
See the Sun Microsystems Java 2 Platform Enterprise Edition Specification for more information.
Here is an example for an application with an EJB module, a Web module, and a client module:
<?xml version="1.0" ?> <!DOCTYPE application (View Source for full doctype...)> <application> <display-name>stateful, application:</display-name> <description> A sample J2EE application that uses a remote stateful session bean to call a local entity bean. </description> <module> <ejb>stateful-ejb.jar</ejb> </module> <module> <web> <web-uri>stateful-web.war</web-uri> <context-root>/stateful</context-root> </web> </module> <module> <java>stateful-client.jar</java> </module> </application>
There is also an OC4J-specific global application descriptor, defined by an OC4J-specific DTD, orion-application.dtd. This is the descriptor for the OC4J global application, as specified by the <global-application> element in the server.xml file. This element specifies the global application name, default by default, and the global application descriptor name, application.xml by default and usually located in the same directory as server.xml.
The OC4J global application is usually referred to as the "default application" and, by default, is the parent application of all other applications in the OC4J instance.
Following is an abbreviated sample application.xml file for the OC4J default application. Note that it specifies the name of a Web application, defaultWebApp, which by convention is bound to one or more Web sites as the default Web application.
Do not confuse the OC4J default J2EE application with the default Web application that it contains. See "OC4J Default Application and Default Web Application" for related information.
<?xml version="1.0" standalone='yes'?> <!DOCTYPE orion-application PUBLIC "-//Evermind//DTD J2EE Application runtime 1.2//EN" "http://xmlns.oracle.com/ias/dtds/orion-application.dtd"> <!-- The global application config that is the parent of all the other applications in this server. --> <orion-application autocreate-tables="true" default-data-source="jdbc/OracleDS"> <web-module id="defaultWebApp" path="../../home/default-web-app" /> <connectors path="./oc4j-connectors.xml"/> <!-- Path to the libraries that are installed on this server. These will accesible for the servlets, EJBs etc --> <library path="../../home/lib" /> <!-- Path to the taglib directory that is shared among different applications. --> <library path="../../home/jsp/lib/taglib" /> <log> <file path="../log/global-application.log" /> </log> <data-sources path="data-sources.xml" /> <namespace-access> <read-access> <namespace-resource root=""> <security-role-mapping> <group name="administrators" /> </security-role-mapping> </namespace-resource> </read-access> <write-access> <namespace-resource root=""> <security-role-mapping> <group name="administrators" /> </security-role-mapping> </namespace-resource> </write-access> </namespace-access> </orion-application>
In addition to the standard application descriptor, application.xml, there is an OC4J-specific application-level application descriptor, orion-application.xml. This is defined by the same DTD as the OC4J global application descriptor. You can provide an orion-application.xml file as well as an application.xml file, also in the /META-INF directory of your EAR file. The orion-application.xml file can add OC4J-specific configuration.
Including an orion-application.xml file in your EAR file is optional. If you include it, OC4J copies it into the deployment directory during deployment (under j2ee/home/application-deployments by default). Otherwise, OC4J generates one for you in the deployment directory, using default settings from the OC4J global application descriptor (assuming the OC4J default application is the parent application, as is the case by default) and the application.xml file in the EAR file. See "J2EE Application Structure" for information about where orion-application.xml fits in the application structure.
In most circumstances, you should use orion-application.xml only to define OC4J-specific configuration such as security role mappings. Also note that if OC4J generates the file, it creates <web-module> elements to reflect the modules specified in the J2EE application.xml file.
The following example shows some OC4J-specific configuration and defines the same EJB, Web, and client modules as defined in the example of the standard application.xml file in "Standard J2EE Application Descriptors":
<?xml version="1.0"?> <!DOCTYPE orion-application PUBLIC "-//Evermind//DTD J2EE Application runtime 1.2//EN" "http://xmlns.oracle.com/ias/dtds/orion-application.dtd"> <orion-application default-data-source="jdbc/OracleDS"> <ejb-module remote="false" path="stateful-ejb.jar" /> <web-module id="stateful-web" path="stateful-web.war" /> <client-module path="stateful-client.jar" auto-start="false" /> <persistence path="persistence" /> <log> <file path="application.log" /> </log> <namespace-access> <read-access> <namespace-resource root=""> <security-role-mapping name="<jndi-user-role>"> <group name="users" /> </security-role-mapping> </namespace-resource> </read-access> <write-access> <namespace-resource root=""> <security-role-mapping name="<jndi-user-role>"> <group name="users" /> </security-role-mapping> </namespace-resource> </write-access> </namespace-access> </orion-application>
To summarize the relationship between J2EE application descriptors, the OC4J global application descriptor, and OC4J application-level application descriptors:
application.xml. This file acts as a manifest for the modules of a J2EE application and must be placed in the /META-INF directory of the J2EE application EAR file.
application.xml but defined by an OC4J-specific DTD, becomes relevant because no J2EE standard application.xml file is associated with a standalone WAR file.
orion-application.xml descriptor for additional OC4J configuration, such as for security role mappings. The orion-application.xml file might also specify additional modules, beyond those specified in the J2EE application.xml file, and can even override modules specified in application.xml (though this is not advisable). The orion-application.xml file would also be in the /META-INF directory of the EAR file. If you do not include this file, it is created automatically during deployment, using defaults from the OC4J global application descriptor (assuming the default application is the parent of your application, which is true by default). The orion-application.xml descriptors are defined according to the same DTD as the OC4J global application descriptor.
A Web descriptor specifies and configures a set of J2EE Web components: static pages, servlets, and JSP pages. The Web components might together form an independent Web application and be deployed in a standalone WAR file. More typically, however, they will form just part of an overall J2EE application, being deployed in a WAR file within the EAR file of the J2EE application.
There are three categories of Web descriptors to consider in using OC4J. The following sections discuss each of them and summarize the relationships between them:
The J2EE servlet specification defines the concept and DTD of a Web descriptor, called web.xml, that you must include in the /WEB-INF directory of the associated WAR file. The web.xml file specifies and configures the Web components of the WAR file, as well as other components, such as EJBs, that the Web components might call.
See the Sun Microsystems Java Servlet Specification for more information.
Here is a sample web.xml file specifying, among other things, a servlet, the servlet mapping, and a local EJB lookup:
<?xml version="1.0"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app> <display-name>stateful, web-app:</display-name> <description>no description</description> <welcome-file-list> <welcome-file>index.html</welcome-file> </welcome-file-list> <ejb-local-ref> <ejb-ref-name>CartBean</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home>cart.CartHome</local-home> <local>cart.Cart</local> </ejb-local-ref> <servlet> <servlet-name>cart</servlet-name> <servlet-class>cart.CartServlet</servlet-class> <init-param> <param-name>param1</param-name> <param-value>1</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>cart</servlet-name> <url-pattern>/cart</url-pattern> </servlet-mapping> <security-role> <role-name>users</role-name> </security-role> </web-app>
The server.xml file, through its <global-web-app-config> element, specifies the OC4J global Web application descriptor. It is typically global-web-application.xml, in the same directory as server.xml. This descriptor defines default behavior for Web applications in OC4J.
The global Web application descriptor is defined by the DTD orion-web.dtd. This is the same DTD as for the application-level OC4J-specific Web descriptor, orion-web.xml, described in the next section, "OC4J-Specific Web Descriptors".
The orion-web.dtd is a superset of the standard DTD for web.xml. There is a <web-app> subelement of the <orion-web-app> top-level element in orion-web.dtd, which has the same specification as the top-level <web-app> element of web.xml. There are also many other subelements of <orion-web-app> for specifying and configuring OC4J-specific features.
For any default settings you specify within the <web-app> element in global-web-application.xml, you can add to or, optionally, override these settings through <web-app> settings in web.xml. You can then add to or, optionally, override the resulting settings through <web-app> settings in orion-web.xml.
For any default settings you specify outside the <web-app> element in global-web-application.xml, you can add to or, optionally, override these settings through parallel settings in orion-web.xml.
For detailed information about the elements and attributes of the OC4J global Web application descriptor, including the DTD and a hierarchical representation, see "Configuration for global-web-application.xml and orion-web.xml".
See "Sample global-web-application.xml Settings" for an abbreviated sample global-web-application.xml file.
In addition to the standard Web descriptor, web.xml, and the OC4J global Web application descriptor, global-web-application.xml (which establishes default behavior), there is an OC4J-specific application-level Web descriptor, orion-web.xml.
The orion-web.xml descriptor is defined by the DTD orion-web.dtd. This is the same DTD as for the global Web application descriptor that was described in the previous section, "OC4J Global Web Application Descriptor".
You can provide an orion-web.xml file as well as the web.xml file, also in the /WEB-INF directory of your WAR file. Use orion-web.xml to add to or, optionally, override any default settings in global-web-application.xml, as well as to add to or override any settings in web.xml.
Including an orion-web.xml file in your WAR file (inside the EAR file) is optional. If you include it, OC4J copies it into the deployment directory during deployment (under the j2ee/home/application-deployments directory by default). Otherwise, OC4J generates orion-web.xml for you in the deployment directory, using default settings from global-web-application.xml. Additionally, some web.xml settings will influence the generation of orion-web.xml. For example, <resource-ref> entries in web.xml will result in corresponding <resource-ref-mapping> entries in orion-web.xml. See "J2EE Application Structure" for information about where orion-web.xml fits in the application structure.
For detailed information about the elements and attributes of the OC4J-specific Web descriptor, including the DTD and a hierarchical representation, see "Configuration for global-web-application.xml and orion-web.xml".
A sample orion-web.xml file follows:
<?xml version="1.0" ?> <!DOCTYPE orion-web-app (View Source for full doctype...)> <orion-web-app jsp-cache-directory="./persistence" temporary-directory="./temp" servlet-webdir="/servlet/" default-buffer-size="2048" development="false" directory-browsing="deny" file-modification-check-interval="1000" jsp-timeout="0 (never)"> <ejb-ref-mapping name="EmployeeBean" /> <security-role-mapping name="users"> <group name="users" /> </security-role-mapping> <!-- <web-app> There are no <web-app> entries in this sample. </web-app> --> </orion-web-app>
You can think of the relationship between global-web-application.xml, web.xml, and orion-web.xml as follows:
global-web-application.xml file establishes defaults for any Web application in OC4J.
web.xml file overlays anything defined in the <web-app> element of global-web-application.xml, adding to and possibly overriding any Web components and other settings defined there.
orion-web.xml file overlays everything, adding to and possibly overriding any settings from global-web-application.xml and web.xml.
Each Web site in OC4J is defined and configured through a Web site XML file. The key functions of a Web site XML file are the following:
The server.xml file indicates the number of Web sites that OC4J recognizes, by including a <web-site> element for each site. Each of these elements specifies the path and file name for the corresponding Web site XML file, as in the following sample server.xml entries:
... <web-site path="./default-web-site.xml" /> <web-site path="mydir/my-web-site.xml" /> ...
In Oracle Application Server, there is just one Web site. In OC4J standalone, there is typically one Web site, but you might use a second Web site for "shared" applications, for example, where some communication is through HTTP and some through HTTPS. (For information about shared applications, see the description of the <web-app> element shared attribute in "Element Descriptions for Web Site XML Files".)
A Web site XML file contains a <web-app> element for each Web module to bind to the Web site. At a minimum, each <web-app> element has the following:
application attribute to specify the name of the J2EE application to which the Web module belongs (the same as the EAR file name without the .ear extension)
name attribute to specify the name of the Web module (the same as the WAR file name without the .war extension)
root attribute to specify the context path on this Web site to which the Web module is to be bound
There is also a <default-web-app> element for the default Web application. The default Web application is useful in OC4J standalone during development, as discussed in "OC4J Default Application and Default Web Application". In Oracle Application Server, it is used for some system-level functionality but is not otherwise meaningful. See "OC4J Default Web Application in Oracle Application Server".
|
Important:
|
By default, OC4J comes configured with one Web site XML file: http-web-site.xml in OC4J standalone, or default-web-site.xml in Oracle Application Server.
See "Configuration for Web Site XML Files" for detailed information about the elements and attributes of Web site XML files, including the DTD and a hierarchical representation.
See "Sample default-web-site.xml File" for an example, in this case a sample default-web-site.xml file for an Oracle Application Server environment.
This example shows how an entry in server.xml points to a Web site descriptor (Web site XML file), and how a <web-app> element in the Web site XML file points to a Web module. The <web-app> element binds the Web module to the Web site. The Web module is defined in the application.xml file (also shown) of the containing J2EE application.
The server.xml file includes an <application> element for the relevant J2EE application (which contains the desired Web module) and includes a <web-site> element specifying the Web site XML file for the desired Web site:
<application-server ... > ... <application name="myear" path="../myapps/myear.ear" /> ... <web-site path="my-web-site.xml" /> ... </application-server>
The Web site XML file, my-web-site.xml, configures the Web site and has a <web-app> element that specifies the J2EE application that contains the Web module, the name of the Web module itself, and the root context path for accessing the Web module:
... <web-site protocol="http" port="8888" display-name="My Web Site" host="[ALL]" log-request-info="false" secure="false"> ... <web-app application="myear" name="mywebmod1" root="/someUrl" load-on-startup="false" max-inactivity-time="no shutdown" shared="false" /> ... </web-site>
See "Element Descriptions for Web Site XML Files" for information about the <web-site> and <web-app> attributes shown here.
|
Note:
For a Web application (WAR file) that is deployed to the OC4J default application instead of being deployed within an EAR file, the See "OC4J Default Application and Default Web Application" for general information about the default application. |
The J2EE application.xml file in myear.ear specifies the Web module:
<application ... > ... <module> <web> <web-uri>mywebmod1.war</web-uri> <context-root>/someUrl</context-root> </web> </module> ... </application>
Note the following:
root attribute of the <web-app> element in my-web-site.xml overrides the value of the <context-root> element in application.xml. As a convention, though, use the same setting in both places.
default-web-site.xml file, by default, sets up a Web site that accesses OC4J through the Oracle HTTP Server and AJP (Apache JServ protocol), using a protocol setting of "ajp13" and a port setting of "0". However, OPMN, the Oracle Process Management and Notification system, overrides this port setting.
http-web-site.xml file, by default, sets up a Web site that accesses the OC4J listener directly, using a protocol setting of "http" and a port setting of "8888".
OC4J supports standard J2EE archive files for deployment, including WAR files for Web modules and EAR files for overall J2EE applications. The following sections review the structure of these files:
This section reviews the standard J2EE application structure, which you can use as your development structure as appropriate. This discussion also shows the relative locations of optional OC4J-specific descriptors. If you do not include the OC4J-specific descriptors in your deployment, OC4J generates them for you when you deploy a J2EE application, using values from corresponding OC4J global descriptors and J2EE descriptors as defaults.
J2EEAppName/ META-INF/ application.xml orion-application.xml (optional) EJBModuleName/ (EJB classes, according to package) META-INF/ ejb-jar.xml orion-ejb-jar.xml (optional) WebModuleName/ (static files, such as index.html) (JSP pages) WEB-INF/ web.xml orion-web.xml (optional) classes/ (servlet classes, according to package) lib/ (JAR files for dependency classes) ClientModuleName/ (client classes, according to package) META-INF/ application-client.xml orion-application-client.xml ResourceAdapterModuleName/ META-INF/ ra.xml (JAR files for required classes) (required static files or other files)
The Web portion is marked in bold type. This portion reflects the structure of WAR files used to deploy Web modules. At the top level are static pages (such as index.html), JSP pages, and the /WEB-INF directory.
|
Notes:
|
In J2EE, a WAR file is typically contained within an EAR file. In the example in the preceding section, the EAR file, J2EEAppName.ear, would have its /META-INF directory at the top level, along with Web module WAR files, EJB module JAR files, client application JAR files, and resource adapter RAR files (zero or more of each, as applicable):
META-INF/ application.xml orion-application.xml (optional) EJBModuleName.jar WebModuleName.war ClientModuleName.jar ResourceAdapterModuleName.rar
This example shows the structure of the archive files for a simple Web application. The EAR file contains a WAR file, which contains a single servlet.
Following are the contents of utility.ear. If there were EJB, client application, or resource adapter modules, the associated JAR files would be at the same level as the WAR file. Optionally, you could also include an orion-application.xml file in the /META-INF directory. Instead, in this example, one would be generated by OC4J during deployment.
META-INF/MANIFEST.MF META-INF/application.xml utility_web.war
Here are the contents of utility_web.war. Optionally, you could also include an orion-web.xml file in the /WEB-INF directory. Instead, in this example, one would be generated by OC4J during deployment.
META-INF/MANIFEST.MF WEB-INF/classes/TestStatusServlet.class WEB-INF/web.xml index.html
|
Notes:
|
This section reviews some preliminary considerations and then discusses several scenarios for deployment to OC4J standalone. The primary deployment scenario is to use the admin.jar utility after you package your application in an EAR file. The EAR file optionally contains Web module WAR files, EJB module JAR files, client application JAR files, and resource adapter RAR files (zero or more of each). See "Application Packaging" for more information about structure and packaging.
The use of EAR files for OC4J deployment, and features of the admin.jar utility, are covered extensively in the Oracle Application Server Containers for J2EE Stand Alone User's Guide. Key features are discussed here.
In addition, this section considers alternative deployment scenarios that you might find useful during development, such as manually creating and populating a J2EE application structure or deploying an independent WAR file into the OC4J default application.
|
Note: In these alternative deployment scenarios, in which you manually place and update files, you are considered to be in "expert mode". You are operating outside the safeguards and constraints of the OC4J and Oracle Application Server tools. See "Using Oracle Deployment Tools Versus Expert Modes". |
This section includes the following subjects:
Before using the admin.jar utility to deploy an application in OC4J standalone, you must have a user with administrative privileges.
The j2ee/home/config/jazn-data.xml file determines security privileges for user accounts. By default, there is a user admin with administrative privileges, as specified in the following sample jazn-data.xml entry:
<role> <name>administrators</name> <display-name>Realm Admin Role</display-name> <description>Administrative role for this realm.</description> <members> <member> <type>user</type> <name>admin</name> </member> </members> </role>
For the default administrative user admin, the default password is welcome, as in the following sample jazn-data.xml entry:
<users> ... <user> <name>admin</name> <display-name>OC4J Administrator</display-name> <description>OC4J Administrator</description> <credentials>!welcome</credentials> </user> ... </users>
(The file is automatically rewritten later to obfuscate the specified password.) See the Oracle Application Server Containers for J2EE Security Guide for more information about the jazn-data.xml file, especially regarding the <credentials> element.
This section provides a quick review of how to start and stop OC4J standalone. Assume % is the system prompt and j2ee/home is your current directory.
Issue the following command to start OC4J:
% java -jar oc4j.jar [options]
See the Oracle Application Server Containers for J2EE Stand Alone User's Guide for a discussion of OC4J command-line options.
Issue the following command to stop OC4J:
% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port adminuser adminpassword -shutdown
For the admin.jar -shutdown command, note the following:
j2ee/home/config/rmi.xml file, where there will be an entry such as the following:
<rmi-server port="23791" host="[ALL]">
adminuser and adminpassword.
The following sections discuss features and configuration of the OC4J default application and default Web application. Some of the OC4J standalone deployment scenarios described later will use these features.
|
Note: Use of the default application and default Web application for deployment during testing is a useful OC4J convenience feature, but is considered to be an expert mode because you are manually placing application files and sometimes manually updating configuration files. See "Using Oracle Deployment Tools Versus Expert Modes". |
OC4J is installed with a default configuration that includes a default application (also known as the global application). The default application is, by default, the parent of all other J2EE applications in OC4J.
In OC4J, a Web application must be contained within a parent J2EE application. Usually, a WAR file is deployed within an EAR file that defines the parent J2EE application. If you want to deploy an independent WAR file, you can deploy to the OC4J default application instead. By default, the OC4J server.xml file specifies the location and name of the global application descriptor that defines the default application.
In a typical OC4J installation, the default application contains a default Web application. The name and root directory path of the default Web application are specified in the global application descriptor, and the default Web application is bound to a Web site through the http-web-site.xml file for OC4J standalone (default-web-site.xml in Oracle Application Server). In OC4J standalone, the default context path for the default Web application is "/".
Also by default in OC4J standalone, the root directory of the default Web application is j2ee/home/default-web-app. To deploy to the default Web application, place your JSP pages and class files under this directory in the standard Web application directory structure: static pages and JSP pages at the top level, servlet classes under j2ee/home/default-web-app/WEB-INF/classes, and library JAR files in j2ee/home/default-web-app/WEB-INF/lib. Also see "Using a Web Application Directory Structure in the Default Web Application".
This section details the default configurations for the OC4J default application and default Web application.
In server.xml, the <global-application> element specifies the OC4J default application. The name attribute specifies its name, and the path attribute specifies what to use as the OC4J global application descriptor:
<application-server ... > ... <global-application name="default" path="application.xml" /> ... </application-server>
The specified descriptor for the default application (or global application), application.xml, specifies the name and root directory path of the default Web application, which is contained in the default application:
<orion-application ... > ... <web-module id="defaultWebApp" path="../../home/default-web-app" /> ... </orion-application>
To deploy to the default Web application, place your files under this directory according to the standard Web application structure.
By default, the default Web application is bound to a Web site in the http-web-site.xml file for OC4J standalone (default-web-site.xml in Oracle Application Server).
Although most OC4J Web applications are bound to a Web site through <web-app> subelements of a <web-site> element in the Web site XML file, the default Web application is instead configured through the <default-web-app> subelement of <web-site>.
In OC4J standalone, the default context path of the default Web application is "/", without a root attribute being required. Here is an example:
<web-site ... > ... <default-web-app application="default" name="defaultWebApp" load-on-startup="true" shared="false" /> ... </web-site>
See "Configuration for Web Site XML Files" for detailed information about elements and attributes of Web site XML files.
The following sections describe the process of deploying an EAR file in OC4J standalone using the admin.jar utility.
This discussion assumes that if you modify your code, you would then repackage it and redeploy it.
After you have packaged your application into an EAR file, you can use the OC4J admin.jar utility to deploy it, using the following syntax:
% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port adminuser adminpassword -deploy -file path/filename.ear -deploymentName appname
This command uses RMI to communicate with OC4J. Note the following:
adminuser and adminpassword.
-file, specify the path to the EAR file, including the file name.
-deploymentName, specify the desired application name, by convention the same as the EAR file name without the .ear extension.
By default, a deployment results in the following:
j2ee/home/applications directory. This directory is set as the default through the application-directory attribute of the <application-server> element in the server.xml file.
j2ee/home/applications directory.
orion-application.xml and orion-web.xml for a Web application in an EAR file--are copied or generated under the j2ee/home/application-deployments directory. This directory is set as the default through the deployment-directory attribute of the <application-server> element in the server.xml file. These descriptors are copied from the EAR file if they exist there; otherwise, OC4J generates them.
<application> element is added to the server.xml file. This element specifies the application name, according to the -deploymentName setting in admin.jar, and specifies the path to where the EAR file was deployed, j2ee/home/applications by default.
See "Sample Deployment" for an example.
After you have deployed your application, you can use the OC4J admin.jar utility to bind the associated Web application to a Web site:
% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port adminuser adminpassword -bindWebApp appname webappname websitename contextpath
As with the -deploy command, the -bindWebApp command uses RMI to communicate with OC4J. Note the following:
adminuser and adminpassword.
appname is the application name, according to the -deploymentName setting when you deployed it.
webappname is the name of the Web application. This is the WAR file name without the .war extension.
websitename is indicated by the Web site XML file name for the desired site, without the .xml extension (for example, http-web-site in OC4J standalone).
As a result of this command, a <web-app> element is added to the specified Web site XML file, indicating the application name, the Web application name, and the context path.
See the next section, "Sample Deployment", for an example.
This example shows the result of deploying the utility.ear file shown in "EAR File and WAR File Structures", then binding its Web application. Here are the admin.jar commands, assuming % is the system prompt, j2ee/home is the current directory, and the EAR file is in j2ee/home/demo:
% java -jar admin.jar ormi://myhost:23791 admin welcome -deploy -file demo/utility.ear -deploymentName utility % java -jar admin.jar ormi://myhost:23791 admin welcome -bindWebApp utility utility_web http-web-site /utilroot
Note the following:
myhost; the port setting is 23791 in j2ee/home/config/rmi.xml.
admin and the password is welcome.
utility.ear is utility_web, based on the WAR file name, utility_web.war.
-bindWebApp command is to bind utility_web to the Web site defined by j2ee/home/config/http-web-site.xml. This assumes the following entry is in the server.xml file, as is the case by default:
<web-site path="http-web-site.xml" />
/utilroot".
The -deploy command results in the following entry in server.xml, as a subelement of the top-level <application-server> element:
<application name="utility" path="../applications/utility.ear" auto-start="true" />
The auto-start attribute specifies whether this application should be automatically restarted each time OC4J is restarted.
The -bindWebApp command results in the following entry in http-web-site.xml, as a subelement of the top-level <web-site> element:
<web-app application="utility" name="utility_web" root="/utilroot" load-on-startup="false" max-inactivity-time="no shutdown" shared="false" />
(See "Element Descriptions for Web Site XML Files" for information about the load-on-startup, max-inactivity-time, and shared attributes.)
After the deployment of utility.ear, the directory structure for key files is as follows, assuming default settings for the target directories:
j2ee/home/ application-deployments/ utility/ orion-application.xml utility_web/ orion-web.xml applications/ utility.ear utility/ utility_web.war META-INF/ application.xml utility_web/ index.html META-INF/ WEB-INF/ web.xml classes/ TestStatusServlet.class
The server.xml and http-web-site.xml files are in the j2ee/home/config directory.
If orion-application.xml and orion-web.xml exist in the EAR file, they are copied from there into the directories shown above. Otherwise, OC4J generates them into the directories shown above, using default settings from the corresponding OC4J global descriptors and J2EE descriptors.
The deployment in the preceding section uses the following descriptors. Passages of particular interest to servlet developers are marked in bold type.
The standard application.xml descriptor is supplied by the developer. Some IDEs, such as Oracle JDeveloper, will create this for you.
<?xml version="1.0" ?> <!DOCTYPE application (View Source for full doctype...)> <application> <display-name>Web Services Demo</display-name> <module> <web> <web-uri>utility_web.war</web-uri> <context-root>/j2ee/utility</context-root> </web> </module> </application>
Remember that the <context-root> element here is overridden by the root attribute of the <web-app> element in the Web site XML file.
The standard web.xml descriptor is supplied by the developer.
<?xml version="1.0" ?> <!DOCTYPE web-app (View Source for full doctype...)> <web-app> <display-name>Web Services Example</display-name> <description>A few examples of web service publication</description> <welcome-file-list> <welcome-file>index.html</welcome-file> </welcome-file-list> <servlet> <servlet-name>TestStatus</servlet-name> <servlet-class>TestStatusServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>TestStatus</servlet-name> <url-pattern>/TestStatusServlet</url-pattern> </servlet-mapping> </web-app>
Because the orion-application.xml descriptor is not included in the EAR file in this example, it is generated by OC4J. Most of the file is omitted here, but note that the <web-module> element mirrors the entry in the application.xml file.
<?xml version="1.0" ?> <!DOCTYPE orion-application (View Source for full doctype...)> <orion-application deployment-version="9.0.4.0.0" default-data-source="jdbc/OracleDS" treat-zero-as-null="true" autocreate-tables="true" autodelete-tables="false"> ... <web-module id="utility_web" path="utility_web.war" /> ... </orion-application>
Because the orion-web.xml descriptor is not included in the WAR file (within the EAR file) in this example, it is generated by OC4J. It is not shown here because there are no entries specific to the example.
Given the information for the sample deployment in the preceding sections, in which /utilroot is specified as the context path in the admin.jar -bindWebApp command and /TestStatusServlet is specified as the servlet path in web.xml, you invoke the application as follows:
http://host:port/utilroot/TestStatusServlet
Instead of deploying an EAR file, you can manually deploy the file structure and then update the server.xml and Web site XML files. This is an expert mode. (See "Using Oracle Deployment Tools Versus Expert Modes".)
Look again at "Sample Deployment", but assume that you manually create the j2ee/home/applications/utility directory and manually populate the application directory structure underneath, as follows.
j2ee/home/applications/utility/ META-INF/ application.xml utility_web/ index.html META-INF/ WEB-INF/ web.xml classes/ TestStatusServlet.class
Further assume that you update the server.xml file as follows:
<application name="utility" path="../applications/utility" auto-start="true" />
And you update the http-web-site.xml file as follows:
<web-app application="utility" name="utility_web" root="/utilroot" load-on-startup="false" max-inactivity-time="no shutdown" shared="false" />
Note that the path attribute in the <application> element in server.xml is "../applications/utility" instead of "../applications/utility.ear". This is because there is no EAR file, just the directory structure under the utility directory.
By default in OC4J standalone, when you update server.xml, OC4J detects the change, deploys the application, and copies or generates the orion-web.xml file and orion-application.xml file under the application-deployments directory as follows:
j2ee/home/ application-deployments/ utility/ orion-application.xml utility_web/ orion-web.xml
However, if OC4J update-checking is disabled, you must manually inform OC4J of your configuration updates, using the admin.jar -updateConfig option. Checking is enabled through the server.xml check-for-updates flag. See "Key OC4J Flags for Development".
"Deploying an EAR File to OC4J Standalone" discusses using the admin.jar utility to deploy an EAR file, including a WAR file within an EAR file for a Web module. For convenience during testing, it is also possible to manually deploy an independent WAR file, using the OC4J default application as the containing application. (A Web application must always be part of a parent J2EE application in OC4J.) This is an expert mode. See "Using Oracle Deployment Tools Versus Expert Modes".
See "OC4J Default Application and Default Web Application" for background information.
Use the following steps to deploy an independent WAR file to the OC4J default application:
application.xml file to add a <web-module> element to specify the Web application name and the location of the WAR file.
http-web-site.xml in OC4J standalone, to add a <web-app> element to bind the Web application to the Web site.
The following example illustrates deployment of a WAR file to the default application.
This example shows entries in server.xml, the Web site XML file, and the OC4J global application.xml file for a Web application mywebmod1 within the OC4J default application. Note the following:
path attribute of the <web-site> element in server.xml specifies the path and name of the Web site XML file, http-web-site.xml in this example.
name attribute of the <global-application> element in server.xml specifies the name of the OC4J default application and corresponds to the application attribute of the <web-app> element in http-web-site.xml.
path attribute of the <global-application> element in server.xml points to the OC4J global application.xml file.
name attribute of the <web-app> element in http-web-site.xml indicates a Web application, mywebmod1, within the OC4J default application and corresponds to the id attribute of a <web-module> element in the OC4J global application.xml file. Both of these attributes typically correspond to the WAR file name without the .war extension.
application.xml file must specify the name and location of the WAR file, through the path attribute of the <web-module> element, because there is no containing EAR file.
The following entries are in the server.xml file (no changes required):
<application-server ... > ... <global-application name="default" path="application.xml" /> ... <web-site path="http-web-site.xml" /> ... </application-server>
Place the bold entry into the Web site XML file, http-web-site.xml:
<web-site protocol="http" port="8888" display-name="HTTP Web Site" host="[ALL]" log-request-info="false" secure="false"> ... <web-app application="default" name="mywebmod1" root="/someUrl" load-on-startup="false" max-inactivity-time="no shutdown" shared="false" /> ... </web-site>
(See "Element Descriptions for Web Site XML Files" for information about the <web-site> and <web-app> attributes shown here.)
Place the bold entry into the OC4J global application.xml file:
<orion-application ... > ... <web-module id="mywebmod1" path="../myhome/mywebmod1.war" /> ... </orion-application>
|
Note:
By default in OC4J standalone, editing the global
However, automatic detection of configuration changes depends on the |
The previous section discusses how to deploy an independent WAR file to the OC4J default application. Alternatively, you can manually set up the J2EE Web application directory structure instead of using a WAR file. Again, this involves the OC4J default application. The simplest way to do this is to also use the OC4J default Web application, but you can optionally define a new Web application under the default application. See "OC4J Default Application and Default Web Application" for background information.
Each of these scenarios is an expert mode. (See "Using Oracle Deployment Tools Versus Expert Modes".) The following sections discuss them in detail:
By default, OC4J comes configured with a default application, and a default Web application contained in the default application. To use the default Web application to contain your test files, put them in the standard Web application directory structure under the j2ee/home/default-web-app directory (by default).
To verify the configuration, look in the server.xml file. First, you should see the following entry to define the name and specify the application descriptor for the default application:
<global-application name="default" path="application.xml" />
You should also see the following entry to specify the Web site XML file:
<web-site path="./http-web-site.xml" />
Next, look in the OC4J global application.xml descriptor. You should see the following entry to define the default Web application name and specify its root directory:
<web-module id="defaultWebApp" path="../../home/default-web-app" />
Finally, look in the Web site XML file that is indicated in server.xml (http-web-site.xml, by default, in OC4J standalone). You should see the following entry to define defaultWebApp as the default Web application for the Web site. As noted earlier, "/" is the context path for the default Web application in OC4J standalone, without the necessity of a root attribute in the <default-web-app> element.
<default-web-app application="default" name="defaultWebApp" />
Given this configuration, you can deploy your files as in the following example. No further action is necessary before you invoke the servlet.
j2ee/home/default-web-app/ index.html WEB-INF/ web.xml classes/ TestServlet.class
In the previous section, the OC4J default Web application, defaultWebApp, is used to deploy a Web application directory structure. Alternatively, you can define some other Web application that will also be contained in the OC4J default application. This is useful if you want functionality similar to that of the default Web application, but deploying to a clean directory. This section describes the steps to define a Web application, myDefaultWebApp, within the default application.
First, add a <web-module> element to the OC4J global application.xml file, as in the following example. This defines the name and specifies the root directory of a new OC4J Web application. The entry for the OC4J default Web application is also shown for comparison.
<web-module id="defaultWebApp" path="../../home/default-web-app" /> <web-module id="myDefaultWebApp" path="../../home/my-default-web-app" />
Next, add a <web-app> element to the Web site XML file, http-web-site.xml, as in the following example. This ties the Web application to a context path. The <default-web-app> element for the OC4J default Web application is also shown for comparison.
<default-web-app application="default" name="defaultWebApp" /> <web-app application="default" name="myDefaultWebApp" root="/mydefroot" />
Given this configuration, you can deploy your files as in the following example. No further action is necessary before you invoke the servlet.
j2ee/home/my-default-web-app/ index.html WEB-INF/ web.xml classes/ TestServlet.class
During testing, you will presumably have to modify and redeploy your application. The following sections describe undeployment and redeployment features for OC4J standalone:
If you are finished using an application, you can use admin.jar to undeploy it as follows:
% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port adminuser adminpassword -undeploy appname
This removes associated entries in server.xml and the Web site XML file, as well as removing all directories and files that were created and copied. See "Starting and Stopping OC4J Standalone" for information about the ORMI port. See "Setting Up an Administrative User and Password" for information about adminuser and adminpassword.
To undeploy the utility.ear application shown in "Sample Deployment", for example:
% java -jar admin.jar ormi://myhost:23791 admin welcome -undeploy utility
As when you initially deploy an application to OC4J standalone, use the admin.jar -deploy command to redeploy it. There is no difference to the user. The utility automatically takes care of effectively undeploying it first so that you will have a clean start. See "Deploying an EAR File to OC4J Standalone" for information about the -deploy command.
Before redeploying, you must repackage your EAR file to pick up any updated files. If you updated OC4J descriptors on the server, such as orion-web.xml and orion-application.xml, and want to keep the changes, you must include these in the EAR file as well. Previously copied or generated OC4J descriptors are lost if there has been any update to the EAR file.
Deploying an independent WAR file to the OC4J default application is described in "Deploying an Independent WAR File to OC4J Standalone". If you want to redeploy, you must reverse the steps you took to deploy, repackage the WAR file, and repeat the deployment steps. This is an expert mode. (See "Using Oracle Deployment Tools Versus Expert Modes".)
To summarize:
application.xml file and the http-web-site.xml file (or other Web site XML file).
orion-web.xml that you want to save, then include it in the WAR file.
application.xml and http-web-site.xml. Updating application.xml causes OC4J to unpack the WAR file and copy or generate the orion-web.xml file as during the initial deployment.
Depending on OC4J polling, which is enabled by default in OC4J standalone, there are several ways to trigger a redeployment of your application when you modify files in place on the server. (This is an expert mode. See "Using Oracle Deployment Tools Versus Expert Modes".)
/WEB-INF/classes.
If you update a servlet .class file under /WEB-INF/classes, the servlet and its dependency classes are reloaded, and the Web application is redeployed, upon the next request. This is regardless of whether OC4J polling is enabled.
|
Notes:
|
If you modify web.xml while polling is enabled, the Web application is redeployed the next time the OC4J task manager runs, which by default is once each second. Servlets and dependency classes in the Web application are reloaded upon the next request.
If you modify application.xml while polling is enabled, the J2EE application is redeployed. Servlets and dependency classes in the Web application are reloaded upon the next request.
/WEB-INF/lib.
If you modify a JAR file in /WEB-INF/lib while polling is enabled, the Web application is redeployed the next time the OC4J task manager runs. Servlets and dependency classes in the Web application are reloaded upon the next request.
development flag to "true".
The development flag is an attribute of the <orion-web-app> element in global-web-application.xml and orion-web.xml. If development is set to "true", then the OC4J server checks a particular directory (the application /WEB-INF/classes directory by default) for updates to servlet source files. If a source file has changed since the last request, then OC4J will, upon the next request, recompile the servlet, redeploy the Web application, and reload the servlet and any dependency classes. See the description of development under "Element Descriptions for global-web-application.xml and orion-web.xml" for further information.
main_mode flag to "recompile".
See the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information.
In OC4J standalone, polling is controlled through the server.xml check-for-updates flag, which is set to "true" by default. Alternatively, you can use the admin.jar -updateConfig option to trigger one-time polling. See "Key OC4J Flags for Development".
|
Notes: Be aware of a few points in any of the preceding scenarios:
|
This section considers deployment and redeployment scenarios to OC4J in an Oracle Application Server environment.
In Oracle Application Server, you must use either Enterprise Manager or parallel commands in the dcmctl command-line utility for starting, stopping, configuring, and deploying applications. Both of these tools are coordinated with the Oracle Application Server Distributed Configuration Management subsystem (DCM). You cannot use the OC4J standalone utility, admin.jar, for managing OC4J instances in an Oracle Application Server instance. Also, do not manually update configuration files in Oracle Application Server. (See "Using Oracle Deployment Tools Versus Expert Modes".)
The following sections are included here:
The Enterprise Manager pages for deploying and configuring Web modules are discussed in Chapter 7, "Configuration with Enterprise Manager". See the Oracle Application Server Containers for J2EE User's Guide for further information about using Enterprise Manager or the dcmctl command-line utility with OC4J.
The deployment scenarios discussed earlier in this chapter, using admin.jar or a manual deployment of application files, do not apply in an Oracle Application Server environment. Enterprise Manager includes pages for deploying an EAR file or a WAR file, as described in "Application Server Control Deploy Application (EAR) Page" and "Application Server Control Deploy Web Application (WAR) Page". In Oracle Application Server, do not manually deploy EAR or WAR files, or deploy loose files, as described in some of the scenarios for OC4J standalone.
In Oracle Application Server, issues of copying EAR or WAR files, unpacking these files into a directory structure, and copying or generating the OC4J descriptors (such as orion-web.xml and orion-application.xml) are generally handled automatically and transparently through Enterprise Manager.
Deployment to Oracle Application Server through Enterprise Manager or dcmctl automatically registers Web applications with Oracle HTTP Server and results in a new mount point in the mod_oc4j.conf file. A URL mapping you specify in Enterprise Manager, such as "/mypath/myapp", defines the mount point. Mount points determine which URL requests are routed from Oracle HTTP Server to OC4J for processing. In this case, any URL request starting with "/mypath/myapp" (after the host and port) is handed off to OC4J.
There are a number of Enterprise Manager pages, also described in Chapter 7, for configuring servlet or Web site parameters. Manipulating settings in these pages results in appropriate configuration updates being made automatically. The configuration files discussed earlier in this chapter are used by OC4J in Oracle Application Server, but this is largely transparent and there are additional logistics to consider:
For these reasons, it is imperative that you not attempt to update configuration manually in Oracle Application Server.
If for some reason you must modify configuration files without going through Enterprise Manager, you must run a dcmctl update command to inform DCM of the changes. This will affect all instances of OC4J managed by DCM and should be avoided.
OPMN, DCM, and the dcmctl tool are documented in the Oracle Application Server 10g Administrator's Guide. This guide and Oracle Enterprise Manager Concepts provide further information about Enterprise Manager as well.
The default Web application in OC4J standalone is of potential use during development and is discussed in "OC4J Default Application and Default Web Application". OC4J has a default Web application in an Oracle Application Server environment as well, but it is not for developer use.
In Oracle Application Server, there is just one Web site, and the root namespace is owned by Oracle HTTP Server, not OC4J. The concept of an OC4J default Web application in an Oracle Application Server environment is not sensible in the way that it is for OC4J standalone, in which OC4J itself owns any Web sites. Furthermore, in OC4J standalone, the default Web application is used by manipulating files manually, which is not appropriate in Oracle Application Server.
In Oracle Application Server, as noted elsewhere, routing from Oracle HTTP Server to OC4J is accomplished through mount points in the mod_oc4j.conf file. Each time you deploy an application to OC4J in Oracle Application Server (as described in "Application Server Control Deploy Application (EAR) Page" and "Application Server Control Deploy Web Application (WAR) Page"), the URL that you specify as the context path results in the specification of that URL as another mount point.
One default OC4J mount point and context path, /j2ee, with a default Web application, defaultWebApp, exists for OC4J system use only. For example, if a request has a URL pattern that matches an OC4J mount point and, therefore, results in routing to OC4J, but the specified Web application cannot be found, OC4J uses this default Web application to print an error message. This context path and default Web application are specified in the <default-web-app> element in default-web-site.xml. This element is required, but is not of direct use to developers.
Oracle Enterprise Manager includes features to undeploy or redeploy an application. The following sections introduce these features:
If you are finished using a J2EE application in Oracle Application Server, you can undeploy it through the Application Server Control OC4J Applications Page in Enterprise Manager. Select the application from the applications list (using the corresponding radio button) and click the Undeploy button. This removes all directories and files that were created and copied, and updates the server configuration appropriately.
See "Application Server Control OC4J Applications Page" to see what the page looks like and for further information.
You can redeploy a J2EE application in Oracle Application Server through the Application Server Control OC4J Applications Page in Enterprise Manager. Select the application from the applications list (using the corresponding radio button) and click the Redeploy button. You will be prompted for the path to the EAR file.
See "Application Server Control OC4J Applications Page" to see what the page looks like and for further information.
During redeployment, if you have not changed the EAR file since the previous deployment, then server configuration settings are maintained from the previous deployment. This is particularly relevant for settings in the OC4J descriptors, such as orion-application.xml and orion-web.xml, given that standard configuration, such as through application.xml and web.xml, is presumably in your EAR file anyway.
If you have changed the EAR file, however, then the previous server configuration is discarded. It is replaced with information from the EAR file, such as from the OC4J descriptors (if present) and applicable default values. In this scenario, if you have made OC4J-specific configuration changes on the server, you should make the same changes to the OC4J descriptors in the EAR file in order to keep those changes.
After redeployment, you can check the OC4J servlet and Web site configuration pages, described in Chapter 7, "Configuration with Enterprise Manager", to verify whether desired configurations settings have been maintained.
|
 Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|