Oracle WAR Deployment

This document describes Web archive (WAR) deployment to the Oracle9i (or 8.1.7) database for installation and execution of Web applications in the Oracle Servlet Engine. The Oracle implementation follows the general WAR deployment standard, but there are special considerations and logistics for execution in the database. Oracle provides various utilities to help with these logistics. The following topics are discussed here:

Additional References

This document assumes knowledge of servlets in general and the Oracle Servlet Engine in particular. Readers can refer to the following for background information:

Sun Microsystems Java Servlet Specification, Version 2.2, for information about Web applications, servlets, WAR files, and other related topics

This specification is available at the following Web site:
```
http://java.sun.com/products/servlet/
```
Oracle Servlet Engine User's Guide, which describes how to use the Oracle database Web server and servlet environment
Oracle JavaServer Pages Developer's Guide and Reference, which describes Oracle's JavaServer Pages (JSP) implementation
Oracle9i (or 8i) Java Tools Reference, which documents tools, such as loadjava and the session shell, that are provided with the Oracle9i database.

Standard Web Applications and Hierarchies

A Web application is a collection of components that are bundled and run as an integrated unit. Web application components can include HTML pages (or other static components such as images or sounds), servlets, JavaServer Pages (JSP pages), JavaBeans, Java utility classes, and other resources. (It is typical for libraries of classes and resources to be packaged in JAR files.) Such an application can be run in any standard "container" (engine) from any vendor. There must also be some sort of top-level meta information to tie all the components together.

This section briefly summarizes the standard concepts of Web applications and Web archive (WAR) files, which provide the mechanism for deploying a Web application to a target environment. The following topics are introduced:

Web Application Servlet Contexts

Each Web application is represented by a servlet context, which is an instance of a class that implements the standard javax.servlet.ServletContext interface. A servlet context maintains application state information; you can think of it as an "application container".

In general (not considering the Oracle9i JVM in particular), this would be state information for all instances of the various application components running within a given Java virtual machine. This is similar to the way a session maintains state information for a single client on the server; however, in most environments a servlet context is not specific to any single user and can potentially handle multiple clients.

The model differs in the Oracle9i JVM, however, where there is just a single user for each JVM instance. In this case, any particular servlet context instance is managing state information for just a single instance of the application and for just a single user.

Web Application Hierarchies

A Web application has a hierarchy that is rooted at a specific directory path within a Web server. As described in the servlet 2.2 specification, this hierarchy can exist in a file system, an archive file (such as a WAR file, described in "Web Application Deployment and WAR Files"), or some other form for deployment.

When you create a servlet context for an application, you associate its root location, or document root, with a context path (a name that you choose), and the context path becomes part of the URL to access the application.

When you publish an application component (such as a servlet or JSP page), which is a process to make the component available for execution, you typically specify a virtual path (or servlet path) which determines the rest of the URL to access the component. The virtual path is typically in accordance with the location of the component within the application hierarchy.

For example, if a customer service application on host www.corphomepage.com has a context path of custservice, then all requests using URLs that start with the following prefix will be routed to the servlet context that represents the customer service application:

http://www.corphomepage.com/custservice

An index.html file in the application document root directory, for example, would be served as a result of a request to the following URL (and you can say that index.html is the virtual path):

www.corphomepage.com/custservice/index.html

If a JSP page, mypage.jsp, has a virtual path of jsp/mypage.jsp (and so presumably, but not necessarily, is in a jsp subdirectory under the document root directory), you would access it as follows:

www.corphomepage.com/custservice/jsp/mypage.jsp

According to the servlet 2.2 specification, there is a WEB-INF subdirectory of the document root. This directory contains the application deployment descriptor (described in the next section, "Web Application Deployment Descriptors"), and its subdirectories contain any components of the application other than document pages to be served to the client. For example, components under the WEB-INF directory might include servlets, JavaBeans, and utility classes. Components outside the WEB-INF directory include HTML pages and perhaps JSP pages.

Following are the contents of the WEB-INF directory, according to the servlet 2.2 specification:

/WEB-INF/web.xml file (the deployment descriptor)
/WEB-INF/classes directory (for .class files for servlet, JavaBean, and utility classes)
/WEB-INF/lib directory (for JAR files containing libraries of Java .class files and resources)

Here is a sample hierarchy for a Web application (in a WAR file):

/index.html
/welcome.jsp
/images/logo.gif
/WEB-INF/web.xml
/WEB-INF/lib/beans.jar
/WEB-INF/classes/com/custservice/servlets/CSLogServlet.class

Web Application Deployment Descriptors

The servlet 2.2 specification provides a mechanism known as a Web application deployment descriptor to specify the elements and configuration of an application. The deployment descriptor is an XML file, named web.xml by convention.

The web.xml file includes information and settings for such items as servlet context configuration parameters, session configuration parameters, servlet and JSP definitions, servlet and JSP mappings, MIME type mappings, error pages, and security.

