Release 1 (9.0.1)
Part Number A90213-02
 Home |
 Book List |
 Contents |
 Index |  Master Index |  Feedback |
| 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. |
|