|Oracle9i Servlet Engine Developer's Guide
Release 1 (9.0.1)
Part Number A90213-02
This chapter describes Web archive (WAR) deployment to the Oracle9i database for installation and execution of Web applications in the Oracle Servlet Engine. Although the Oracle implementation follows the general WAR deployment standard, there are special considerations and logistics for execution in the Oracle9i JVM. Oracle offers utilities to help with these logistics. The following topics are discussed in this chapter:
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 image files or sound files), servlets, JavaServer Pages (JSP pages) and tag libraries, JavaBeans, Java utility classes, and other resources. (It is typical for libraries of classes and resources to be packaged in JAR files.) You can run such an application in any standard container (servlet engine) from any vendor. In addition, there must be some kind 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:
Each Web application is represented by a servlet context, which maintains application state information and which you can think of as an application container. As defined in the servlet 2.2 specification, a particular servlet context is represented in Java as an instance of a class that implements the standard
javax.servlet.ServletContext interface. See "Servlet Contexts" for more information about servlet contexts.
In general (not considering the Oracle9i JVM in particular), this would be state information for all instances of the different 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 session. 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.
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.
Publishing an application component (such as a servlet or JSP page) is a process to make the component available for execution. When you publish a component, you typically specify a virtual path (or servlet path), which determines the rest of the URL to access the component. The virtual path typically represents 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:
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):
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:
There is a
WEB-INF subdirectory of the document root, according to the servlet 2.2 specification, which contains the application deployment descriptor (described in the next section, "Web Application Deployment Descriptors"). Subdirectories of
WEB-INF 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.xmlfile (the deployment descriptor)
.classfiles for servlet, JavaBean, and utility classes)
/WEB-INF/libdirectory (for JAR files containing libraries of Java
.classfiles 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
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.
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
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>email@example.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. The
web.xml file specifies this through the presence of a
distributable element, defined as follows in the
According to the servlet 2.2 specification, a
The Oracle WAR implementation does not currently support these tags, however. See "Current Restrictions" for more information.
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. ("Overview of the Oracle WAR Deployment Tool" describes the Oracle 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.
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:
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. (Within an application that is marked as distributable, all requests that are part of a particular session can be handled only on a single JVM at any one time.)
With the scalable nature of the Oracle Servlet Engine, 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:
distributabletag 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 checks the application deployment descriptor and issues a warning if the application is not marked
distributable. (Deployment will continue despite the warning.) 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.
"Web Application Deployment Descriptors" describes the standard Web application deployment descriptor file,
web.xml. 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. Furthermore, 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. As with 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.
Oracle offers 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 the tool can be invoked in any of the following ways:
deploywarcommand (requires you to first manually upload the WAR file and auxiliary descriptor)
oracle.mts.http.deployment.DeployWar.main(String args)method (this also requires you to first manually upload the WAR file and auxiliary descriptor)
oracle.aurora.mts.http.deployment.DeploymentServletservlet class has been published to the Oracle Servlet Engine in advance, which occurs as part of Oracle WAR deployment installation)
(Oracle supplies a special form,
deploywar.htm, as a convenient way to invoke the deployment servlet.)
deploywaron UNIX or
deploywar.baton Windows NT)
HttpClientWrapper, directly from Java
"Vehicles for Invoking the Oracle WAR Deployment Tool" discusses each of these ways to invoke the Oracle WAR deployment tool.
When you invoke the WAR deployment tool, it performs several automated steps, presuming that your
web.xml file and Oracle auxiliary descriptor are configured in some appropriate way. These steps include the following:
web.xmland the auxiliary descriptor)
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.
"Oracle WAR Deployment Tool Functionality" describes these steps in more detail.
The Oracle WAR deployment tool will translate JSP pages (
If an application being deployed defines any security restrictions, you must complete (or verify) appropriate preparations before deployment:
security-roleelements in the
web.xmlfile. (This is necessary only for roles involved in security constraints.)
For background information about OSE security, see the Oracle9i 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
security-constraint elements in the
web.xml file indicates that the application has security features.
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):
For more information about the
realm publish command, see the Oracle9i Java Tools Reference.
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) according to the
basic authentication method.
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 are 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
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.)
The Oracle WAR deployment tool will protect Web resources according to directives indicated by
security-constraint elements in the
web.xml file. The following example illustrates the structure of these elements:
<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
HEAD (by which these paths are accessed) must be protected so that only certain authenticated principals can access the resources. The
web-resource-collection subelement in
web.xml defines the Web resources. The principals--users and groups--are listed in
role-name subelements of the
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 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. To achieve the desired effect, you can create a group that consists of all users in the realm, and give appropriate permissions to that group. You also must 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
Continuing the example, you must then use appropriate
realm parent commands, such as the following, to put desired principals into the
(This adds the OSE principal
tyrone to the group
In addition, you must add a new
security-role element to the
web.xml file, as follows:
You must also add the following subelement under the
auth-constraint subelement of the
For more information about Oracle9i session shell commands such as
realm group and
realm parent, see the Oracle9i Java Tools Reference.
A simpler way to authenticate is to use the Oracle Single Sign-On server (OSSO). With OSSO authentication all of the authorization checks also take place on the Oracle HTTP Server prior to the request being forwarded to the OSE. Thus, any
<security-role> elements that are present in either the
web.xml or in the Oracle auxiliary descriptor file do not make sense for OSSO, and are ignored. This allows administrators to reuse shrink-wrapped WAR files with minimal changes configure applications to use OSSO authentication.
For additions to the DTD to support OSSO, see "login-config".
The Oracle Servlet Engine, and any components of your application, will execute within an Oracle9i JVM 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 remainder of this section describes what determines the schema of the deployment database session, and discusses special considerations regarding application privileges.
Depending on how you invoke the Oracle WAR deployment tool, the deployment database session schema may be determined either explicitly or implicitly.
There are a couple of ways to explicitly determine the deployment database session schema:
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.
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.
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:
SYSfor 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.
run-as-ownerproperty set to
true, then the deployment database session schema is the schema that owns the servlet context, instead of the schema that owns the domain.
To help ensure that your application will run properly, consider the following points when you deploy it:
run-as-ownerattribute of the
context-descriptorelement is set to
truein 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.
schemasubelement under the
jserver-loadersubelement of the
class-loader-descriptorelement, then that is the schema where your application code will be loaded. If you do not specify this
schemaelement, then your application will be loaded into the deployment database session schema. ("Auxiliary Descriptor Element and Attribute Descriptions" describes these elements.)
This section describes 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:
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 to have the owner's permissions if the user schema is not the same as the serlvet owner's. --> <!ATTLIST context-descriptor run-as-owner (true|false) "false"> <!-- The browse-dirs flag specifies whether to allow the user to see the directory structure if the welcome file is 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 on how errors are logged. --> <!ELEMENT error-log (system-log | rdbms-log | file-log)> <!-- The event-log element contains the information on how events are logged. --> <!ELEMENT event-log (system-log | rdbms-log | file-log)> <!-- The http-access-log element contains the information on 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 the 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 the 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 the 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 writing the 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 writing the 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 the 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, the 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 the '-resolver' option of the 'loadjava' tool. If omitted, the 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 the 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 the OSE HTTP security realm. --> <!ELEMENT security-role-mapping (description?, security-role, ose-principal)> <!-- The security-role element contains the 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 the 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 the 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>
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 summarizes and briefly describes the elements, subelements, and attributes. For background information, see the Oracle9i Oracle Servlet Engine User's Guide and Oracle9i Java Tools Reference (particularly information about the session shell
Use subelements and attributes of this top-level element to indicate properties of the servlet context.
default-info: This has subelements to specify NLS information for the server to use in interpreting requests.
default-infoto specify NLS character sets for the server to try in interpreting each request.
default-infoto specify NLS language codes for the server to try in interpreting each request.
default-info element can have multiple
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.
charset: Use a
accept-infoto specify the preferred NLS character set of the server. This character set will be returned through an
accept-charsetheader in the response.
language: Use a
accept-infoto specify the preferred NLS language encoding of the server. This language encoding will be returned through an
accept-languageheader in the response.
accept-info element can have, at most, one
charset subelement and one
name: This is the JNDI name of the servlet context to be created (for example,
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.
false): When the
debugattribute 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.
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
chowncommand.) By setting
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.
false): If the document root does not have
welcomefiles (as specified in the
welcome-files-listelement in the
browse-dirsallows you to still see and browse the directory structure under the document root when you make a request such as the following:
false; applicable only when accessing OSE through the Apache
statelessspecifies 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.)
stateless settings correspond to the
-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 Java Tools Reference.
Specify the domain name, which corresponds to the
Use subelements of this top-level element to specify information about the error log, event log, and HTTP access log.
See "Sample Auxiliary Descriptor" for examples of how to use the subelements of
error-log: This has subelements and attributes to specify where errors are logged.
Subelements (only one of the following can be used):
rdbms-log: Use this (empty) subelement and its attribute to log errors to a database table.
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,
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
schemasubelement, if present, of the
class-loader-descriptor, explained below).
Columns for this table are as follows:
file-log: Use this (empty) subelement and its attribute to log errors to an operating system file.
event-log: This has subelements and attributes to specify where events are logged.
Subelements (only one of the following can be used; usage is the same as for
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 can be used; usage is the same as for
error-log, except there is no possible
Use subelements and attributes under this top-level element to specify whether to hotload JavaServer Pages.
hotload: Use subelements and attributes of this element to specify the JSP pages to be hotloaded.
jspelements to specify JSP pages to be hotloaded (overridden by the
allattribute). There can be multiple
jspelements, with one JSP page per element.
For general information about hotloading, see the Oracle JavaServer Pages Developer's Guide and Reference.
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
auth-method: This is the security authentication method, either
CLIENT-CERTare not currently supported.)
In addition to already documented values, the
<auth-method> can also be
OSSO. The effect is the same as securing the context in the session shell with the
realm secure -osso command (see Securing a Servlet Context with the OSSO Security Servlet). The special OSSO realm
ossoRealm is created as a result of an
auth-method element equal to OSSO, if it did not exist before. OSSO is the only case where <realm-name> element is optional, and may be omitted in the
<login-config>, as shown in this fragment:
realm-name: This is the name of the OSE security realm (for example,
testRealm). You can omit
Use subelements under this top-level element to provide required information for loading application classes and resources.
jserver-loader: This has subelements to specify the schema and resolver for loading application classes and resources into the Oracle database.
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.
resolver: This is the resolver to be used during loading of the application. The syntax must match what would be used for the
loadjava -resolveroption. See the Oracle9i 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
schemasubelement described above.)
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.
security-role: Use subelements of this element to specify logical security role names.
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-nameelement, as described immediately above). The specified principal must be an existing user or group in the security realm specified in the
realm-namesubelement of the
login-configelement in the auxiliary descriptor or
There can be multiple
security-role-mapping elements defining
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> ... <web-resource-collection> <web-resource-name>SalesInfo</web-resource-name> <urlpattern>/salesinfo/*</urlpattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> ... <auth-constraint> <role-name>manager</role-name> </auth-constraint> ... </security-constraint>
And assume the following entries in the auxiliary descriptor:
security-role-mapping> <security-role> <role-name>manager</role-name> </security-role> <ose-principal>DBA</ose-principal> </security-role-mapping>
In this situation, a logical security role,
manager, is given HTTP access permission to a Web resource collection,
manager is allowed
POST HTTP requests to URLs with a context-relative virtual path that starts with the following:
In the auxiliary descriptor, the
security-role-mapping element maps the
manager logical role name to
DBA, an existing user or group in the OSE security realm.
The auxiliary descriptor mapping is optional. Instead, you could create an OSE principal named
manager. But the mapping functionality in the auxiliary descriptor provides additional flexibility, allowing a better fit for application security roles in a previously existing or general-purpose OSE security realm.
You can map an OSE principal, such as
DBA, to multiple security roles.
This section provides a sample Oracle auxiliary descriptor, based on the DTD in "Auxiliary Descriptor DTD".
<?xml version="1.0"?> <!DOCTYPE oracle-auxiliary-descriptor PUBLIC "-//Oracle Corporation//DTD Oracle Auxiliary web Descriptor//1.0/EN" "otn.oracle.com"> <oracle-auxiliary-descriptor> <description> This is an example Oracle Auxilary Descriptor for Version 1.0, Dec. 2000 webdomain for servlet context is given on command line as: $ deploywar -webdomain /serviceroot/10.1.1.20/cavist.com foo.war foo.xml </description> <context-descriptor debug="true" run-as-owner="false" browse-dirs="true" stateless="false" name="winecellar" virtual-path="/cellar" doc-root="/usr/htdocs/web-static-content"> <description> The full JNDI context name is: /serviceroot/10.1.1.20/cavist.com/winecellar <default-info> <charset> ISO-8859-1 </charset> <language> en-gb </language> <language> en </language> </default-info> <accept-info> <charset> ISO-8859-1 </charset> <language> en </language> </accept-info> </context-descriptor> <log-descriptor> <description> error log is written to System.out event log - to database table "$OSE$ERROR_LOG$" (HR schema, as specified) http access log - to table "$OSE$ACCESS_LOG$" (HR schema, as inferred from jserver-loader) JNDI node in context "winecellar" will be called "logs/audit" </description> <error-log> <system-log/> </error-log> <event-log> <rdbms-log table="HR.$OSE$ERROR_LOG$"/> </event-log> <http-access-log name="logs/audit" > <rdbms-log table="$OSE$ACCESS_LOG$"/> </http-access-log> </log-descriptor> <jsp-info> <hotload all="false"> <jsp> /cellar/jsp/wine_1.jsp </jsp> <jsp> /cellar/jsp/cell_1.jsp </jsp> </hotload> </jsp-info> <class-loader-descriptor> <jserver-loader> <schema> HR </schema> <resolver> ((* HR) (* PUBLIC) ) </resolver> </jserver-loader> </class-loader-descriptor> <login-config> <description> This login-config will override the login-config in web.xml file. Valid authorization method values are BASIC or DIGEST. </description> <auth-method> BASIC </auth-method> <realm-name> wineRealm </realm-name> </login-config> <security-role-mapping> <security-role> <description> Mapping application's "manager" role to OSE HTTP Security </description> <role-name> manager </role-name> </security-role> <ose-principal> DBA </ose-principal> </security-role-mapping> </oracle-auxiliary-descriptor>
This section describes steps the Oracle WAR deployment tool takes in deploying an application, represented by a WAR file, to the Oracle9i database:
Any necessary WAR deployment tool parameter settings are noted. For information about how to invoke the deployment tool and set its input parameters, see "Oracle WAR Deployment Tool Usage".
A WAR file can generally have an arbitrary directory structure, but a
WEB-INF subdirectory is required. This subdirectory contains the
web.xml file and, in further subdirectories, all Java classes and resources used in the application. There are many possible kinds of resources, but examples include external resource (
.res) files for JSP pages, serialized resource (
.ser) files for SQLJ JSP pages, and tag library descriptor (
.tld) files for JSP tag libraries. (See the Oracle JavaServer Pages Developer's Guide and Reference for more information about
JSP pages themselves are outside the
WEB-INF directory, and the Oracle WAR deployment tool assumes that any other files outside the
WEB-INF directory are static documents to be served as is to any requests at runtime.
The remainder of this section gives more information about how the deployment tool loads deployment descriptors, Java files, and static files.
The Oracle WAR deployment tool uses the Oracle
loadjava tool to load the
web.xml descriptor file and the Oracle auxiliary descriptor file into the database as Java resources. The
web.xml file is extracted from the
WEB-INF directory of the WAR file; the auxiliary descriptor is specified through a parameter of the session shell
deploywar command, the deployment servlet, or the client-side script (as described in "Oracle WAR Deployment Tool Options and Parameters").
The descriptors are loaded as follows, where
context_name is the name of the servlet context that is created, and is taken from the
name attribute of the
context-descriptor element in the Oracle auxiliary descriptor.
web.xmlfile is loaded as:
To run in the Oracle Servlet Engine, Java code must be loaded into the Oracle9i database. The Oracle WAR deployment tool examines the WAR file and uses the Oracle
loadjava tool to load the following:
This includes Java class files under the
/WEB-INF/classes subdirectory in the WAR file, and JAR files under the
loadjava encounters problems, the WAR deployment tool will report them to you. Note that errors in individual Java objects do not prevent deployment of remaining objects. After deployment has finished, you have the option of correcting any errors and manually using
loadjava to reload the Java objects that caused the errors. Alternatively, you can repackage the WAR file and redeploy the application.
Be aware of the following:
-replaceoption of the Oracle WAR deployment tool when you want to redeploy an application that has been deployed previously (whether or not there were errors during the previous deployment).
schemasubelement under the
class-loader-descriptorelement in the Oracle auxiliary descriptor file. This is to specify the database schema where Java objects will be loaded. (Alternatively, you can let the deployment tool default to the schema of the user session from which you are invoking the deployment tool.)
.sqljspfiles) in the WAR file, but will not translate or compile
.javafiles. (The servlet 2.2 specification assumes that only compiled classes are used as application code.) Any
.sqljfiles in the WAR file will be treated as Java resources and loaded as is. If your initial WAR file does not conform to the specification, then you must manually perform any server-side translation or compilation and then repackage the WAR file.
Most Web applications, in addition to dynamic components such as servlets and JSP pages, use static pages (such as HTML pages) whose output does not change from request to request. WAR file contents that are not under the
WEB-INF directory, with the exception of JSP source files, are assumed to be static pages. These files must be copied to the appropriate document root directory during OSE deployment.
For any Web application that will run in OSE and use OSE directly as the Web server, the Oracle WAR deployment tool will place static documents into the specified document root directory of the servlet context that corresponds to the application. The doc root is a directory in the file system of the machine on which the database (including its Oracle Servlet Engine) is installed.
Before invoking the deployment tool in situations where OSE will be used directly as the Web server, set the
doc-root subelement under the
context-descriptor element in the Oracle auxiliary descriptor file to specify the application doc root. If necessary, the deployment tool will create the file system directory and the
doc_root object in the application's servlet context (once it has created the servlet context).
Regarding file permissions, you must verify the following:
writepermission for the parent directory so that the deployment tool can write to it.
readpermission for the deployed WAR file and Oracle auxiliary descriptor.
You can address both of these issues through
dbms_java.grant_permission calls (through SQL*Plus or equivalent) for
PropertyPermission, as in the following examples:
call dbms_java.grant_permission ('HR', 'SYS:java.io.FilePermission', '/usr/htdocs/web-static-content/-', 'read/write'); call dbms_java.grant_permission ('HR', 'SYS:java.util.PropertyPermission', '*', 'read,write');
This example assumes that
HR is the user name and
/usr/htdocs/web-static-content is the parent directory. The directory name must be the full path of the parent directory, followed by a hyphen.
In many circumstances, OSE is not used directly as the Web server. Instead, a front-end Web server such as the Oracle HTTP Server powered by Apache is used. In this case there may be no need to specify a doc root directory for deployment, but you must manually copy your static files to the doc root of the front-end Web server. (The Oracle auxiliary descriptor
doc-root subelement under the
context-descriptor element is optional.)
As described in "Web Application Servlet Contexts", a Web application is represented by a servlet context, which acts as an application container. A servlet context is represented in Java as an instance of a class that implements the standard
javax.servlet.ServletContext interface. The Oracle WAR deployment tool will create a servlet context during deployment of your application and will define initial servlet context parameters according to
context-param settings, if this element is present in the
When deploying the application, you must specify the servlet context name and the URI path or paths you want mapped to the context (and therefore, to the application). To provide this information, set the following attributes of the
context-descriptor element in the Oracle auxiliary descriptor file:
When you invoke the Oracle WAR deployment tool, you must specify the domain where you want the deployment tool to place the context (for example, through the
-webdomain parameter in the session shell
deploywar command or client-side script).
(Refer to the Oracle9i Oracle Servlet Engine User's Guide for background information about domains, context names, and virtual paths.)
When you deploy an application to the Oracle9i database, the Oracle WAR deployment tool will publish any servlets and JSP pages in the application. This process makes them available for execution in the Oracle Servlet Engine. (Refer to the Oracle9i Oracle Servlet Engine User's Guide for background information about publishing.)
The remainder of this section describes the publishing process for servlets and JSP pages, and any necessary preparations.
For an application to follow the servlet 2.2 specification, any class that is to be accessed as a servlet must have a corresponding
servlet element, with
servlet-class subelements, in the
web.xml file. If no
servlet element is present, then the Oracle WAR deployment tool will load the servlet class into the database, but will not publish it as a servlet in the application servlet context.
If a servlet will be accessed through one or more virtual paths within the servlet context, then the
web.xml file must also contain a
servlet-mapping element for each virtual path.
According to the servlet 2.2 specification, a JSP page would have a
servlet element with a
jsp-file subelement instead of a
servlet-class subelement. However, use of the
servlet element is not required for JSP pages in Oracle WAR deployment.
If the Oracle WAR deployment tool encounters a
.jsp file or
.sqljsp file outside the
WEB-INF directory, and the page is not explicitly listed in the
web.xml file, the page will still be translated, compiled, and published. In this case, however, a user would invoke the page with a servlet path that is determined by the context-relative path of the file in the WAR file hierarchy.
Consider the following example.
imajsp.jsp, is located in
jsp/imajsp.jspin the WAR file. This makes the following its context-relative path:
Therefore, a user would invoke the page as follows:
The Oracle WAR deployment tool performs the following steps for each
.sqljsp file that it deploys into the Oracle9i database:
For example, a directory path of
myroot/myjsp will result in the following package:
(For more information about package naming by the OracleJSP translator, including its use of leading underscores, see the Oracle JavaServer Pages Developer's Guide and Reference.)
servlet-mappingelements in the
web.xmlfile (if any).
servletelement for the JSP page in the
web.xmlfile, then the JNDI name is the same as the
servlet-namesubelement of the
servletelement, then the servlet name is determined by the path of the JSP page in the WAR file. First,
implicit_is prepended, then each slash ("/") in the path is replaced by an underscore ("_"). For example,
myroot/myjsp/page1.jspwould have the following JNDI name:
To protect a virtual path, the Oracle WAR deployment tool essentially uses the same sequence of session shell commands that you would use manually. For example, to allow users in the group
catalogBuilder in a realm
CatalogRealm to perform
POST operations to the relative virtual path
publishedCatalogs/* (after they authenticate themselves through the
basic authentication method), the deployment tool issues the following session shell commands:
$realm map -s <servletContextPath> -add publishedCatalogs/* -scheme basic:CatalogRealm $realm perm -w <webserviceRoot> -realm CatalogRealm -s <servletContextPath> -name catalogBuilder -path publishedCatalogs/* + POST
Any messages printed by the
realm commands are output by the WAR deployment tool. For example, the following messages indicate that the two realm commands above succeeded:
mapping `publishedCatalogs/*' with scheme `basic:CatalogRealm' added permissions post granted on publishedCatalogs/* for catalogBuilder
If, however, you did not create a user or a group named
catalogBuilder in the realm
CatalogRealm prior to deployment, you will see the following error message:
For information about preliminary steps you must take before establishing application security, see "Security Preparations".
This section describes the Oracle WAR deployment tool, introduced in "Overview of the Oracle WAR Deployment Tool". The deployment tool takes an application WAR file and Oracle auxiliary descriptor and deploys the application into the Oracle9i database accordingly. You can then execute the application in the Oracle Servlet Engine.
The following subsections describe the different ways to invoke the deployment tool, and document the options and input parameters that the deployment tool supports:
Each of the vehicles for invoking the Oracle WAR deployment tool supports the same set of key options and parameters, and the deployment servlet and client-side script support additional parameters as appropriate.
Table 8-1 summarizes these options and parameters. (The session shell WAR deployment command, deployment servlet, and client-side script are described in "Vehicles for Invoking the Oracle WAR Deployment Tool".)
|Functionality||Session Shell Command Parameter||Deployment Servlet Parameter||Client-Side Script Parameter|
WAR file name
(enter file name on command line)
Oracle auxiliary descriptor file name
(enter file name on command line)
Web domain name (where the application's servlet context will be created)
Replacement of a previously deployed application (disabled by default)
Verbose output from tool (disabled by default)
XML validation for
on by default;
Upload directory for files being loaded (WAR file and Oracle auxiliary descriptor)
URL of deployment servlet
Schema (and optionally password) where WAR file and auxiliary descriptor will be deployed
n/a to deployment servlet (inferred from the schema used in executing the servlet)
Password for target schema (if not supplied with user name)
Help (brief usage notes)
WAR file and Oracle auxiliary descriptor
If you are using the session shell
This is always required to specify the (existing) Web domain where the WAR deployment tool is to create the servlet context for the application being deployed. In an OSE single-domain scenario, this would simply be a name such as the following:
In an OSE multi-domain scenario, however, you must include the IP address and DNS name such as in the following example:
You must always specify the absolute domain name (starting with "/"), regardless of your current directory in the session shell.
If an application has already been deployed, even if it deployed with errors, OSE will not allow creation of a servlet context again unless you enable this option.
Enabling this option significantly increases the amount of output (especially from the
XML validation (can be disabled for
You can disable XML validation for
This option may not be supported in future releases.
The Oracle WAR deployment tool must have
User and password
These are not applicable for the session shell
General comments about client-side script parameters
You have choices in how to format your command-line option settings for the client-side scripts (such as whether they are preceded by a hyphen). See "Oracle Client-Side Deployment Scripts (Oracle Client)" for information.
This section describes each of the ways to invoke the Oracle WAR deployment tool, providing details about option settings and command-line syntax as applicable. The following topics are covered:
When using the session shell command or invoking the WAR deployment tool from server-side Java or a PL/SQL call specification, you must first manually place the WAR and auxiliary descriptor files onto the file system of the target server. Loading these files is generally done for you if you deploy through one of the client-side vehicles that Oracle provides.
From the Oracle9i session shell, you can use the
deploywar command to deploy a Web application packaged in a WAR file. Here is the command-line syntax (this is a single wrap-around command line;
$ is the session shell prompt):
$ deploywar [-replace|-r] [-verbose|-ver] [-noxmlvalidate|-nox] -webdomain|-w <domain_name> <WAR-file-name> <Oracle-aux-descriptor>
-webdomain option, WAR file name, and Oracle auxiliary descriptor file name are mandatory arguments.
The WAR and auxiliary descriptor file names must include full paths to the files and must be specified on the command line in the positions shown in the example.
-noxmlvalidate settings are optional. The order of these three options and the
-webdomain option amongst themselves is not significant.
For general information about deployment options and parameters, see "Oracle WAR Deployment Tool Options and Parameters".
For general information about the Oracle9i session shell and how to run it, see the Oracle9i Java Tools Reference.
To invoke the Oracle WAR deployment tool from server-side Java code or through a PL/SQL call specification, you can use the following public static method:
Arguments are the same as for the session shell
deploywar command. See "WAR Deployment Tool Session Shell Command".
Provided with the Oracle WAR deployment tool is a servlet that you can use to start deployment of a WAR file to the Oracle9i database from a client.
This deployment servlet is preloaded in the database
SYS schema and published in the
admin domain of the Oracle Servlet Engine, under the
/deploywar virtual path. Alternatively, you can publish it in any other desired context with a virtual path of your choice.
On the server, the Java class for the servlet is as follows:
For convenience, Oracle also provides a form called
deploywar.htm that you can use to invoke the servlet from a client. In Oracle9i releases, this form is in the doc root,
[ORACLE_HOME]/jis/public_html, of the default context of the OSE
admin service. For the Oracle8i 22.214.171.124 and 126.96.36.199 releases, it is in the
packager.jar files that are included with the Oracle Technology Network download.
deploywar.htm is placed in an appropriate doc root directory, access it from a browser, supplying settings for the following parameters when prompted:
target dir for WAR file and aux descriptor
Web domain for servlet context
WAR file name
Oracle auxiliary descriptor file name
deploywar.htm form prompts you for all of these, but only
auxdescriptor are required. The
replace parameter defaults to
verbose defaults to
xmlvalidate defaults to
For general information about these options and parameters, see "Oracle WAR Deployment Tool Options and Parameters".
The remainder of this section discusses considerations in ensuring that the deployment servlet will have sufficient permissions when it executes.
When you deploy your application, its servlet context is created in the domain that you specified through the
webdomain parameter. You must ensure that the database session executing the deployment servlet has sufficient JNDI permissions to browse the domain in question, and to create new JNDI objects in that domain.
One possible way to handle these permission and ownership issues would be to publish the deployment servlet in every domain where you anticipate executing it (publishing it in the default context of each domain, for example).
However, this liberal approach may not fit your security model. You may find it desirable to keep tighter control over application deployment and to use only the copy of the deployment servlet that is automatically published in the
admin domain. This copy of the deployment servlet is owned by the
SYS schema, which can publish your application in any domain and also has the broadest file creation permissions.
The danger of using the
SYS schema, however, is that the servlet context created for your application during deployment will therefore be owned by
SYS. This fact, combined with setting the
run-as-owner property of the
context-descriptor element to
true in the auxiliary descriptor, would give the application unlimited access to the database. However, you can prevent this potential security breach by using the session shell
chown command to change ownership of the servlet context immediately after application deployment.
Also be aware that in the current release, you cannot control the database session owner by means of HTTP security authentication. Although you can protect access to the deployment servlet by using the HTTP security
realm command of the session shell and requiring a user to be authenticated before invoking the deployment servlet, be aware that the user being authenticated for HTTP access comes from an OSE HTTP security domain. When the user is authenticated successfully and is found to have permissions to the servlet, servlet execution is allowed to start. In general, however, this has no relation to the database schema that actually executes the servlet.
Currently, you can control which database users can execute the deployment servlet only as follows:
For deploying your application from a system with an Oracle client installation, an alternative to invoking the deployment servlet from the
deploywar.htm form or an HTTP client is to use a client-side deployment script that Oracle provides and which uploads the WAR and auxiliary descriptor files for you.
The client-side deployment script requires an Oracle client installation. For a non-Oracle client, see "Oracle Client-Side WAR Deployment Tool Wrapper (Non-Oracle Client)".
On Solaris, run the following script (
% is the UNIX prompt):
On Windows NT, run the following batch file from a DOS prompt or from the
Run command line in Windows:
Running either of these scripts will invoke the Oracle deployment servlet, which is preloaded in the Oracle9i database and published in the
SYS schema of the
admin domain. (Or the deployment servlet, along with the rest of the Oracle WAR deployment software, can be added manually to an Oracle8i 8.1.7 database. Refer to the Oracle WAR deployment README file.)
You can set parameters for the client-side deployment scripts in a variety of ways.
The simplest way to set a true/false parameter is to precede its name with "-" to enable it or with "-no" to disable it, such as in the following examples:
or, to use the accepted shortcuts:
These settings enable the
-replace option and the
-verbose option (which are disabled by default) and disable the
-xmlvalidate option (which is enabled by default).
Set other options (those other than true/false) using an equals sign (=) as follows:
-target=http://www.acme.com:8000/DeploymentServlet -user=HR -password=hr -upload=/tmp -webdomain=/testRoot
or, to use the accepted shortcuts:
For help, use
-? to get the deployment script parameter list.
For parameters other than true/false parameters, you can optionally omit the "-" or replace the "=" with a space, but not both, such as in the following examples:
You can explicitly set true/false parameters to
You must always use "=" (you cannot use a space) when setting true/false parameters explicitly.
As a shortcut, you can set the user name and password simultaneously through the
user option, by placing a forward-slash ("/") between the settings. In this case you do not need to use the
All of the following are equivalent:
File names with the default file name extension are recognized by the client-side deployment script as being WAR files or auxiliary descriptors, in which case you can enter the file names on the command line without the
auxdescriptor parameter name:
.warfile name extension indicates a WAR file.
.xmlfile name extension indicates an Oracle auxiliary descriptor file.
Following is an example of running the client-side deployment script from a Solaris system:
% deploywar t=http://localhost:8080/DeploymentServlet u=HR/hr up=/tmp -r -v -nox w=/testRoot myTestApp.war /somedir/aux.xml
This example accomplishes the following:
-up(upload) setting causes the WAR file and Oracle auxiliary descriptor to be uploaded to the server's
-vsettings enable the
-noxsetting disables XML validation of the
-woption specifies that the servlet context for the application is to be created in the
aux.xml) and the WAR file (
myTestApp.war) have default file name extensions, the
auxdescriptorparameter names are not required.
On a system without an Oracle client installation, you can do the equivalent of running the client-side deployment script by executing the client-side WAR deployment tool wrapper directly from Java, as follows.
UNIX (this is a single wrap-around command):
Windows NT (this is a single wrap-around command):
Specify the WAR file, auxiliary descriptor, and other input parameters just as you would for the client-side deployment scripts, as described above in "Oracle Client-Side Deployment Scripts (Oracle Client)".
This section provides the hierarchy,
web.xml file, and Oracle auxiliary descriptor for a sample application. The following topics are covered:
Consider a sample Web application with the following hierarchy from the root directory:
index.html WEB-INF/ WEB-INF/classes/ WEB-INF/classes/BasicQuery.class WEB-INF/lib/ WEB-INF/lib/ForTag.jar WEB-INF/web.xml images/ images/mailbox.gif jsp/ jsp/tag/ jsp/tag/tagexample.jsp jsp/tag/exampletag.tld jsp/welcome.jsp
The static file
index.html is at the top of the hierarchy in the doc root. There is an
images directory for the one graphic (
In accordance with the servlet 2.2 specification, the
WEB-INF directory contains the
web.xml file, a
classes subdirectory for compiled Java class files (only
BasicQuery.class in this case), and a
lib subdirectory for compressed JAR or ZIP files with utility libraries (
ForTag.jar in this case).
jsp directory contains a JSP welcome page, and the tag subdirectory has a JSP tag example page and the tag library descriptor (TLD file) for the tag library. JSP pages will be translated by the Oracle WAR deployment tool during deployment.
This section provides the sample
web.xml file and Oracle auxiliary descriptor.
Following is the
web.xml deployment descriptor file for the sample application. Note the
servlet-mapping elements for the
BasicQuery servlet and the
tagexample.jsp JSP pages. For JSP pages, the
servlet element has a
jsp-file subelement instead of a
web.xml file also specifies possible welcome pages and an error page.
<?xml version="1.0" encoding="ISO-8859-1"?> <!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> <distributable/> <servlet> <servlet-name>exampletag</servlet-name> <jsp-file>jsp/tag/tagexample.jsp</jsp-file> </servlet> <servlet> <servlet-name>Basic</servlet-name> <servlet-class>BasicQuery</servlet-class> </servlet> <servlet> <servlet-name>welcome</servlet-name> <jsp-file>jsp/welcome.jsp</jsp-file> </servlet> <servlet-mapping> <servlet-name>exampletag</servlet-name> <url-pattern>/jsp/tag/tagexample.jsp</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>Basic</servlet-name> <url-pattern>/basic</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>welcome</servlet-name> <url-pattern>jsp/welcome.jsp</url-pattern> </servlet-mapping> <welcome-file-list> <welcome-file> index.html </welcome-file> </welcome-file-list> </web-app>
Following is the Oracle auxiliary descriptor file for the sample application. This file specifies a servlet context,
MyCtx, in an OSE domain of your choosing, with
/myapp as its virtual path. The doc root will be the context-relative
The application will be deployed into the
HR schema, using the default resolver of that schema (because no resolver is specified).
<?xml version="1.0"?> <oracle-auxiliary-descriptor> <description> This is Oracle Auxilary Descriptor for application MyApp. You may deploy in any Domain you have. </description> <context-descriptor name="MyCtx" virtual-path="/myapp" doc-root="/tmp/myapp_docroot"> <description> The full context name is "Domain/contexts/MyCtx". </description> </context-descriptor> <class-loader-descriptor> <jserver-loader> <schema> HR </schema> </jserver-loader> </class-loader-descriptor> </oracle-auxiliary-descriptor>
Assuming the application component files are in the directory structure indicated by the WAR file example above, and you run the JAR utility from the application root directory, you can create a WAR file named
myapp.war with the following command:
The WAR file will have an internal structure that reflects the application hierarchy (see "Sample Hierarchy").
Using the client-side deployment script (as an example), the following operating system command will deploy the WAR file,
myapp.war, and the Oracle auxiliary descriptor,
% deploywar target=http://host[:8080]/admin/deploywar user=HR/hr \
upload=/tmp webdomain=/MyDomain warfile=myapp.war auxdescriptor=MyAppAux.xml
Or, using parameter name shortcuts and dropping
auxdescriptor (allowable because the WAR file and auxiliary descriptor use default file name extensions):
Or, to enable the
-replace option (so the servlet context can be re-created if the application has previously been deployed) and the
-verbose option (for informative status output from the Oracle WAR deployment tool and the other tools that it calls):
% deploywar t=http://host[:8080]/admin/deploywar u=HR/hr up=/tmp w=/MyDomain -r -v myapp.war MyAppAux.xml
Some features are not yet implemented in the current release of Oracle WAR deployment. Following is a list of the current restrictions.
load-on-startupelement has no effect; OSE does not pre-start servlets. If this element is encountered, the Oracle WAR deployment tool will print a warning message with the order number that was specified in the
web.xmlfile will result in a warning message and will otherwise be ignored.
resource-refelements. Attempts to use these elements will result in a warning message and will otherwise be ignored.
ejb-refelement. Attempts to use this element will result in a warning message and will otherwise be ignored. It is possible, however, to refer to an EJB from a servlet by explicitly using its
security-role-refsubelement of the
servletelement. Attempts to use this subelement will result in a warning message listing names and role links of all security role references found in a servlet definition. If any of these reference names are used in the servlet code, the code must be modified to work without them.
taglibdirective that specifies a tag library descriptor (
.tldfile) in a JAR file. A
taglibdirective must specify a
.tldfile directly. This is because when a JAR file is included in a WAR file, the Oracle WAR deployment tool will distribute the contents according to the WAR file hierarchy. The JAR file would no longer be in its original form, and OracleJSP would no longer be able to find the
.tldfile that had formerly been embedded in the JAR file.
The same restriction exists when the JAR file is published using the session shell
user-data-constraintsubelement of the
FORMvalue for the
form-login-configsubelement of the
CLIENT-CERTvalue for the
auth-methodsubelement of the