The DTD that defines XML grammar for a web.xml file is included in Chapter 13 of the Sun Microsystems Java Servlet Specification, Version 2.2.

Oracle provides a local copy of this DTD and uses it for validation by default if you do not specify a DTD in the web.xml DOCTYPE declaration.

Following is a basic example of a web.xml file (taken from the servlet 2.2 specification):

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
   <display-name>A Simple Application</display-name>
   <context-param>
      <param-name>Webmaster</param-name>
      <param-value>webmaster@mycorp.com</param-value>
   </context-param>
   <servlet>
      <servlet-name>catalog</servlet-name>
      <servlet-class>com.mycorp.CatalogServlet</servlet-class>
      <init-param>
         <param-name>catalog</param-name>
         <param-value>Spring</param-value>
      </init-param>
   </servlet>
   <servlet-mapping>
      <servlet-name>catalog</servlet-name>
      <url-pattern>/catalog/*</url-pattern>
   </servlet-mapping>
   <session-config>
      <session-timeout>30</session-timeout>
   </session-config>
   <mime-mapping>
      <extension>pdf</extension>
      <mime-type>application/pdf</mime-type>
   </mime-mapping>
   <welcome-file-list>
      <welcome-file>index.jsp</welcome-file>
      <welcome-file>index.html</welcome-file>
      <welcome-file>index.htm</welcome-file>
   <welcome-file-list>
   <error-page>
      <error-code>404</error-code>
      <location>/404.html</location>
   </error-page>
</web-app>

As described in "Distributable Applications and the Oracle Servlet Engine", a Web application must be designed as distributable to run in the Oracle Servlet Engine. This is specified in the web.xml file through the presence of a distributable element, specified as follows in the web.xml DTD:

<!ELEMENT distributable EMPTY>

For example:

<distributable />

Note:
According to the servlet 2.2 specification, a web.xml file can use the env-entry, ejb-ref, and resource-ref elements to refer application components to external resources and EJBs without explicit knowledge of their location or organization. The ejb-ref element, for example, would contain information to help a servlet find the home interfaces of an EJB. For more information, see the Sun Microsystems Java Servlet Specification, Version 2.2.
The Oracle WAR implementation for the post-8.1.7 release does not yet support these tags, however. See "Current Restrictions" for more information.

Web Application Deployment and WAR Files

A Web archive (WAR) file is a single file that contains all the components of a Web application and is structured according to the hierarchy of these components. It is the vehicle for deploying a Web application to the target environment where the application is intended to run.

At the target system, a deployment tool will unpackage the WAR file and place the application components according to the hierarchy specified by the WAR file structure. (The Oracle WAR deployment tool is described in "Overview of the Oracle WAR Deployment Tool".)

WAR files are identified by the .war file name extension and can be created using any standard Java archive (JAR) tool that allows any or all of the application components to be signed.

Overview of WAR Deployment to the Oracle9i Database

This section provides an overview of details, considerations, and mechanisms in deploying and running a Web application in the Oracle9i database. This discussion includes the following topics:

Distributable Applications and the Oracle Servlet Engine

The Sun Microsystems servlet 2.2 specification introduces the concept of distributable Web applications, where application components can be deployed across multiple Java virtual machines (running on either the same host or different hosts).

With the scalable nature of the Oracle Servlet Engine (OSE), it is typical for many client sessions to be simultaneously active and accessing the same Web application at any given time, with each client session executing in its own "virtual" JVM. This means that a Web application deployed to run in OSE must be distributable.

For an application to be distributable you must take the following steps:

Follow a more restrictive set of rules during development of the application, as detailed throughout the servlet 2.2 specification.
Mark the application as distributable using the distributable tag in the application deployment descriptor (web.xml, discussed in "Web Application Deployment Descriptors").

When you deploy an application to the Oracle9i database, the Oracle WAR deployment tool will check the application deployment descriptor and issue a warning if the application is not marked distributable. (Deployment will continue despite the warning.) You should use the warning as a reminder to check that your application does not make assumptions about running in a single JVM instance. Update the deployment descriptor to mark the application distributable after you are satisfied with your analysis and have made the necessary changes.

Overview of the Oracle Auxiliary Descriptor

The standard Web application deployment descriptor file, web.xml, is described earlier, in "Web Application Deployment Descriptors". This file is a vehicle for standard configuration instructions for a Web application and is portable to any runtime environment supporting the servlet 2.2 specification. However, web.xml cannot provide all the information necessary to deploy an application to a particular servlet container, because each vendor is free to extend standard functionality with their own set of features. Also, some aspects of deployment may be intentionally left out of the standard web.xml descriptor. The servlet 2.2 specification therefore suggests that each vendor provide an additional descriptor file for configuration of features unique to that vendor's runtime environment.

Oracle specifies and supports such an additional descriptor, known as the Oracle auxiliary descriptor. Like the web.xml deployment descriptor, the auxiliary descriptor is in XML format. Oracle provides a DTD to specify supported elements and attributes. You can choose any file name for the auxiliary descriptor, but the .xml file name extension is recommended.

See "Oracle Auxiliary Descriptor" for more information.

Overview of the Oracle WAR Deployment Tool

Oracle provides a tool that deploys a Web application to the Oracle9i database for execution in the Oracle Servlet Engine. The WAR deployment tool requires that the application be packaged in a WAR file, and can be invoked in any of the following ways:

from the server, by using the Oracle session shell deploywar command (requires you to first manually upload the WAR file and auxiliary descriptor)
from the server, from Java code or a PL/SQL call specification through the oracle.mts.http.deployment.DeployWar.main(String[] args) method (this also requires you to first manually upload the WAR file and auxiliary descriptor)
from any HTTP client, by invoking the Oracle deployment servlet (presuming the oracle.aurora.mts.http.deployment.DeploymentServlet servlet class has been published to the Oracle Servlet Engine in advance, which occurs as part of Oracle WAR deployment installation)

(A special form, deploywar.htm, is provided as a convenient way to invoke the deployment servlet.)
from an Oracle client (any machine with an Oracle client installation), through a client-side deployment script (deploywar on UNIX or deploywar.bat on Windows NT)
from a non-Oracle client (any machine without an Oracle client installation), by executing the WAR deployment tool wrapper, HttpClientWrapper, directly from Java

Note:
The client-side scripts and client-side wrapper are just convenient front ends that invoke the deployment servlet.

Each of these ways to invoke the Oracle WAR deployment tool is discussed in more detail later, in "Vehicles for Invoking the Oracle WAR Deployment Tool".

When you invoke the WAR deployment tool, it performs a number of automated steps, presuming that your web.xml file and Oracle auxiliary descriptor are configured in some appropriate way. These steps include the following:

loading of the deployment descriptors (web.xml and the auxiliary descriptor)
file loading from the WAR file, using the Oracle loadjava utility

The loadjava utility loads Java classes, Java resources, and JSP pages into the Oracle9i database, including JSP translation where applicable. It also copies static pages of the application to the OSE document root directory.
creation of a servlet context for the application
publishing of application components (servlets and JSP pages)
securing the application (implementing any URI protections and login/password requirements, assuming appropriate OSE security preparations were made)

These steps are described later, in "Oracle WAR Deployment Tool Functionality".

Note:
While the Oracle WAR deployment tool will translate JSP pages (.jsp and .sqljsp files), it will not translate or compile .sqlj or .java files. (The servlet 2.2 specification assumes only compiled classes are being loaded.) Any .java or .sqlj files in the WAR file will be treated as Java resources and simply loaded as is. You will have to perform any server-side translation or compilation manually.

Security Preparations

If an application being deployed defines any security restrictions, you will need to make (or verify) appropriate preparations before deployment:

Create the necessary security realm.
Create users and groups for role names.
Create a group for all realm users (if necessary).
Decide what principals (users or groups) in OSE will correspond to role names in any security-role elements in the web.xml file. (This is only necessary for roles involved in security constraints.)

For background information about OSE security, see the Oracle Servlet Engine User's Guide.

The application developer must provide a description of security roles and different authorization arrangements that are required. The appearance of login-config, security-role, or security-constraint elements in the web.xml file indicates that the application has security features.

Create Security Realms Prior to Deployment

All HTTP security protections for an application apply within one HTTP security realm. The realm is specified in the login-config element of the web.xml file or Oracle auxiliary descriptor. Security roles and virtual path protections should be found and established within this HTTP security realm.

Before deploying the WAR file, it is your responsibility to make sure the HTTP security realm for the application has been created in OSE. You can accomplish this using the Oracle9i session shell realm publish command, as in the following example ($ is the session shell prompt):

$ realm publish -w someService -add catalogRealm -type RDBMS

For more information about the realm publish command, see the Oracle9i (or 8i) Java Tools Reference.

The login-config element includes a subelement that provides the realm name, as in the following example:

<login-config> 
  <auth-method>basic</auth-method> 
  <realm-name>catalogRealm</realm-name> 
</login-config>

The HTTP security realm name specified in the realm-name subelement (catalogRealm in this example) must match the name of the realm that was created prior to deployment. This example also specifies that the application will be authenticated by the Oracle Servlet Engine with the basic authentication method.

The login-config element is optional in the web.xml file and can be specified in the Oracle auxiliary descriptor instead, which is useful if you may be deploying the application to different environments and do not want to change the web.xml file each time. The value in the Oracle auxiliary descriptor takes precedence over the value in web.xml.

If the login-config element is not specified in either descriptor, but the web.xml file contains some security constraints, the Oracle WAR deployment tool will issue an error. (It is impossible to configure any security constraints without knowing the security realm and authentication method.)

Create Users and Groups for Role Names Prior to Deployment

The Oracle WAR deployment tool will protect Web resources according to directives indicated by security-constraint elements in the web.xml file. These elements are structured as in the following example:

<security-constraint>
    <web-resource-collection>
      ...
    </web-resource-collection>
    <auth-constraint>
       <role-name>catalogUser</role-name>
       <role-name>catalogBuilder</role-name>
    </auth-constraint>
    <user-data-constraint>
      ...
    </user-data-constraint>
</security-constraint>

Web resources (such as the list of relative virtual paths within the application context) and HTTP methods such as GET, POST, and HEAD (by which these paths are accessed) must be protected so that only certain authenticated principals may access the resources. The Web resources are defined in the web-resource-collection subelement in web.xml. The principals--users and groups--are listed in role-name subelements of the auth-constraint subelement.

During deployment, the Oracle WAR deployment tool will ensure appropriate protection of Web resources at runtime, but cannot decide what groups of users in your realm correspond to the roles used by the application.

Before deploying the WAR file, it is your responsibility to make sure users and groups for all role names used in application security constraints have been created. Users and groups must be created as appropriate for all role names specified by role-name subelements of any security-role elements in the web.xml file.

Note:
The servlet 2.2 specification requires each role name used in an authorization constraint to be declared in a separate security-role element in the web.xml file. If this requirement is not followed, the Oracle WAR deployment tool issues an error.

Create a Group for All Realm Users Prior to Deployment (if necessary)

The web.xml DTD in the servlet 2.2 specification allows a security-constraint element with an auth-constraint subelement that does not contain any role name, as in the following example:

<security-constraint>
    <web-resource-collection>
        <web-resource-name>SalesInfo</web-resource-name>
      ...
    </web-resource-collection>

    <auth-constraint>
       <description> 
          all authorized users in realm should be allowed access 
       </description>
    </auth-constraint>
</security-constraint>

The specification does not , however, clarify what such a constraint means. It is reasonable to assume it means that all users of the application realm are authorized to access the Web resource collection. Such protection is sensible because it requires that all clients authorize themselves in the given realm before they can use a Web resource.

There is no direct way in the OSE HTTP security mechanism to protect a resource for all existing and future users in the realm, but there is a convenient workaround. In order to achieve the desired effect, you can create a group which consists of all users in the realm, and give appropriate permissions to that group. You also need to edit the web.xml file to add a role-name subelement with the name of the newly created group.

For example, without a workaround the above security constraint will cause the following error message during WAR deployment:

WARNING: Web Resource Collection "SalesInfo" is defined,
but the list of Security Role names is empty in its 
<auth-constraint> element. 
In this release you need to provide a Security Role name in order to protect a 
Web resource. 
Web resource "SalesInfo" will not be protected.

To remedy the situation, issue an appropriate realm group command from the Oracle9i session shell. Consider the following example, which assumes the application is deployed in the domain scottRoot:

realm group -w scottRoot -realm catalogRealm -add allUsrs

Continuing the example, you would then need to use appropriate realm parent commands, such as the following, to put desired principals into the allUsrs group:

realm parent -w scottRoot -realm catalogRealm -group allUsrs -add tyrone

(This adds the OSE principal tyrone to the group allUsrs.)

In addition, you will need to add a new security-role element to the web.xml file, as follows:

<security-role>
   <role-name>allUsrs</role-name>
</security-role>

You must also add the following subelement under the auth-constraint subelement of the web.xml security-constraint element:

      <role-name>allUsrs</role-name>

For more information about Oracle9i session shell commands such as realm group and realm parent, see the Oracle9i (or 8i) Java Tools Reference.

Database Sessions, Servlet Context Ownership, and Application Privileges

The Oracle Servlet Engine, and any components of your application, will execute within an Oracle database instance, and therefore within a particular database session. Additionally, when you run the Oracle WAR deployment tool, the tool will run in a particular database session, and this session is used to deploy your application. In particular, when the new servlet context for your application is created, it will be owned by the database schema of the deployment session.

For your application to run properly, you must be aware of the database schema that will own the servlet context, the database schema where your application classes and resources will be loaded, and the database schemas that are likely to be used in running your application. These considerations will determine whether your application will have the necessary privileges to run properly and access desired database entities such as tables and stored procedures.

The rest of this section describes what determines the deployment database session schema, and discusses special considerations regarding application privileges.

Deployment Database Session Initiation and Schema

Depending on how you invoke the Oracle WAR deployment tool, the deployment database session schema may be determined either explicitly or implicitly.

Explicit Deployment Session Initiation

There are a couple of ways to explicitly determine the deployment database session schema:

using the session shell deploywar command

When you log in to the Oracle9i session shell, you supply a database user name and password, and a database session is started for that user schema. Any subsequent session shell command, including deploywar, is executed within that session, by that schema. When you run deploywar, this schema becomes the deployment database session schema.
using Java or a PL/SQL call specification to invoke DeployWar.main()

When you log in to the database and invoke the DeployWar.main() method, either directly from Java or through a PL/SQL call specification, the schema you logged in as becomes the deployment database session schema.

Implicit Deployment Session Initiation

All WAR deployment tool vehicles that invoke the deployment servlet--including the deploywar.htm form, the client-side script (for Oracle clients), or the client-side deployment tool wrapper (for non-Oracle clients)--start a deployment database session in which the deployment servlet runs.

According to general OSE policy, the schema of this database session is determined as follows:

Generally speaking, the deployment database session schema will be the schema that owns the domain of the servlet context in which the deployment servlet runs. (This is the servlet context in which it was published.) This is SYS for the copy of the deployment servlet that is published automatically when an Oracle9i database is created. If you publish additional copies of the deployment servlet, or if you install the Oracle WAR deployment tool onto an existing Oracle8i 8.1.7 database, then the schema depends on how you published the deployment servlet.

If the servlet context in which the deployment servlet runs was published with the run-as-owner property set to true, then the deployment database session schema will be the schema that owns the servlet context, instead of the schema that owns the domain.

Note:
Initially, when a servlet context is created, it is owned by the schema that created it. This owner can be changed later through the session shell chown command. You can verify the owner through the session shell ls command ($ is the session shell prompt):
$ ls -l <context_name>

Special Deployment Considerations Regarding Application Privileges

To help ensure that your application will run properly, consider the following points when you deploy it:

If the run-as-owner attribute of the context-descriptor element is set to true in the Oracle auxiliary descriptor during deployment, all servlets in your application will run with privileges of the owner of the servlet context that was created during deployment of your application.
If your Oracle auxiliary descriptor specifies the schema subelement under the jserver-loader subelement of the class-loader-descriptor element, then that is the schema where your application code will be loaded. If you do not specify this schema element, then your application will be loaded into the deployment database session schema. (These elements are described in "Auxiliary Descriptor Element and Attribute Descriptions".)

Oracle Auxiliary Descriptor

This section provides information about the Oracle auxiliary descriptor, introduced in "Overview of the Oracle Auxiliary Descriptor". The auxiliary descriptor, used in conjunction with the standard web.xml file, is for application settings specific to the Oracle environment.

This section is organized as follows:

Auxiliary Descriptor DTD

This section contains the complete DTD for the Oracle auxiliary descriptor.

<!--
This is the XML DTD for the Oracle Auxiliary Descriptor   Version 1.0.1, 
Dec. 2000
-->

<!--
The oracle-auxiliary-descriptor element is the root element of the Oracle 
specific deployment descriptor.
-->
<!ELEMENT oracle-auxiliary-descriptor (description?, context-descriptor, 
log-descriptor?, jsp-info?, class-loader-descriptor?, login-config?, 
security-role-mapping*)>

<!--
The description element is used to provide descriptive text about the parent 
element.
-->
<!ELEMENT description (#PCDATA)>

<!--
The context-descriptor contains the servlet context information.
-->
<!ELEMENT context-descriptor (description?, default-info?, accept-info?)>


<!--
The debug flag specifies whether to print servlet debug information.
-->
<!ATTLIST context-descriptor debug (true|false) "false">

<!--
The run-as-owner flag specifies whether to allow the user have the owner's 
permissions if the user schema is not the same as the serlvet owners.
-->
<!ATTLIST context-descriptor run-as-owner (true|false) "false">

<!--
The browse-dirs flag specifies whether to allow to see the directory structure 
if welcome file missing.
-->
<!ATTLIST context-descriptor browse-dirs (true|false) "false">

<!-- 
The name attribute is the JNDI name of the servlet context to be created. 
-->
<!ATTLIST context-descriptor name CDATA #IMPLIED >

<!-- 
The virtual-path attribute is the virtual path to the servlet context. 
-->
<!ATTLIST context-descriptor virtual-path CDATA #IMPLIED >

<!-- 
The doc-root attribute is the full path of the doc root directory on a file 
system. 
-->
<!ATTLIST context-descriptor doc-root CDATA #IMPLIED >

<!--
The stateless flag specifies whether the servlet context is stateless.
-->
<!ATTLIST context-descriptor stateless (true|false) "false">

<!--
The default-info element specifies NLS information for the server to use in 
interpreting requests.
-->
<!ELEMENT default-info (description?, charset*, language*)>

<!--
The accept-info element specifies NLS information for the server to use in 
sending responses.
-->
<!ELEMENT accept-info (description?, charset?, language?)>

<!--
The charset element contains the name of a character set.
-->
<!ELEMENT charset (#PCDATA)>

<!--
The language element contains the name of a langauge.
-->
<!ELEMENT language (#PCDATA)>

<!--
The log-descriptor element contains http access, event and error log 
information.
-->
<!ELEMENT log-descriptor (description?, error-log?, event-log?, 
http-access-log?)>

<!--
The error-log element contains the information how errors are logged.
-->
<!ELEMENT error-log (system-log | rdbms-log | file-log)>

<!--
The event-log element contains the information how events are logged.
-->
<!ELEMENT event-log (system-log | rdbms-log | file-log)>

<!--
The http-access-log element contains the information how http-accesses are 
logged.
-->
<!ELEMENT http-access-log (system-log | rdbms-log)>

<!-- 
The optional name attribute of error-log is the name of the JNDI node, 
containing the error log object, relative to context directory. 
-->
<!ATTLIST error-log name CDATA #IMPLIED>

<!--
The optional name attribute of event-log is the name of the JNDI node, 
containing the event log object, relative to context directory. 
-->
<!ATTLIST event-log name CDATA #IMPLIED>

<!-- 
The optional name attribute of http-access-log is the name of the JNDI node, 
containing the http-access log object, relative to context directory. 
-->
<!ATTLIST http-access-log name CDATA #IMPLIED>

<!-- 
The system-log element specifies the log is written into System.out 
-->
<!ELEMENT system-log EMPTY>

<!-- 
The rdbms-log element specifies the log is written into the table, given by the 
'table' attribute.   It is advisable to specify database schema as the prefix in 
table name.  If schema is omitted, the table will be created in the schema used 
for loading Java objects of the application.
-->
<!ELEMENT rdbms-log EMPTY>

<!-- 
The required table attribute of rdbms-log element is the table name for doing 
log into a database.
-->
<!ATTLIST rdbms-log table CDATA #REQUIRED>

<!-- 
The file-log element specifies the log is written into the file, given by the 
'file' attribute. 
-->
<!ELEMENT file-log EMPTY>

<!-- 
The required file attribute of file-log element is the file name for doing log 
into a file.
-->
<!ATTLIST file-log file CDATA #REQUIRED>

<!-- 
The jsp-info element contains setting information for JavaServer Pages.
-->
<!ELEMENT jsp-info (description?, hotload?)>

<!-- 
The hotload element specifies the JSP pages to be hotloaded.
-->
<!ELEMENT hotload (description?, jsp*)>

<!--
The all attribute of hotload element overrides the jsp page list if it is true.
-->
<!ATTLIST hotload all (true|false) "false">

<!--
Each jsp element contains the name of a jsp page that is in the WAR file and is 
to be hotloaded. 
-->
<!ELEMENT jsp (#PCDATA)>

<!--
The class-loader-descriptor element provides information necessary to load 
application classes and resources.
-->
<!ELEMENT class-loader-descriptor (description?, jserver-loader)>

<!-- 
The jserver element holds information necessary to load java objects into the 
database.
-->
<!ELEMENT jserver-loader ( schema?, resolver?)>

<!--
The schema element must be a valid database schema name. If omitted, web 
application will be loaded into the schema which invoked the deployment tool. 
Schema element is case sensitive.
-->
<!ELEMENT schema (#PCDATA)>

<!--
The resolver element must use syntax for '-resolver' option of 'loadjava' tool.   
If omitted, default oracle resolver is used.
-->
<!ELEMENT resolver (#PCDATA)>

<!--
The login-config element takes precedence over the login-config in web.xml.
-->
<!ELEMENT login-config (description?, auth-method, realm-name)>

<!-- 
The auth-method element is the name of security authentication method.
-->
<!ELEMENT auth-method (#PCDATA)>

<!-- 
The realm-name element is the name of the OSE security realm.
-->
<!ELEMENT realm-name (#PCDATA)>

<!--
The security-role-mapping element maps a logical security role name to a 
principal in OSE HTTP security realm.
-->
<!ELEMENT security-role-mapping (description?, security-role, ose-principal)>

<!-- 
The security-role element contains logical security role name.
-->
<!ELEMENT security-role (description?, role-name)>

<!--
The role-name element contains the name of a logical role. It must also appear 
in a security-role element of web.xml application descriptor.
-->
<!ELEMENT role-name (#PCDATA)>

<!--
The ose-principal must be the existing user or group in the HTTP security 
domain, defined by login-config element in this descriptor or in the web.xml.
-->
<!ELEMENT ose-principal (#PCDATA)>

<!--
The ID mechanism is for future references to the elements of this auxiliary 
deployment descriptor. 
-->

<!ATTLIST oracle-auxiliary-descriptor id ID #IMPLIED>
<!ATTLIST description id ID #IMPLIED>
<!ATTLIST context-descriptor  id ID #IMPLIED>
<!ATTLIST default-info id ID #IMPLIED>
<!ATTLIST accept-info id ID #IMPLIED>
<!ATTLIST charset id ID #IMPLIED>
<!ATTLIST language id ID #IMPLIED>
<!ATTLIST log-descriptor id ID #IMPLIED>
<!ATTLIST error-log id ID #IMPLIED>
<!ATTLIST event-log id ID #IMPLIED>
<!ATTLIST http-access-log id ID #IMPLIED>
<!ATTLIST system-log id ID #IMPLIED>
<!ATTLIST rdbms-log id ID #IMPLIED>
<!ATTLIST file-log id ID #IMPLIED>
<!ATTLIST jsp-info id ID #IMPLIED>
<!ATTLIST hotload id ID #IMPLIED>
<!ATTLIST jsp id ID #IMPLIED>
<!ATTLIST class-loader-descriptor id ID #IMPLIED>
<!ATTLIST jserver-loader id ID #IMPLIED>
<!ATTLIST schema id ID #IMPLIED>
<!ATTLIST resolver id ID #IMPLIED>
<!ATTLIST login-config id ID #IMPLIED>
<!ATTLIST auth-method id ID #IMPLIED>
<!ATTLIST realm-name id ID #IMPLIED>
<!ATTLIST security-role-mapping id ID #IMPLIED>
<!ATTLIST security-role id ID #IMPLIED>
<!ATTLIST role-name id ID #IMPLIED>
<!ATTLIST ose-principal id ID #IMPLIED>

Auxiliary Descriptor Element and Attribute Descriptions

Element names used in the auxiliary descriptor DTD are largely self-explanatory given an understanding of Web servers in general and the Oracle Servlet Engine in particular.

This section provides a summary and brief descriptions of the elements, subelements, and attributes. For background information, see the Oracle Servlet Engine User's Guide and Oracle9i (or 8i) Java Tools Reference (particularly information about the session shell createcontext command).

Note:
All elements have an optional description subelement where you can enter a descriptive comment, but these are omitted in the discussion below.

context-descriptor

Use subelements and attributes of this top-level element to indicate properties of the servlet context.

Subelements:

default-info: This has subelements to specify NLS information for the server to use in interpreting requests.

Subelements:
- charset: Use charset subelements of default-info to specify NLS character sets for the server to try in interpreting each request.
- language: Use language subelements of default-info to specify NLS language codes for the server to try in interpreting each request.
A default-info element can have multiple charset or language subelements. They will be tried in the order presented.
accept-info: This has subelements to specify NLS information for the server to use in sending responses.

Subelements:
- charset: Use a charset subelement of accept-info to specify the preferred NLS character set of the server. This character set will be returned through an accept-charset header in the response.
- language: Use a language subelement of accept-info to specify the preferred NLS language encoding of the server. This language encoding will be returned through an accept-language header in the response.
An accept-info element can have at most one charset subelement and one language subelement.

Note:
Refer to the HTTP 1.1 specification for more information about these NLS-related elements.

Attributes:

name: This is the JNDI name of the servlet context to be created (for example, scottContext).
virtual-path: This is the virtual path to the servlet context.
doc-root: This is the full file-system path of the document root directory for the servlet context.
debug (true or false; default false): When the debug attribute is enabled, debugging information--headers and request line of the request, and headers and response line of the response--is printed into the HTTP access log.
run-as-owner (true or false; default false): A servlet context exists inside a domain. By default, any servlet in any servlet context in a given domain executes with permissions of the domain owner. However, any particular servlet context can have a separate owner. (The owner can be changed through a JNDI chown command.) By setting run-as-owner to true, you ensure that servlets in your application execute with permissions of the owner of the particular context, instead of with permissions of the owner of the domain.
browse-dirs (true or false; default false): If the document root does not have welcome files (as specified in the welcome-files-list element in the web.xml file), enabling browse-dirs allows you to still see and browse the directory structure under the document root when you make a request such as the following:
```
http://foo.com/myDir
```
stateless (true or false; default false; applicable only when accessing OSE through the Apache mod_ose module): Enabling stateless specifies that the application associated with the servlet context is a stateless application. (For a stateless application, the Oracle9i JVM database session is reused between client requests. Multiple clients are hosted by the same session, saving startup costs. Servlets are not allowed to create HTTP session objects.)

The name, virtual-path, doc-root, and stateless settings correspond to the context_name, -virtualpath, -docroot, and -stateless settings used by the WAR deployment tool in the session shell createcontext command to create the servlet context. Following is the format of this command ($ is the session shell prompt; this is a single wrap-around command):

$ createcontext -virtualpath <path> [-recreate] [-properties <prop_groups>] 
[-docroot <location>] [-stateless] <domain_name> <context_name>

For information about the createcontext command, see the Oracle9i (or 8i) Java Tools Reference.

Note:
Specify the domain name, which corresponds to the domain_name setting used by the createcontext command, through an Oracle WAR deployment tool command-line option. See "Oracle WAR Deployment Tool Options and Parameters".

log-descriptor

Use subelements of this top-level element to specify information about the error log, event log, and HTTP access log.

Note:
See "Sample Auxiliary Descriptor" for examples of how to use the subelements of log-descriptor.

Subelements:

error-log: This has subelements and attributes to specify where errors are logged.

Subelements (only one of the following may be used):
- system-log: Use this (empty) subelement to log errors to the System.out device.
or:
- rdbms-log: Use this (empty) subelement and its attribute to log errors to a database table.
  
  Attribute:
  - table: The name of the database table to use for the log. It is advisable to include the schema name in the table name, for clarity (for example, SCOTT.tab1 instead of tab1). If you do not specify a schema, then the schema used will be the one into which classes are being loaded (inferred from the schema subelement, if present, of the jserver-loader element under class-loader-descriptor, explained below).
    
    Columns for this table are as follows:
```
(ID NUMBER, LINE NUMBER, TEXT VARCHAR2(4000) );
```
or:
- file-log: Use this (empty) subelement and its attribute to log errors to an operating system file.
  
  Attribute:
  - file: the full path and name of the operating system file to use for the log.
Attributes:
- name: This optional error-log attribute specifies the name of the JNDI node containing the log object, relative to the servlet context directory.
event-log: This has subelements and attributes to specify where events are logged.

Subelements (only one of the following may be used; usage is the same as for error-log):
- system-log
or:
- rdbms-log
  
  Attribute:
  - table
or:
- file-log
  
  Attribute:
  - file
Attributes:
- name
http-access-log: This has subelements and attributes to specify where HTTP access information is logged (this is a standard HTTP log).

Subelements (only one of the following may be used; usage is the same as for error-log, except there is no possible file-log subelement):
- system-log
or:
- rdbms-log
  
  Attribute:
  - table
Attributes:
- name

jsp-info

Use subelements and attributes under this top-level element to specify whether JavaServer Pages are to be hotloaded.

Subelements:

hotload: Use subelements and attributes of this element to specify the JSP pages to be hotloaded.

Subelements:
- jsp: Use jsp elements to specify JSP pages to be hotloaded (overridden by the all attribute). There can be multiple jsp elements, with one JSP page per element.
Attributes:
- all (true or false; default false): Use this attribute to specify that all JSP pages are to be hotloaded (overrides the jsp elements).

For general information about hotloading, see the Oracle JavaServer Pages Developer's Guide and Reference.

login-config

Use subelements of this top-level element to specify login security configuration information. Usage is the same as for the login-config element in the standard web.xml file.

Important:
Any login-config settings in the auxiliary descriptor take precedence over login-config settings in web.xml.

Subelements:

auth-method: This is the security authentication method, either BASIC or DIGEST. (FORM and CLIENT-CERT are not yet supported.)
realm-name: This is the name of the OSE security realm (for example, scottRealm).

class-loader-descriptor

Use subelements under this top-level element to provide required information for loading application classes and resources.

Subelements:

jserver-loader: This has subelements to specify the schema and resolver for loading application classes and resources into the Oracle database.

Subelements:

schema: This is the schema where the application is to be loaded. It must be a valid database schema. If no schema is specified, then the application will be loaded into the schema from which the WAR deployment tool was invoked.

Important:
The schema element is case-sensitive. The string for the schema name must exactly match what would be returned by the following query when the user in question is logged in to the database:
SELECT USER FROM DUAL;

resolver: This is the resolver to be used during loading of the application. The syntax must match what would be used for the loadjava -resolver option. See the Oracle9i (or 8i) Java Tools Reference for information, or see the examples in "Sample Auxiliary Descriptor" immediately below. If no resolver is specified, then the default Oracle resolver is used. (The default resolver for the schema specified in the schema subelement described above.)

Note:
In a future release, when OSE will run outside as well as inside the database, there will also be a jdk-loader element.

security-role-mapping

Use subelements of this top-level element, in conjunction with security-role elements in the web.xml file, to create mappings between logical security role names in the deployment environment and principals (users or groups) in the OSE HTTP security realm.

Subelements:

security-role: Use subelements of this element to specify logical security role names.

Subelements:
- role-name: This is a logical security role name (such as manager). This role name must also appear in a security-role element in the web.xml file, and can be used in a role-name subelement of an auth-constraint subelement of a security-constraint element in web.xml.
ose-principal: This is an OSE user or group in the OSE HTTP security realm that is to be granted HTTP access permissions associated with a particular security role (specified in the role-name element described immediately above). The specified principal must be an existing user or group in the security realm specified in the realm-name subelement of the login-config element in the auxiliary descriptor or web.xml file.

There can be multiple security-role-mapping elements defining security-role to ose-principal mappings.

As an example, presume the following entries in the web.xml file (based on the example in section 13.3.2 of the Sun Microsystems Java Servlet Specification, Version 2.2, with typographical errors corrected):

<security-role> 
   <role-name>manager</role-name> 
</security-role> 
... 
<security-constraint>
   ...