Release 2 (9.0.2) for Sun SPARC Solaris
Part Number A96157-03
 Home |
 Contents |
 Index |
| Oracle9i Application Server Migrating from Oracle9iAS Release 1 (1.0.2.2.x) to Release 2 (9.0.2) Release 2 (9.0.2) for Sun SPARC Solaris Part Number A96157-03 |
|
This chapter explains how to change the necessary configuration files, application deployment files, and metadata schema in order to migrate Internet Applications components. It contains these major sections:
Migrating Oracle9iAS Containers for J2EE
Migrating Oracle Business Components for Java
This section explains how to perform the following migrations from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle9iAS Release 2 (9.0.2):
This section covers the major considerations for Oracle9i Application Server customers in migrating JSP applications from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle9iAS Release 2 (9.0.2). This involves adapting from an Apache JServ servlet 2.0 environment to the Oracle9iAS Containers for J2EE (OC4J) servlet 2.3 environment supplied in the new release. There are also differences in the JSP container.
The following topics are covered:
Prior to Oracle9iAS Release 2 (9.0.2), JServ was the primary servlet environment. There are significant differences between the OC4J servlet environment, a servlet 2.3 implementation, and the JServ servlet environment, which is a servlet 2.0 implementation. The following list offers a summary of highlights:
globals.jsa mechanism. Use of a globals.jsa file is no longer necessary in Oracle9iAS Release 2 (9.0.2), and is not supported in OC4J.
setCharacterEncoding() method of the HTTP request object. Previous Oracle JSP implementations supported this through the translate_params configuration parameter, and later through the setReqCharacterEncoding() method of a public utility class. You should now migrate your applications to setCharacterEncoding(). See "Globalization Considerations for HTTP Parameters".
In Oracle9iAS Release 1 (1.0.2.2.x), the first release to include OC4J, there were two JSP containers:
The OracleJSP container offered a number of advantages, including useful value-added features and enhancements such as for globalization and SQLJ support. The Orion container also offered advantages, including superior speed, but had disadvantages as well. It did not always exhibit standard behavior when compared to the JSP 1.1 reference implementation (Tomcat), and its support for internationalization and globalization was not as complete.
With Oracle9iAS Release 2 (9.0.2), these two containers have been integrated into a single JSP container, referred to as the "OC4J JSP container". This container offers the best features of both previous versions, runs efficiently as a servlet in the OC4J servlet container, and is integrated with other OC4J containers as well. The integrated container primarily consists of the OracleJSP translator and the Orion JSP container runtime, running with a newly simplified dispatcher and the OC4J 1.0.2.2 core runtime classes.
The Orion container was the default JSP container in Oracle9iAS Release 1 (1.0.2.2.x). If that is the container you used, there are a number of considerations when migrating to the OC4J JSP container in Oracle9iAS Release 2 (9.0.2). Note that it is possible, but not advisable, to configure OC4J to continue to use the original Orion JSP container. If you must do this, it should be a temporary solution only.
Following is a summary of the migration considerations.
Consider the following taglib definition in web.xml:
<taglib> <taglib-uri>/hello</taglib-uri> <taglib-location>WEB-INF/lib/taglib.tld</taglib-location> </taglib>
Note there is no opening "/" in the taglib-location setting. The OC4J JSP container in release 9.0.2 resolves this to the following:
/WEB-INF/WEB-INF/lib/taglib.tld
This is compliant with the JSP specification. The Orion JSP container resolves it to the following (which was presumably the intent of the developer):
/WEB-INF/lib/taglib.tld
It is advisable to change the taglib-location setting to the following (adding the opening "/"):
<taglib-location>/WEB-INF/lib/taglib.tld</taglib-location>
The Orion JSP container sometimes ignored the content of HTML comments, denoted by <!-- ... --> (as opposed to <%-- ... --%> for JSP comments). As a result, the content within the HTML comment was not output.
The OC4J JSP container does not interpret HTML comments, but also does not ignore them. The container passes them through to the browser, which is behavior that complies with the JSP specification. This makes it feasible for developers to add JavaScript to an HTML comment, for example.
The JSP specification does not specify whether an include directive should accept a page header without a proper closing tag. The Orion JSP container would accept such a situation, but the OC4J JSP engine and the Tomcat reference implementation do not. Consider the following example:
-------------------------- a.jsp <jsp:useBean id="b" class="pkgA.BeanB" > <% // init the bean %> -------------------------- -------------------------- b.jsp <%@ include file="a.jsp" %> </jsp:useBean> <%= new java.util.Date() %> --------------------------
This would be accepted by the Orion JSP container. To migrate this to the OC4J JSP container, modify the syntax as follows:
-------------------------- a.jsp <jsp:useBean id="b" class="pkgA.BeanB" > <% // init the bean %> </jsp:useBean> -------------------------- -------------------------- b.jsp <%@ include file="a.jsp" %> <%= new java.util.Date() %> --------------------------
The Orion JSP container accepted the following incorrect syntax:
<%@ include file="value" />
This does not follow the specification and is not accepted by the OC4J JSP container. The correct Include directive syntax is:
<%@ include file="value" %>
According to the JSP 1.2 specification, tag attribute settings must always be quoted. Quotes within a setting must use an escape character. This was not clarified in previous JSP specifications, and the Orion JSP container accepted settings that were not properly quoted.
The following is incorrect, but was accepted by the Orion container:
<jsp:tag prop=<%=bean.getProperty("name")%> />
The following is correct and is now required by the OC4J JSP container; note the additional quotes and escapes:
<jsp:tag prop="<%=bean.getProperty(\"name\")%>"/>
The servlet 2.0 specification did not have a clearly defined concept of a Web application and there was no defined relationship between servlet contexts and applications, as there is in later servlet specifications. In a servlet 2.0 environment such as JServ, there is only one servlet context object per JVM. A servlet 2.0 environment also has only one session object.
Oracle JSP implementations, however, have offered the use of globals.jsa files (a non-standard Oracle extension) to provide support for multiple applications and multiple sessions in a Web server, particularly for use in a servlet 2.0 environment. Where a distinct servlet context object would not otherwise be available for each application, the presence of a globals.jsa file for an application allowed the Oracle JSP container to provide the application with a distinct ServletContext object.
Because OC4J in Oracle9iAS Release 2 (9.0.2) offers a servlet 2.3 environment with standard application support, use of globals.jsa is no longer supported. (See "Migration from globals.jsa".)
The rest of this section discusses globals.jsa considerations and other issues related to the application environment:
The OC4J JSP container in release 9.0.2 no longer supports globals.jsa. If an existing application uses globals.jsa, you should migrate away from this usage. The following substitutions for globals.jsa functionality are recommended:
globals.jsa as an application marker, use standard WAR packaging to denote the application structure.
globals.jsa start-session, end-session, start-application, and end-application events, use standard servlet 2.3 listener functionality. For example, equivalent capabilities are offered through the standard javax.servlet.ServletContextListener and javax.servlet.http.HttpSessionListener interfaces.
globals.jsa for global variable declarations, make the declarations in a single source file and use "global include" functionality of the OC4J JSP engine, introduced in release 9.0.2. See "JSP Global Includes".
If you cannot migrate your code immediately, an application that uses globals.jsa can still run in OC4J if you use the previous oracle.jsp.JspServlet front-end servlet instead of the new oracle.jsp.runtimev2.JspServlet front-end. You can specify this in the <servlet> element in the application web.xml file, which overrides definitions in the OC4J global-web-application.xml file. This should be for short-term use only, however, given that the new front-end servlet supports many new features and configuration parameters and offers improved performance. (See "JSP Configuration".)
The OC4J JSP container in rOracle9iAS Release 2 (9.0.2) uses standard locations on the Web server in searching for translated JSP pages and any.class files and .jar files that they require. The container will find files in these locations without any Web server classpath configuration, and has the ability to automatically reload classes in these locations (depending on configuration settings).
The locations for dependency classes are as follows and are relative to the application root:
/WEB-INF/classes/... /WEB-INF/lib
The location for JSP page implementation classes (translated pages) is as follows:
.../_pages/...
The /WEB-INF/classes directory is for individual Java .class files. These classes should be stored in subdirectories under the classes directory according to Java package naming conventions. For example, consider a JavaBean called LottoBean whose code defines it to be in the oracle.jsp.sample.lottery package. The JSP container will look for LottoBean.class in the following location relative to the application root:
/WEB-INF/classes/oracle/jsp/sample/lottery/LottoBean.class
The lib directory is for .jar files. Because the Java package structure is specified in the .jar file structure, the .jar files are all directly in the lib directory, not in subdirectories. As an example, LottoBean.class might be stored in lottery.jar, located as follows relative to the application root:
/WEB-INF/lib/lottery.jar
The _pages directory is under the following directory in OC4J:
/j2ee/home/application-deployments/app-name/web-app-name/temp
The app-name is determined through the application tag in the OC4J server.xml file; the web-app-name, which corresponds to the WAR file name, is mapped to the app-name through the web-app tag in the OC4J default-web-site.xml file. See the Oracle9iAS Containers for J2EE User's Guide and the Oracle9iAS Containers for J2EE Servlet Developer's Guide for information.
Generated page implementation classes for translated JSP pages are placed in subdirectories under the _pages directory according to the locations of the original .jsp files.
|
Important:
Implementation details, such as the location of the |
The Oracle JspScopeListener interface has been ported to OC4J to track page-scope, request-scope, session-scope, and application-scope events. To conform with servlet 2.3 standards, however, there are changes from how this mechanism was used in previous releases.
For page-scope objects, no special steps or configuration are necessary if you use the OC4J JSP container. There is an Oracle-specific runtime implementation to support page scope. If you want to migrate to another JSP environment, however, you can use a custom tag, checkPageScope, to support page scope.
If you use JspScopeListener for session-scope events, you should now implement the standard HttpSessionBindingListener interface as well as the JspScopeListener interface. This is necessary because the servlet 2.3 standard uses the servlet container instead of the JSP container to provide notification for session-based events. Delegate the valueUnbound() method of HttpSessionBindingListener to a common method shared by the outOfScope() method of the JspScopeListener interface.
JspScopeListener now supports request-scope objects through a servlet filter. The filtering applies to any servlets matching a specified URL pattern. For event-handling for request-scope objects, add an entry such as the following to the web.xml file for your application. To ensure proper operation of the JspScopeListener functionality, this setting must be after any other filter settings.
<filter> <filter-name>Request Filter</filter-name> <filter-class>oracle.jsp.event.impl.RequestScopeFilter</filter-class> </filter> <!-- Define filter mappings for the defined filters --> <filter-mapping> <filter-name>Request Filter</filter-name> <url-pattern>/jsp/*</url-pattern> </filter-mapping>
JspScopeListener now supports application-scope objects through a servlet context listener implementation class, in accordance with the servlet 2.3 specification. For event-handling for application-scope objects, add an entry such as the following to the web.xml file for your application. To ensure proper operation of the JspScopeListener functionality, this setting must be after any other listener settings.
<listener> <listener-class>oracle.jsp.event.impl.AppScopeListener</listener-class> </listener>
For additional information and examples, see the Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference.
In Oracle9iAS Release 2 (9.0.2), the OC4J JSP container introduces a feature called global includes. You can use this feature to specify one or more files to statically include into JSP pages in (or under) a specified directory, through virtual JSP include directives. During translation, the JSP container looks for a configuration file, /WEB-INF/ojsp-global-include.xml, that specifies the included files and the directories for the pages.
This enhancement is particularly useful in migrating applications that had used globals.jsa or translate_params functionality in previous Oracle JSP releases.
Globally included files can be used for the following, for example:
globals.jsa)
translate_params equivalent code
The ojsp-global-include.xml file specifies the names of files to include, whether they should be included at the tops or bottoms of JSP pages, and the locations of JSP pages to which the global includes should apply. This section describes the elements of ojsp-global-include.xml.
This is the root element of the ojsp-global-include.xml file. It has no attributes.
Subelements:
<include>
Use this subelement of <ojsp-global-include> to specify a file to be included, and whether it should be included at the top or bottom of JSP pages.
Subelements:
<into>
Attributes:
file: Specify the file to be included, such as "/header.html" or "/WEB-INF/globalbeandeclarations.jsph". The file name must start with a slash ("/"). In other words, it must be context-relative, not page-relative.
position: Specify whether the file is to be included at the top or bottom of JSP pages. Supported values are "top" (default) and "bottom".
Use this subelement of <include> to specify a location (a directory, and possibly subdirectories) of JSP pages into which the specified file is to be included. This element has no subelements.
Attributes:
directory: Specify a directory. Any JSP pages in this directory, and optionally its subdirectories, will statically include the file specified in the file attribute of the <include> element. The directory setting must start with a slash ("/"), such as "/dir1". The setting can also include a slash after the directory name, such as "/dir1/", or a slash will be appended internally during translation.
subdir: Use this to specify whether JSP pages in all subdirectories of the directory should also have the file statically include. Supported values are "true" (default) and "false".
This section provides examples of global includes.
Assume the following ojsp-global-include.xml file:
<?xml version="1.0" standalone='yes'?> <!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'> <ojsp-global-include> <include file="/header.html"> <into directory="/dir1" /> </include> <include file="/footer1.html" position="bottom"> <into directory="/dir1" subdir="false" /> <into directory="/dir1/part1/" subdir="false" /> </include> <include file="/footer2.html" position="bottom"> <into directory="/dir1/part2/" subdir="false" /> </include> </ojsp-global-include>
This example accomplishes three objectives:
header.html file is included at the top of any JSP page in or under the dir1 directory. The result would be the same as if each .jsp file in or under this directory had the following include directive at the top of the page:
<%@ include file="/header.html" %>
footer1.html file is included at the bottom of any JSP page in the dir1 directory or its part1 subdirectory. The result would be the same as if each .jsp file in those directories had the following include directive at the bottom of the page:
<%@ include file="/footer1.html" %>
footer2.html file is included at the bottom of any JSP page in the part2 subdirectory of dir1. The result would be the same as if each .jsp file in that directory had the following include directive at the bottom of the page:
<%@ include file="/footer2.html" %>
|
Note:
If multiple header or multiple footer files are included into a single JSP page, the order of inclusion is according to the order of |
Assume the following ojsp-global-include.xml file:
<?xml version="1.0" standalone='yes'?> <!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'> <ojsp-global-include> <include file="/WEB-INF/nls/params.jsf"> <into directory="/" /> </include> </ojsp-global-include>
And assume params.jsf contains the following:
<% request.setCharacterEncoding(response.getCharacterEncoding(); %>
The params.jsf file is included at the top of any JSP page in or under the application root directory. In other words, it is included in any JSP page in the application. The result would be the same as if each .jsp file in or under this directory had the following include directive at the top of the page:
<%@ include file="/WEB-INF/nls/parms.jsf" %>
Also see "Global Includes for translate_params Migration".
In OC4J in Oracle9iAS Release 2 (9.0.2), the oracle.jsp.runtimev2.JspServlet front-end servlet replaces the oracle.jsp.JspServlet front-end used for the JServ component of Oracle9iAS.
Mapping of this class as the JSP servlet is handled automatically in the OC4J global-web-application.xml file, as in the following entry:
<servlet> <servlet-name>jsp</servlet-name> <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class> ... init params ... </servlet>
This file also includes <servlet-mapping> elements where file name extensions (.jsp, .JSP, .sqljsp, .SQLJSP) are mapped to this front-end servlet.
Configuration parameters ("init params", see above) can also be set in global-web-application.xml, as in the following example:
<init-param> <param-name>precompile_check</param-name> <param-value>true</param-value> </init-param>
Table 3-1 summarizes JSP configuration parameters supported in the previous front-end servlet for the JServ environment, and notes which are still relevant and supported for OC4J in Oracle9iAS Release 2 (9.0.2).
The following JSP configuration parameters are added for Oracle9iAS Release 2 (9.0.2):
main_mode--This determines whether classes are automatically reloaded or JSP pages are automatically recompiled, in case of changes. Possible settings are justrun, reload, and recompile.
old_include_from_top--Set this boolean to true for page locations in nested include directives to be relative to the top-level page, for backwards compatibility with Oracle JSP behavior prior to Oracle9iAS Release 2 (9.0.2).
precompile_check--Set this boolean to true to check the HTTP request for a standard jsp_precompile setting.
reduce_tag_code--Set this boolean to true for further reduction in the size of generated code for custom tag usage.
req_time_introspection--Set this boolean to true to enable request-time JavaBean introspection if compile-time introspection is not possible. If compile-time introspection is possible and succeeds, this parameter is ignored and there is no request-time introspection.
static_text_in_chars--Set this boolean to true to instruct the JSP translator to generate static text in JSP pages as characters instead of bytes. Also see "Static Text as Characters".
tags_reuse_default--This specifies a default setting for JSP tag handler pooling (true to enable by default; false to disable by default). This default setting can be overridden for any particular JSP page. Also see "Tag Handler Reuse".
xml_validate--Set this boolean to specify whether XML validation is to be performed on the web.xml file and TLD files.
See Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for additional information.
The new "global includes" functionality in the OC4J JSP container in Oracle9iAS Release 2 (9.0.2), described in "JSP Global Includes", is useful in migrating applications that have previously used translate_params for globalization.
In this case, the globally included file can consist of a scriptlet similar to one of the following to achieve functionality that is equivalent to that of translate_params:
or:
contentType attribute of a JSP page directive:
<% request.setCharacterEncoding(response.getCharacterEncoding()); %>
or:
<% String yourCharSet = yourLogicToDetermineCharset(); response.setContentType("text/html; charset="+yourCharSet); request.setCharacterEncoding(response.getCharcterEncoding()); // NOTE: The relative ordering of response.setContentType() // and request.setCharacterEncoding() is important. %>
There are a few relatively minor migration considerations regarding the ojspc pre-translation utility in Oracle9iAS Release 2 (9.0.2).
The ojspc front-end script that sets up the classpath for pre-translation has been modified for the OC4J environment. Most users running ojspc for OC4J should not encounter problems using the new ojspc defaults; however, there are two potential issues to consider:
include directive, you can set -oldIncludeFromTop=true for compatibility with the previous behavior. This ojspc option has the same functionality as the new old_include_from_top JSP configuration parameter.
-staticTextInChars=true if you want the old behavior. This ojspc option has the same functionality as the new static_text_in_chars JSP configuration parameter.
See "New Oracle JSP Configuration Parameters" for information about the old_include_from_top and static_text_in_chars parameters.
If you want to use ojspc for pre-translation for the JServ environment in Oracle9iAS Release 2 (9.0.2), use the new ojspc_jserv script (ojspc_jserv.bat on Windows NT) instead of the ojspc (or ojspc.bat) script.
In previous Oracle9iAS releases, one deployment mechanism was through the standard servlet 2.2 WAR (Web archive) file. In Oracle9iAS Release 2 (9.0.2), deployment is through the standard J2EE 1.2 EAR (Enterprise archive) file, with the WAR file included inside the EAR file.
For OC4J, deploy each application through a standard EAR file. Specify the name of the application and the name and location of the EAR file through an application tag in the OC4J /j2ee/home/config/server.xml file.
You can accomplish this by using Oracle9iAS Enterprise Manager for deployment.
The EAR file includes the following:
application.xml configuration file, in /META-INF
orion-application.xml configuration file, in /META-INF
The WAR file includes the following:
web.xml configuration file, in /WEB-INF
orion-web.xml configuration file, in /WEB-INF
/WEB-INF/classes and in JAR files in /WEB-INF/lib
Place the EAR file in the OC4J applications directory, which is specified in the application-directory setting in the application-server tag of the server.xml file, and is typically the /j2ee/home/applications directory. This would be the same directory as is specified for the EAR file location in the application tag in server.xml.
Through the OC4J auto-deployment feature, a new EAR file in the applications directory (as specified in server.xml) is detected automatically and is hierarchically extracted into the OC4J application deployment directory, according to the deployment-directory setting in the application-server tag of the server.xml file. This is typically the /j2ee/home/application-deployments directory.
This section discusses the following additional considerations:
Oracle9iAS release 9.0.2 includes new globalization functionality.
Effective with the servlet 2.3 specification, the setCharacterEncoding() method is available in the javax.servlet.ServletRequest class as the standard mechanism for specifying a non-default character encoding for reading HTTP requests. The signature of this method is as follows:
void setCharacterEncoding(java.lang.String enc) throws java.io.UnsupportedEncodingException
The enc parameter is a string specifying the name of the desired character encoding, and overrides the default character encoding. Call this method before reading request parameters or reading input through the getReader() method (also of the ServletRequest class).
There is also a corresponding getter method:
String getCharacterEncoding()
In previous Oracle9iAS releases, which used pre-2.3 servlet environments, the setCharacterEncoding() method was not available. For such environments, particularly the JServ servlet 2.0 environment, Oracle's JSP implementation provided two alternative mechanisms as non-standard extensions:
oracle.jsp.util.PublicUtil.setReqCharacterEncoding() method (preferred)
translate_params configuration parameter (or equivalent code)
You should now migrate to the standard setCharacterEncoding() mechanism when you use OC4J.
In JServ, which was the primary servlet environment under previous Oracle9iAS releases, static text is output in character format. In OC4J, static text is output as bytes by default, for faster throughput.
Some globalization functionality and flexibility is unavailable if static text is generated as bytes. For this reason, the OC4J JSP container supports the configuration parameter static_text_in_chars if you want to revert to character format for any reason.
Enable this flag, for example, if your application requires the ability to change the character encoding dynamically during runtime, such as in the following example:
<% response.setContentType("text/html; charset=UTF-8"); %>
Consider the following jsp:include tag and nested jsp:param tag:
<jsp:include page="..." > <jsp:param name="..." value="..." /> </jsp:include>
With the OC4J JSP container in Oracle9iAS Release 2 (9.0.2), there is no need to manually encode the name and value settings for the jsp:param tag. Just use the appropriate Java strings; encoding is handled automatically. This was not the case with the Orion JSP container in Oracle9iAS Release 1 (1.0.2.2.x) (manual encoding was required).
In OC4J with Oracle9iAS Release 2 (9.0.2), you can specify whether JSP tag handler instances are pooled in a particular JSP page (always in the application scope) by setting the oracle.jsp.tags.reuse attribute in the JSP page context. Set it to true to enable pooling, or to false to disable pooling. For example:
pageContext.setAttribute("oracle.jsp.tags.reuse", new Boolean(true));
You can use separate settings in different pages, or even in different sections of the same page.
The default is according to the setting of the tags_reuse_default JSP configuration parameter. This default is true in OC4J, but false in JServ.
OC4J in Oracle9iAS Release 2 (9.0.2) has a more secure session key seed generation process. When the first HttpSession object is created in an OC4J instance, there are a number of threads created to generate the session key seed. Therefore, users experience a longer delay during the first compilation or serving of a JSP page that uses session objects, compared to when using the OC4J in Oracle9iAS Release 1 (1.0.2.2.x). After the seed is generated, the process of compiling and serving JSP pages is as fast as before.
This section covers the major considerations for migrating servlet applications from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle9iAS Release 2 (9.0.2). This involves adapting from the Apache JServ servlet 2.0 environment to the Oracle9iAS Containers for J2EE (OC4J) servlet 2.3 environment.
Included is information about application environment and servlet zones, class and file locations, mount points, servlet aliases, initialization parameters, environment and JVM settings, prestarting, class loading, logging, servlet sessions, load balancing, and fault tolerance. The chapter is organized as follows:
Most sections present information for JServ as a reference, followed by the corresponding information for OC4J.
For more information about topics in this chapter, refer to the Oracle9iAS Containers for J2EE Servlet Developer's Guide and the Oracle9iAS Containers for J2EE User's Guide.
In Oracle9iAS Release 1 (1.0.2.2.x), Apache JServ, a servlet 2.0 environment, was the primary servlet environment. The servlet 2.0 specification did not have a clearly defined concept of a Web application and there was no defined relationship between servlet contexts and Web applications, as there is in later servlet specifications. In a servlet 2.0 environment such as JServ, there is only one servlet context object per JVM. A servlet 2.0 environment also has only one session object.
In Oracle9iAS Release 2 (9.0.2), OC4J is the primary application environment. OC4J includes a servlet 2.3 container with standard Web application support.
The rest of this section covers the following topics:
The servlet 2.2 and 2.3 specifications provide for each Web application to have its own servlet context, unlike in the servlet 2.0 JServ environment. This section reviews the servlet 2.2 and 2.3 functionality.
Each servlet context is associated with a directory path in the server file system that is the base path for modules of the Web application. This is the application root. Each Web application has its own application root. For a Web application in a servlet 2.2 or 2.3 environment, servlets, JSP pages, and static files such as HTML files are all based out of this application root. By contrast, in servlet 2.0 environments the application root for servlets and JSP pages is distinct from the doc root for static files.
Note that a URL for a servlet has the following general form:
http://host[:port]/contextpath/servletpath
When a servlet context is created, a mapping is specified between the application root and the context path portion of a URL. The servlet path is defined in the application web.xml file--the <servlet> tag within web.xml associates a servlet class with a servlet name, and the <servlet-mapping> tag within web.xml associates a URL pattern with a servlet name. When a request reaches a Web application, the servlet container will compare the path in the request with known URL patterns defined in web.xml, and invoke the servlet according to a matched URL pattern. See the Oracle9iAS Containers for J2EE Servlet Developer's Guide for more information.
For example, consider an application with the application root /home/dir/mybankapp/mybankwebapp, which is mapped to the context path /mybank. Further assume the application includes a servlet whose servlet path is loginservlet. This servlet can be invoked as follows:
http://host[:port]/mybank/loginservlet
The application root directory name itself is not visible to the end-user.
To continue this example for an HTML page in this application, the following URL points to the file /home/dir/mybankapp/mybankwebapp/dir1/abc.html:
http://host[:port]/mybank/dir1/abc.html
For each servlet environment, there is also a default servlet context. For this context, the context path is simply "/", which is mapped to the default servlet context application root. For example, assume the application root for the default context is /home/dir/defaultapp/defaultwebapp, and a servlet with the servlet path myservlet uses the default context. Its URL would be as follows:
http://host[:port]/myservlet
The default context is also used if there is no match for the context path specified in a URL.
Continuing this example for an HTML file, the following URL points to the file /home/dir/defaultapp/defaultwebapp/dir2/def.html:
http://host[:port]/dir2/def.html
In Oracle9iAS release 9.0.2, the root context of the default Web application is "/j2ee". This is a change from release 1.0.2.2, where the root context was "/", and affects anything deployed in the default Web application. This includes the samples and demos provided with OC4J.
Consider a servlet in the default Web application that was invoked as follows in release 1.0.2.2:
http://host[:port]/servlet/myservlet
In release 9.0.2, invoke it as follows:
http://host[:port]/j2ee/servlet/myservlet
JServ has the concept of servlet zones, somewhat comparable to the Web application concept in servlet 2.2 and higher specifications. This section compares basic zone setup in JServ to basic application setup in OC4J.
JServ uses servlet zones, where a servlet zone is somewhat similar in concept to a Web application. The use of zones helps developers separate the overall JServ environment into separate groups of servlets, according to conditions such as work load, usage, and security privileges. In JServ, servlets are grouped and managed based on servlet zones, not based on the servlet container itself. It is mandatory to have at least one servlet zone.
Servlet zones are specified in the jserv.properties file. In addition, each zone has its own configuration file, known as a "zone properties file", typically with a naming convention such as zonexxx.properties.
Here is an example of zone settings in jserv.properties:
zones = zone1,zone2
The locations of the corresponding zone properties files are also specified in jserv.properties, as in the following example:
zone1.properties =/servlet/zone1/zone1.properties zone2.properties =/servlet2/zone2/zone2.properties
In OC4J, Web applications can be considered as equivalent to zones. It is also true that in OC4J, servlets are grouped and managed on a per-application basis. Additionally, OC4J has the concept of a default global application that is the parent of all applications and also defines a default Web application.
In OC4J, deploy applications using EAR files. When you deploy an EAR file, you must configure at least the following files:
You can also optionally use an orion-web.xml file for configuration of application-specific OC4J features. The web.xml and orion-web.xml files are typically part of the WAR file.
Following is an overview of key OC4J configuration files for Web applications.
These are global files for all OC4J applications, typically in the OC4J /j2ee/home/config directory:
default-web-site.xml--This includes a <web-app> element for each Web application for the default Web site, mapping the application name to the "Web application name". The Web application name corresponds to the WAR deployment file name. Additional Web site XML files, as specified for additional Web sites in the server.xml file, have the same functionality.
global-web-application.xml--This is a global configuration file for OC4J Web applications, establishing default configurations, and including setup and configuration of the JSP front-end servlet, JspServlet.
application.xml--This is a global configuration file for OC4J J2EE applications.
data-sources.xml--This specifies data sources for database connections.
In addition to the global application.xml file, there is a standard application.xml file, and optionally an orion-application.xml file, for each application. These files are in the application EAR file.
Also, in an application WAR file, which is inside the application EAR file, there is a standard web.xml file and optionally an orion-web.xml file. These are for application-specific and deployment-specific configuration settings, overriding global-web-application.xml settings or providing additional settings as appropriate. The global-web-application.xml and orion-web.xml files support the same elements, which is a superset of those supported by the web.xml file.
If the orion-application.xml and orion-web.xml files are not present in the archive files, they will be generated during initial deployment according to settings in the global-web-application.xml file.
For more information about the use of these files, see the Oracle9iAS Containers for J2EE User's Guide and the Oracle9iAS Containers for J2EE Servlet Developer's Guide.
This section discusses the typical OC4J Web application structure, how to configure file locations in OC4J compared to JServ, and the basics of how to deploy an application. The section is organized as follows:
The locations, or repositories, of servlets under a servlet zone are specified through repositories commands in the zone properties file. (See "Basics of JServ Zone Specification" for information about zone properties files.) JServ loads classes from locations specified in repository entries. Here are some examples:
repositories=/private/mydir/net.jar repositories=/private/mydir/tmp/net.zip repositories=/private/mydir/applications
As shown, class files can be read directly from directories or from archive files (.zip or .jar). See "Class Loading in JServ" for more information about repositories and class loading.
Figure 3-1 shows the typical (and recommended) Web application structure under the application root directory. (Much of it applies generally to servlet 2.2 and 2.3 environments.)
In OC4J, the root directory is app-name/web-app-name. The application name is defined in the server.xml file, and mapped to a Web application name in the default-web-site.xml file or other Web site XML file.
According to this structure, put servlet classes under the <application_name>/<web-app-name>/WEB-INF/classes directory, in subdirectories according to package names as appropriate. For example, if you have HelloWorldServlet in the examples package, then the class file should be located as follows:
<application_name>/<web-app-name>/WEB-INF/classes/examples/HelloWorldServlet
Place HTML files, JSP pages, and other resource files in the application root directory.
Place required library files, such as JAR files, in the following directory:
<application_name>/<web-app-name>/WEB-INF/lib
As you can see, in OC4J as well as in JServ, class files can be read either directly from a directory or from an archive file (ZIP or JAR).
You can also specify a codebase, placing additional required files in a desired location, then adding that location to your classpath through the <classpath> subelement of the <orion-web-app> element in the orion-web.xml file, as in the following example:
<classpath path="/private/test/test.jar" />
With OC4J, you deploy applications using Oracle Enterprise Manager (OEM). Also note that you will typically use an EAR (Enterprise archive) file for OC4J deployment.
Consider the following example, creating an EAR file for a simple application with a servlet HelloServlet and a JSP page Hello.jsp:
web.xml, and optionally orion-web.xml, to specify application-specific settings.
helloapp.war, from the application root using the JAR utility.
The helloapp.war file contains the following:
META-INF/MANIFEST.MF WEB-INF/ WEB-INF/classes/ WEB-INF/classes/HelloServlet.class WEB-INF/orion-web.xml WEB-INF/web.xml Hello.jsp
(The META-INF/MANIFST.MF file is created by the JAR utility. There is no need to modify it.)
helloapp.ear, for deploying the application.
The EAR file contains the following:
META-INF/ META-INF/MANIFEST.MF META-INF/application.xml META-INF/orion-application.xml helloapp.war
The application.xml file is required when deploying an EAR file, but the orion-application.xml file is optional.
Using this helloapp.ear file, you can deploy the Web application using OEM.
This section covers a variety of servlet setup issues, reviewing configuration steps for JServ and providing the equivalent steps for OC4J. This includes the following topics:
This section describes how to set JVM and environment variables for OC4J, compared to how to do so for JServ.
In jserv.properties, you can set environment variables for the JVM to use, including Oracle environment settings. The following examples are for Oracle settings:
wrapper.env=LD_LIBRARY_PATH=... wrapper.env=ORACLE_HOME=... wrapper.env=ORACLE_SID=...
There are also settings for the Java and system environment:
wrapper.classpath=...
wrapper.path=...
The default for UNIX is:
/bin:/usr/bin:/usr/local/bin:
wrapper.bin=...
wrapper.bin.parameters for JVM loading parameters, such as for heap or stack size. Following is an example:
wrapper.bin.parameters=-Xms64m
wrapper.env.copy or wrapper.env.copyall to copy environment parameters from the caller to the JVM. The following examples copy all environment parameters, and a particular environment parameter (myparam), respectively:
wrapper.env.copyall wrapper.env.copy=myparam
In addition, JServ has the following security parameters: security.maxConnections, security.allowedaddresses, and security.authentication.
The method used to set environment parameters for OC4J depends on how it is started.
Startup Through OPMN
If OC4J is started through OEM (more specifically, through the opmn process management module OPMN), then you can set parameters through the $ORACLE_HOME/opmn/conf/opmn.xml configuration file. In particular, the following subelements of the <oc4j> element are of interest:
<java-bin> to specify a path to the Java executable. If this element is not specified, the $ORACLE_HOME/jdk/bin/java is used by default.
<java-option> to specify the command line parameters required by the JVM.
The <java-bin> subelement is equivalent to wrapper.bin in JServ. The <java-option> subelement is equivalent to wrapper.bin.parameters in JServ.
Here is an example (showing only the relevant portions of <oc4j> element syntax):
<oc4j numProcs="1" maxRetry="4" ... > <java-bin path="/private/my-sun/jdk/bin/java" /> <java-option value="-Xmls32m -Xmx64m -Xss128K -Doracle.ons.oraclehome=/private/oracle" /> ... </oc4j>
You can also use the opmn.xml file to specify Oracle environment variables, through the <environment> element, such as in the following example:
<environment> <prop name="PATH" value="/private/home/ias/lib"/> <prop name="CLASSPATH" value="/private/home/ias/bin" /> <prop name="LD_LIBRARY_PATH" value="/private/home/lib" /> </environment>
These settings specify the environment for the new process when it is spawned.
See the Oracle9i Application Server Administrator's Guide for information about OPMN.
JServ (mod_jserv) and OC4J (mod_oc4j) each have "mount" commands to establish application root locations, or "mount points".
In JServ, mount points are used to define the root locations for different servlet zones. If the protocol, host, or port are not specified, then they are picked from default entries in the jserv.conf file, which is included into the httpd.conf file.
Consider the following sample mount commands:
ApJServMount /servlets /root ApJServMount /servlets/admin ajpv11://myhost:9009/admin
Based on these commands, the following would be true, for example:
ApJServMount command, would request the servlet HelloWorldServlet in the servlet zone root:
http://myhost.mycompany.com/servlets/HelloWorldServlet
ApJServMount command, would be handled through port 9009, using Apache JServ Protocol (AJP) version 1.1.
http://myhost.mycompany.com/servlets/admin/HelloWorldServlet
In the OC4J and Oracle HTTP Server environment, you can specify mount points through the $ORACLE_HOME/Apache/modoc4j/conf/mod_oc4j.conf file. You can specify additional relevant Java-side settings, such as host and port, through the default-web-site.xml file.
Refer again to "JServ Mount Settings" above, for comparisons. Consider the following JServ example again:
ApJServMount /servlets/admin ajpv11://myhost:9009/admin
You can make equivalent protocol and host settings through the <web-site> element in default-web-site.xml (or some other Web site XML file, for a Web site other than the default), as follows:
<web-site port="9009" protocol="ajp13" ...> ... </web-site>
Also note that within the <web-site> element, you can use <web-app> subelements to specify information about individual applications on the site, such as the corresponding Web application name and application root. Here is an example:
<web-app application="ojspdemos" name="ojspdemos-web" root="/ojspdemos" />
On the target host, myhost, OC4J would find the Web application according to application settings in default-web-site.xml (or some other Web site XML file).
Based on the preceding Oc4jMount command, the following request would be routed to an OC4J process that listens at myhost on port 9009 using Apache JServ Protocol (AJP) version 1.3:
http://myhost.mycompany.com/servlets/admin/HelloWorld
OC4J would find the application according to application settings in the Web site XML file on myhost.
|
Important:
The host and port specified in the |
If OEM (the opmn process) starts OC4J, then in mod_oc4j.conf you can add the following, in which case opmn will scan all possible ports for a suitable and available AJP port to use. Requests of the form /servlets/admin/* will be directed to one of the OC4J JVMs in the default "home" OC4J instance.
Oc4jMount /servlets/admin/*
This is in conjunction with the following default settings in the default-web-site.xml file:
<web-site port="0" protocol="ajp13" ...> ... </web-site>
You can also specify a particular OC4J instance, or load balancing between clusters, or load balancing between Oracle9iAS instances, as in the following examples:
Oc4jMount /servlets/admin/* oc4j_inst1 Oc4jMount /servlets/admin/* cluster://ias_cluster_1:home,ias_cluster_2:home Oc4jMount /servlets/admin/* instance://ias_inst_1:home_1,ias_inst_2:home_2
For more information about Oc4jMount commands, refer to the Oracle HTTP Server Administration Guide. For more information about default-web-site.xml and other Web site XML files, see the Oracle9iAS Containers for J2EE Servlet Developer's Guide.
This section compares how to specify servlet aliases and URL mapping in JServ to the equivalent functionality in OC4J.
In JServ, servlet aliases are specified in the appropriate zone properties file. For example, for a servlet class example.extensionmapping.InputServlet, you can specify the alias inputservlet to avoid having to specify the full path when you invoke the servlet. This is done as follows:
servlet.inputservlet.code = example.extensionmapping.InputServlet
URL extension mappings, like mount points, are defined in the jserv.conf file. Following is an example:
ApJServAction .inp /servlets/example.extensionmapping.InputServlet
This results in URL patterns ending in ".inp" being mapped to InputServlet.
Also assume the following mount command:
ApJServMount /servlets /root
The following URL, because of this ApJServMount command and the ApJServAction command, is passed to example.extensionmapping.InputServlet in the servlet zone root.
http://myhost.mycompany.com/EmployeeInput.inp
In OC4J, specify servlet aliases and URL mapping through entries such as the following in the global-web-application.xml file:
<servlet> <servlet-name>inputservlet</servlet-name> <servlet-class>example.extensionmapping.InputServlet</servlet-class> </servlet> ... <servlet-mapping> <servlet-name>inputservlet</servlet-name> <url-pattern>/*.inp</url-pattern> </servlet-mapping>
The servlet name (alias) can be anything--it simply serves as a reference name to associate the servlet class with the URL extension that is specified in the <servlet-mapping> element.
This section details the differences between JServ and OC4J in how to set servlet initialization parameters.
JServ supports servlet-based initialization parameter settings ("initArgs") as well as zone-wide default parameter settings. These settings are specified in the appropriate zone properties file.
For example, for a servlet foo1, you would define a servlet-based setting for the name parameter as follows:
servlet.foo1.initArgs=name=scott
A zone-wide default setting, shared by all servlets in the zone, is specified as in the following example. This specifies a default setting for the company parameter:
servlets.default.initArgs=company=oracle
A servlet-based setting overrides a zone-wide (default) setting for the same named parameter.
In OC4J, specify servlet-based initialization parameter settings through subelements of the <servlet> element in the standard web.xml file. The following example is equivalent to the example for foo1 in the preceding section (but also specifies the servlet class):
<servlet> <servlet-name>foo</servlet-name> <servlet-class>FooServlet</servlet-class> <init-param> <param-name>name</param-name> <param-value>scott</param-value> </init-param> </servlet>
There is no exact equivalent in OC4J for the concept of a zone-wide setting--there is no mechanism for application-wide default settings. However, context-param settings are conceptually similar. For each Web application, there is a servlet context. You can set attributes for the context in the application web.xml file, as in the following example.
<context-param> <param-name>company</param-name> <param-value>oracle</param-name> </context-param>
You can access context parameters through standard servlet 2.3 methods of the javax.servlet.ServletContext class. The following example will return an enumerated list of the initialization parameter names for a ServletContext instance:
ServletContext ctx = getConfig().getServletContext(); ctx.getInitParameterNames();
The following call will obtain the value of the company parameter:
ctx.getInitParameter("company");
This section covers migration considerations regarding servlet execution and class loading. The following topics are covered:
In both JServ and OC4J, servlets can be pre-started--rather than having servlet instances created only after the first request arrives, they can be created in advance and pre-started by the servlet container when the container starts up. This reduces the time taken for servicing the first request.
In JServ, servlets to pre-start are specified in the appropriate zone properties file, as in the following example:
servlets.startup=oracle.sample.test1.HelloWorld,foo1
This prestarts HelloWorld and foo1.
Alternatively, you can use an alias name instead of the complete name.
JServ zone properties files also support the following parameters, which have no equivalents in OC4J:
init.timeout destroy.timeout
javax.servlet.SingleThreadModel interface:
SingleThreadModelServlet.initialCapacity SingleThreadModelServlet.incrementCapacity SingleThreadModelServlet.maximumCapacity
In OC4J, you can pre-start servlets by using the <load-on-startup> subelement of the <servlet> element in the application web.xml file, as in the following example:
<servlet> <servlet-name>HelloWorld</servlet-name> <servlet-class>oracle.sample.test1.HelloWorld</servlet-class> <load-on-startup/> </servlet>
This section discusses servlet class loaders, and class reloading during servlet execution.
This section discusses class loaders and class reloading in the JServ environment.
There is a separate class loader for each of the following:
For automatic JServ startup, the system classpath is determined by the wrapper.classpath setting in the jserv.properties file. For manual JServ startup, the system classpath is determined by the CLASSPATH setting for the particular JServ instance.
Classes loaded from the system classpath (including servlet classes) cannot be automatically reloaded without restarting the server.
The zone classpath is specified through the repositories parameter in the zone properties file.
Be aware of the following:
Classes in the zone classpath, and therefore loaded by the zone class loader, can be automatically reloaded if they are modified. This is useful if you are in the process of developing your application, and is determined by the following setting in the zone properties file:
autoreload.classes=true
OC4J classpath and class loader configuration that is equivalent to that of JServ is determined as follows:
<library> element of the global j2ee/home/config/application.xml file, as in the following example:
<library path="/tmp/net.jar" />
You can specify the relative or absolute path to directories, and these directories are scanned for JAR or ZIP files to include in the classpath at startup. By default, the application.xml file specifies the inclusion of files from the j2ee/home/lib directory. (A <library> element exists for this path in the default global application.xml file).
|
Note:
Do not confuse the global |
WEB-INF/classes (for class files, in subdirectories according to package names) and WEB-INF/lib (for JAR and ZIP libraries).
You can add to the application classpath through the <classpath> element of the orion-web.xml file, as in the following example:
<classpath path="/private/test/test.jar" />
You can specify automatic recompilation and reloading of servlets in OC4J by setting the development attribute to "true" in the <orion-web-app> element of the j2ee/home/config/global-web-application.xml file or the application orion-web.xml file (which takes precedence over global-web-application.xml for a particular application).
In this case, classes in the target directory are automatically reloaded whenever they are modified, or whenever an application-level XML file is modified. This is useful when you are in the process of developing your application.
By default, when automatically reloading, source files (.java) are picked up from the target directory WEB-INF/src if it exists. If the src directory does not exist, then source files are picked up from the WEB-INF/classes directory instead. You can specify an alternative target directory through the source-directory attribute of the <orion-web-app> element in the application orion-web.xml file, as in the following abbreviated example:
<orion-web-app ... source-directory="/private/scott/myservletsource" ...> ... </orion-web-app>
In this case, files are picked up from the specified directory only, not from the src or classes directory.
This section discusses session behavior and related configuration in JServ and OC4J.
JServ provides the following parameters in the zone properties file for specifying session behavior:
session.useCookies--Specifies whether to use cookies for sessions (default is true). If false, then the encodeUrl() method of the response object is the only means of session-tracking.
session.timeout--Specifies the number of milliseconds to wait before invalidating a session (default is 1800000, which is 30 minutes).
session.checkFrequency--Specifies how frequently (in seconds) to check for timed-out sessions. (The default is 30.)
For session tracking in OC4J, the servlet container will first attempt to accomplish tracking through cookies. If cookies are disabled, session tracking can be maintained only by using the encodeURL() method of the response object explicitly in the servlet. (The encodeURL() method replaces the servlet 2.0 encodeUrl() method, which has been deprecated.)
You can also specify the number of minutes to wait before a session is invalidated. (The default is 20.) Use the <session-timeout> subelement of the <session-config> element in the application web.xml file, as follows:
<session-config> <session-timeout>30</session-timeout> </session-config>
Additionally, you can disable the use of session cookies with the following setting in the global-web-application.xml or orion-web.xml file:
<session-tracking cookies="disabled" ... > ... </session-tracking>(Cookies are enabled by default.) This is equivalent to the functionality of
session.useCookies in JServ. As in JServ, with cookies disabled you must explicitly use the encodeURL() method of the response object for session-tracking.
This section compares the JServ and OC4J mechanisms for setting up log files.
Message logging parameters such as the log file name, timestamp format, and other settings are specified through the jserv.properties file. This can help with debugging.
Following are the key parameters:
log--Specifies whether or not to log messages (log=true by default).
log.file--Specifies the file where log messages are written. (An absolute path name is recommended.)
log.timestamp--Specifies that messages are to be preceded by a timestamp (log.timestamp=true by default).
log.dateFormat--Specifies the date format in the timestamps. The default is "dd/MM/yyyy HH:mm:ss:SSS.zz".
log.queue.maxage--Specifies the maximum time (in milliseconds) that a message can be in the queue.
log.queue.maxsize--Specifies the maximum number of messages in the queue.
There are also the following parameters to enable different levels of logging information:
log.channel
log.channel.info
log.channel.ServletException
log.channel.jservException
log.channel.warning
log.channel.servletLog
log.channel.critical
log.channel.debug
Setting up logging in OC4J is relatively simple, with few settings required. There are two different logs to consider.
Servlet Logging
In this document, the term "servlet logging" refers to the logging of servlet context information. This includes servlet exceptions and information logged through the log() method of the servlet context object.
You can specify a log file for servlet logging through the <file> subelement of the <log> element in the global j2ee/home/config/application.xml file, as in the following example:
<log> <file path="../log/global-application.log" /> </log>
For a particular application, you can override this setting in the application-specific orion-application.xml file. Refer to the Oracle9iAS Containers for J2EE User's Guide for information about creating this file.
Server Logging
There can also be a log file for server-wide information, such as notices of server startup, shutdown, and recovery, for example. Specify this log file name through the <file> subelement of the <log> element in the server.xml file, using the same syntax as for the application.xml file above.
Web Access Logging
In this document, the term "web access logging" refers to the tracking of HTTP-related information, such as the host, IP address, time, request URI, and HTTP response status code.
In the default-web-site.xml file or other Web site XML file, you can specify the log file through the <access-log> subelement of the <web-site> element, as in the following example:
<web-site ... > ... <access-log path="../log/http-web-access.log" /> ... </web-site>
If the server is started through OEM (the opmn process), then logs are in the opmn/logs directory. Log file names are typically defined as follows:
$OH/opmn/logs/<oc4j_instance_name>.default_island.proc
Alternatively, you can specify log files through the <log-file> element in the $ORACLE_HOME/opmn/conf/opmn.xml file, as in the following example:
<log-file path="../logdir/my-web-access.log" level="3" />
The level attribute specifies the severity level of the logging, from 1 to 6: 1=FATAL, 2=ERROR, 3=WARN, 4=NOTIFY, 5=DEBUG, 6=VERBOSE.
This section describes issues and configuration for load balancing and fault tolerance in JServ and OC4J.
JServ supports request routing by appending the appropriate JServ instance ID to the session ID when an HttpSession object is used.
When an HTTP request is received before a session is started, an arbitrary JServ instance is chosen from the available instances to service the request, and a cookie with the JServ instance ID is sent back to the Web browser (or other HTTP client). Later, when the next request comes from the same session, it is forwarded to the same JServ instance by matching the JServ ID. (If the original JServ instance is down, the request will be forwarded automatically to an alternative instance.)
Given this functionality, HttpSession objects in JServ are non-distributable--the session object cannot be distributed between different JServ instances. As a result, a long-lived HTTP session in JServ decreases the flexibility of load balancing. Also, the session data is lost if the corresponding JServ JVM crashes. Fault tolerance is low, because there is no session failover functionality.
OC4J supports clusters of OC4J instances, and clusters can be customized to the specific needs of the users. Through OC4J load balancing, more user traffic can be handled by distributing the request workload to multiple servers within the cluster. The load balancer replicates the state, such as HttpSession data, of each individual node to the cluster. (The state information is not saved to any persistent storage, but is in memory.) Through OC4J fault tolerance, in case of the failure of a server, a client can automatically be redirected to an alternative server in the cluster.
In OC4J, HTTP sessions are replicated to other OC4J JVM instances within a load-balanced cluster island. This avoids loss of session state in case of JVM failure, and is a feature that is not available in JServ.
Assuming proper configuration, when the request is routed through another JVM in the cluster island, the session state is available in the other JVM as well. Furthermore, the session state is still available even in individual JVM failure scenarios. The Web application proceeds smoothly.
For this functionality, the Web application must be marked as "distributable" in the application web.xml file, through the <distributable> element. Objects in a distributable HttpSession instance must be serializable or remoteable for the replication to work properly.
See the Oracle9i Application Server Performance Guide for more information about OC4J load balancing and fault tolerance.
This section provides a general example of migrating a Web application from Apache JServ to OC4J, noting both the original JServ configuration settings and the OC4J configuration settings. This example does not necessarily reflect a typical or optimal scenario; it is merely for illustrative purposes.
The example includes two servlets (source files HelloWorldServlet.java and SessionServlet.java), two JSP pages (Hello.jsp and snoop.jsp), and accompanying .gif and index.html files.
This section shows the original setup in JServ, prior to migration.
Assume the following directory structure:
/private/scott-sun/migration-example/
index.html classes/ HelloWorldServlet.java SessionServlet.java jsps/ Hello.jsp snoop.jsp examples/ index.html images/ blk_line_bullet_35.gif red_arrow_bullet_35.gif
The following JServ configuration files would have related entries, as described in the subsections immediately below:
APACHE_HOME/apache/conf/jserv/jserv.conf jserv.properties zone.properties
Setup in jserv.conf
In this example, the jserv.conf file includes the following entries:
Alias /migdemos /private/scott-sun/migration-example ApJServMount /servlet /root
Setup in jserv.properties
In this example, the jserv.properties file includes the following entries:
zones=root # Configuration file for each servlet zone (one per servlet zone) # Syntax: [servlet zone name as on the zones list].properties= # [full path to configFile] (String) # Default: NONE # Note: if the file could not be opened, try using absolute paths. root.properties=/private/scott-sun/apache/conf/jserv/zone.properties
Setup in zone.properties
In this example, the zone.properties file includes the following entries:
# List of Repositories ####################### # The list of servlet repositories controlled by this servlet zone # Syntax: repositories=[repository],[repository]... # Default: NONE # Note: The classes you want to be reloaded upon modification should be put # here. repositories=/private/scott-sun/migration-example/classes
URLs for Invocation in JServ
Assuming the preceding configuration, you could use the following URLs (specifying the appropriate port) to directly invoke the various pages.
To invoke the servlets:
http://scott-sun:port/servlet/HelloWorldServlet http://scott-sun:port/servlet/SessionServlet
To invoke the JSP pages:
http://scott-sun:port/migdemos/jsps/Hello.jsp http://scott-sun:port/migdemos/jsps/snoop.jsp
To invoke the index HTML pages:
http://scott-sun:port/migdemos/index.html http://scott-sun:port/migdemos/examples/index.html
Setup in OC4J
This section shows the setup in OC4J in order to migrate. Assume the following structure:
/private/scott-sun/migration-example/
migration-example.ear META-INF/ application.xml migration-example.war index.html WEB-INF/ web.xml orion-web.xml classes/ HelloWorldServlet.java SessionServlet.java jsps/ Hello.jsp snoop.jsp examples/ index.html images/ blk_line_bullet_35.gif red_arrow_bullet_35.gif
Initially, of course, the EAR file (migration-example.ear) and WAR file (migration-example.war) would not yet exist. You would create them with the JAR utility after the rest of the directory structure has been established. They are shown within the directory structure, with contents nested beneath them, for illustrative purposes.
The WAR file would have the following structure:
META-INF/ META-INF/MANIFEST.MF WEB-INF/ WEB-INF/classes/ WEB-INF/classes/HelloWorldServlet.java WEB-INF/classes/SessionServlet.java WEB-INF/web.xml WEB-INF/orion-web.xml jsps/ jsps/Hello.jsp jsps/snoop.jsp examples/ examples/index.html examples/images/ examples/images/blk_line_bullet_35.gif examples/images/red_arrow_bullet_35.gif index.html
Then the EAR file would have the following structure:
META-INF/ META-INF/MANIFEST.MF META-INF/application.xml migration-example.war
Deploy the EAR file according to OC4J deployment conventions. See the Oracle9iAS Containers for J2EE User's Guide and the Oracle9iAS Containers for J2EE Servlet Developer's Guide for more information.
Be aware of the following general suggestions for OC4J migration and deployment:
WEB-INF/lib directory.
j2ee/home/lib directory, where they will be accessible to all applications.
System-wide path settings, such as for class file and JAR file locations, are specified in the global application.xml file:
j2ee/home/config/application.xml
This is where, for example, j2ee/home/lib is set as a server-wide library location.
Setup in application.xml
In this example, the application-specific application.xml file includes the following entries:
<?xml version="1.0"?> <!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1. 2//EN" "http://java.sun.com/j2ee/dtds/application_1_2.dtd"> <application> <display-name>OC4J demo application</display-name> <description> Collection of servlet samples. </description> <module> <web> <web-uri>migration-example.war</web-uri> <context-root>/migdemos</context-root> </web> </module> </application>
Setup in orion-web.xml
In this example, the orion-web.xml file includes the following entries:
<?xml version="1.0"?> <!DOCTYPE orion-web-app PUBLIC "-//Evermind//DTD Orion Web Application 2.3//EN" "http://xmlns.oracle.com/ias/dtds/orion-web.dtd"> <orion-web-app deployment-version="9iAS 9.0.2" servlet-webdir="/servlet" > </orion-web-app>
Setup in web.xml
In this example, the web.xml file includes the following entries:
<?xml version="1.0"?> <!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> <!-- A demo servlet, add servlets below --> <servlet> <servlet-name>HelloServlet</servlet-name> <servlet-class>HelloWorldServlet</servlet-class> </servlet> <welcome-file-list> <welcome-file>index.html</welcome-file> </welcome-file-list> </web-app>
URLs for Invocation in OC4J
Assuming the preceding configuration, you could use the following URLs (specifying the appropriate port) to directly invoke the various pages.
To invoke the servlets:
http://scott-sun:port/migdemos/servlet/HelloWorldServlet http://scott-sun:port/migdemos/servlet/SessionServlet
(The <context-root> setting in application.xml and the servlet-webdir setting in orion-web.xml are relevant here.)
To invoke the JSP pages:
http://scott-sun:port/migdemos/jsps/Hello.jsp http://scott-sun:port/migdemos/jsps/snoop.jsp
To invoke the index HTML pages:
http://scott-sun:port/migdemos/index.html http://scott-sun:port/migdemos/examples/index.html
In the Oracle9iAS Release 1 (1.0.2.2.x) OC4J security services, the prinicpals.xml file defines users and groups for mapping to roles defined in application deployment descriptors.
In Oracle9iAS Release 2 (9.0.2), security services are provided through the Java Authentication and Authorization Service (JAAS). For information about JAAS, see "Security Services Provided by Oracle9iAS JAAS" in the Oracle9iAS Security Guide.
The JAAS Admintool is provided for security administrators to manage users, realms, roles and policies. It has a command switch that migrates principals.xml to a JAAS realm. The syntax is:
java -jar jazn.jar -convert filename realm
where filename is the name and location of the OC4J principals.xml file and realm is the realm defined in the JAAS. For example:
java -jar jazn.jar -convert /home/config/principals.xml MyCompanyRealm
All permissions granted to a principals.xml group are granted to the JAAS role. Users that were deactivated are not migrated.
This section describes how to migrate SOAP applications from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle9iAS Release 2 (9.0.2).
SOAP is implemented as a servlet. A servlet delegates service invocations to user supplied implementation classes. In Oracle9iAS Release 1 (1.0.2.2.x), JServ was the default servlet engine. In Oracle9iAS Release 2 (9.0.2), OC4J is the servlet engine. To migrate SOAP applications, you must copy and re-packaging the service implementation classes and descriptors, and also consider the configuration aspects of the JServ and OC4J containers. (See "Migrating JServ to OC4J" for more information on JServ and OC4J configuration.)
Oracle9iAS Release 2 (9.0.2) contains empty (that is, containing no services) SOAP application and web application archives ready to install. These files are named soap.ear and soap.war, and are located in ORACLE_HOME/soap/webapps/soap.ear. The soap.war file is a copy of the WAR file contained in the soap.ear file.
The SOAP migration process involves inserting Oracle9iAS Release 1 (1.0.2.2.x) files into a copy of the empty SOAP application, and then deploying the application in OC4J. Files can be "inserted" in one of two ways:
jar -x to unpack the soap.ear and soap.war files into component directories, copying old files to the corresponding directories, then using jar -c to create new .ear and .war files.
jar -u to update the contents of the .war and .ear files without unpacking them.
Below are the steps in the migration process.
/soap/webapps/soap.ear and ORACLE_HOME_2/soap/webapps/soap.war to a convenient work directory (workdir, in this example).
/soap/webapps/soap/WEB-INF/classes into workdir/soap.war.
soap.jar and samples.jar from ORACLE_HOME_1/soap/webapps/soap/WEB-INF/lib into workdir/soap.war.
/soap/webapps/soap/WEB-INF/config/soapConfig.xml was never changed, go to step 6.
ORACLE_HOME_1/soap/webapps/soap/WEB-INF/config/soapConfig.xml, renaming it to soap.xml.
providerManager and serviceManager elements.
All of the code to be migrated is now in workdir/soap.jar.
workdir/soap.jar into workdir/soap.ear.
Perform the steps below to migrate Oracle Business Components for Java applications to Oracle9iAS Oracle9iAS Release 2 (9.0.2) using JServ. JServ is provided in Oracle9iAS Release 2 (9.0.2) for legacy use only, and is disabled by default. The default servlet container is OC4J.
If you want your business components applications to use OC4J, you must redeploy them from Oracle9i JDeveloper. For information on deployment in Oracle9i JDeveloper, see the JDeveloper documentation.
Follow this procedure to migrate BC4J applications. Instructions are included for configuring JServ in Oracle9iAS Release 2 (9.0.2).
wrapper.classpath=path, where path is the path to the JAR file.
jserv.conf file in ORACLE_HOME_2/Apache/Apache/conf/httpd.conf.
#include "/ORACLE_HOME_2/Apache/Jserv/etc/jserv.conf"
jserv.conf to set directives as appropriate for how you want to use JServ. (jserv.conf contains Include directives for mod_jserv and mod_oprocmgr, an Oracle module that provides process management and load balancing services.)
Oracle HTTP Server Administration Guide in the Oracle9i Application Server documentation library.
See Also:
/Apache/Jserv/etc/jserv.properties file, if needed.
/Apache/Jserv/etc/zone.properties file, if needed.
You can specify that some applications execute on JServ and some on OC4J. Suppose you have these URLs:
/application1/file1.jsp to execute on JServ, and
/application2/file2.jsp to execute on OC4J.
You must rewrite the URL for application1.
/Apache/Apache/conf/httpd.conf and ensure that the following directives are active (uncommented) and present:
LoadModule rewrite_module libexec/mod_rewrite.so RewriteEngine on
ORACLE_HOME_2/Apache/jsp/conf/ojsp.conf to add these directives:
RewriteRule /application1/(.*)/(.*)\.jsp$ /application1/$1/$2.jsp1 ApJServAction .jsp1 /servlets/oracle.jsp.JspServlet
ApJServAction .jsp /servlets/oracle.jsp.JspServlet
/Apache/Jserv/etc/jserv.conf and mount /servlets to the JVM that will service the JSP requests. Use the ApJServMount or ApJServGroupMount directive (depending on how the JServ processes are started).
|
 Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|