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:
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
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.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
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. The web.xml
file specifies this through the presence of a distributable
element, defined as follows in the web.xml
DTD:
<!ELEMENT distributable EMPTY>
For example:
<distributable />
Note:
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:
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 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:
deploywar
command (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.DeploymentServlet
servlet 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.)
deploywar
on UNIX or deploywar.bat
on 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.xml
and the auxiliary descriptor)
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.
"Oracle WAR Deployment Tool Functionality" describes these steps in more detail.
If an application being deployed defines any security restrictions, you must complete (or verify) appropriate preparations before deployment:
security-role
elements in the web.xml
file. (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 login-config
, security-role
, or 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):
$ realm publish -w someService -add catalogRealm -type RDBMS
For more information about the realm publish
command, see the Oracle9i 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) according to 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 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 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.)
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 GET
, POST
, and 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 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.
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 testRoot
:
realm group -w testRoot -realm catalogRealm -add allUsrs
Continuing the example, you must then use appropriate realm parent
commands, such as the following, to put desired principals into the allUsrs
group:
realm parent -w testRoot -realm catalogRealm -group allUsrs -add tyrone
(This adds the OSE principal tyrone
to the group allUsrs
.)
In addition, you must 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 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-constraint>
and <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:
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.
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.
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:
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.
run-as-owner
property 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-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.
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. ("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 createcontext
command).
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.
Attributes:
name
: This is the JNDI name of the servlet context to be created (for example, testContext
).
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 Java Tools Reference.
Note:
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.
Note:
See "Sample Auxiliary Descriptor" for examples of how to use the subelements of |
Subelements:
error-log
: This has subelements and attributes to specify where errors are logged.
Subelements (only one of the following can be used):
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, HR.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:
Attributes:
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 error-log
):
or:
or:
Attributes:
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 file-log
subelement):
or:
Attributes:
Use subelements and attributes under this top-level element to specify whether to hotload JavaServer Pages.
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:
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 web.xml
file.
Subelements:
auth-method
: This is the security authentication method, either BASIC
, DIGEST,
or OSSO
. (FORM
and CLIENT-CERT
are 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:
<login-config>
<description> Context Authentication and Authorization happens on Apache
front end and OSSO server
</description>
<auth-method> OSSO </auth-method>
</login-config>
realm-name
: This is the name of the OSE security realm (for example, testRealm
). You can omit realm-name
if the auth-method
is OSSO.
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.
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 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.)
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:
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, as 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> ... <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, SalesInfo
. Specifically, manager
is allowed GET
and POST
HTTP requests to URLs with a context-relative virtual path that starts with the following:
/salesinfo/
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 .res
, .ser
, and .tld
files.)
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.xml
file is loaded as:
context_name/WEB-INF/web.xml
context_name/oracle_aux.xml
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:
WEB-INF
directory
This includes Java class files under the /WEB-INF/classes
subdirectory in the WAR file, and JAR files under the /WEB-INF/lib
subdirectory.
If 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:
-replace
option 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).
schema
subelement under the class-loader-descriptor
element 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.)
.jsp
and .sqljsp
files) in the WAR file, but will not translate or compile .sqlj
or .java
files. (The servlet 2.2 specification assumes that only compiled classes are used as application code.) Any .java
or .sqlj
files 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:
write
permission for the parent directory so that the deployment tool can write to it.
read
permission 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 FilePermission
and 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 web.xml
file.
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.)
Notes:
|
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-name
and 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 web.xml
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.
/mycontext
imajsp.jsp
, is located in jsp/imajsp.jsp
in the WAR file. This makes the following its context-relative path:
jsp/imajsp.jsp
Therefore, a user would invoke the page as follows:
http://host[:port]/mycontext/jsp/imajsp.jsp
The Oracle WAR deployment tool performs the following steps for each .jsp
or .sqljsp
file that it deploys into the Oracle9i database:
For example, a directory path of myroot/myjsp
will result in the following package:
_myroot._myjsp
(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-mapping
elements in the web.xml
file (if any).
servlet
element for the JSP page in the web.xml
file, then the JNDI name is the same as the servlet-name
subelement of the servlet
element.
servlet
element, 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.jsp
would have the following JNDI name:
implicit_myroot_myjsp_page1.jsp
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:
no such user
Note: 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".)
WAR file and Oracle auxiliary descriptor |
If you are using the session shell |
"Webdomain" option |
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: /testRoot In an OSE multi-domain scenario, however, you must include the IP address and DNS name such as in the following example: /testRoot/10.1.1.20/cavist.com You must always specify the absolute domain name (starting with "/"), regardless of your current directory in the session shell. |
"Replace" option |
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. |
"Verbose" 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
(Severe errors in the This option may not be supported in future releases. |
Upload directory |
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 |
True/false parameters are optional; all other parameters are mandatory and must be explicitly set. 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>
The -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.
The -replace
, -verbose
, and -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:
void oracle.mts.http.deployment.DeployWar.main(String[] args)
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:
oracle.aurora.mts.http.deployment.DeploymentServlet
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 8.1.7.0 and 8.1.7.1 releases, it is in the deploywar.jar
and packager.jar
files that are included with the Oracle Technology Network download.
Once deploywar.htm
is placed in an appropriate doc root directory, access it from a browser, supplying settings for the following parameters when prompted:
replace=true
or false
verbose=true
or false
xmlvalidate=true
or false
uploaddir=<
target dir for WAR file and aux descriptor
>
webdomain=<
Web domain for servlet context
>
warfile=<
WAR file name
>
auxdescriptor=<
Oracle auxiliary descriptor file name
>
The deploywar.htm
form prompts you for all of these, but only uploaddir
, webdomain
, warfile
, and auxdescriptor
are required. The replace
parameter defaults to false
, verbose
defaults to false
, and xmlvalidate
defaults to true
.
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:
run-as-owner
context property
SYS
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.
Important: 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):
% deploywar <parameters>
On Windows NT, run the following batch file from a DOS prompt or from the Run
command line in Windows:
deploywar.bat <parameters>
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:
-replace -verbose -noxmlvalidate
or, to use the accepted shortcuts:
-r -v -nox
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:
-t=http://www.acme.com:8000/DeploymentServlet -u=HR -p=hr -up=/tmp -w=/testRoot
For help, use -help
, -h
, or -?
to get the deployment script parameter list.
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 password
option.
All of the following are equivalent:
-user=HR/hr
or:
-user=HR -password=hr
or:
-user HR/hr
or:
-user HR -password hr
or:
user=HR/hr
or:
user=HR password=hr
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 warfile
or auxdescriptor
parameter name:
.war
file name extension indicates a WAR file.
.xml
file 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:
HR
with password hr
.
-up
(upload) setting causes the WAR file and Oracle auxiliary descriptor to be uploaded to the server's /tmp
directory.
-r
and -v
settings enable the -replace
and -verbose
options.
-nox
setting disables XML validation of the web.xml
file.
-w
option specifies that the servlet context for the application is to be created in the testRoot
domain.
aux.xml
) and the WAR file (myTestApp.war
) have default file name extensions, the warfile
and auxdescriptor
parameter 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):
java -classpath $CLASSPATH oracle.aurora.mts.http.deployment.client.HttpClientWrapper <parameters>
Windows NT (this is a single wrap-around command):
java -classpath %CLASSPATH% oracle.aurora.mts.http.deployment.client.HttpClientWrapper <parameters>
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 (mailbox.gif
).
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).
The 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
and servlet-mapping
elements for the BasicQuery
servlet and the welcome.jsp
and tagexample.jsp
JSP pages. For JSP pages, the servlet
element has a jsp-file
subelement instead of a servlet-class
subelement.
This 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 /tmp/myapp_docroot
directory.
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:
jar cvf myapp.war index.html WEB-INF/ images/ jsp/
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, MyAppAux.xml
:
% 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 warfile
and auxdescriptor
(allowable because the WAR file and auxiliary descriptor use default file name extensions):
% deploywar t=http://host[:8080]/admin/deploywar u=HR/hr up=/tmp w=/MyDomain myapp.war MyAppAux.xml
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.
web.xml
load-on-startup
element 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.xml
file.
web.xml
file will result in a warning message and will otherwise be ignored.
web.xml
env-entry
and resource-ref
elements. Attempts to use these elements will result in a warning message and will otherwise be ignored.
web.xml
ejb-ref
element. 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 Home
and Remote
interfaces.
web.xml
security-role-ref
subelement of the servlet
element. 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.
taglib
directive that specifies a tag library descriptor (.tld
file) in a JAR file. A taglib
directive must specify a .tld
file 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 .tld
file that had formerly been embedded in the JAR file.
The same restriction exists when the JAR file is published using the session shell publishjsp
command.
user-data-constraint
subelement of the web.xml
security-constraint
element.
FORM
value for the auth-method
subelement or form-login-config
subelement of the login-config
descriptor element.
CLIENT-CERT
value for the auth-method
subelement of the login-config
descriptor element.
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|