|
Oracle® Application Server Upgrade and Compatibility Guide
10g Release 3 (10.1.3) Part No. B25585-01 |
|
 Previous |
 Next |
|
Oracle® Application Server Upgrade and Compatibility Guide
10g Release 3 (10.1.3) Part No. B25585-01 |
|
|
Previous |
Next |
Oracle Application Server 10g Release 3 (10.1.3) introduces support for the the latest J2EE 1.4 technologies and APIs. As a result, you can use this release to deploy J2EE applications that take advantage of the newest J2EE features and capabilities.
This chapter provides important considerations to review before you deploy your Oracle Application Server 10g (9.0.4) and 10g Release 2 (10.1.2) applications on Oracle Application Server 10g Release 3 (10.1.3).
This chapter includes the following sections:
Oracle Application Server 10g Release 3 (10.1.3) supports functionality outlined in the J2EE Application Deployment API (JSR-88), which defines a standard API for configuring and deploying J2EE applications and modules into a J2EE-compatible environment.
Specifically, the JSR-88 compliant features in OC4J provide the ability to:
Start an application immediately upon deployment, making it available to clients
Stop an application, making it unavailable to clients
Undeploy an application or module
Redeploy an application or module, essentially updating the currently installed application with an updated version
Create a deployment plan containing the aggregated OC4J-specific configuration data needed to deploy a component into OC4J.
|
See Also: "Working With Deployment Plans" in the Oracle Containers for J2EE Deployment Guide for details on the JSR-88 implementation in OC4J. |
To deploy an application, you use one of two management tools:
The new Application Server Control Console provided with 10g Release 3 (10.1.3)
|
See Also: "Introduction to Administration Tools" in the Oracle Application Server Administrator's Guide |
The admin_client.jar command-line utility, which is new for 10g Release 3 (10.1.3)
For complete information about deploying your J2EE applications on 10g Release 3 (10.1.3), see the Oracle Containers for J2EE Deployment Guide.
For a step-by-step example of upgrading to 10g Release 3 (10.1.3) and redeploying the FAQApp sample application on 10g Release 3 (10.1.3), see Chapter 2, "Step-By-Step Upgrade Examples".
The following sections describe general information that you should consider before redeploying your applications on 10g Release 3 (10.1.3):
New Location for JavaServer Pages (JSP) Standard Tag Libraries (JSTL)
Oracle JSP Markup Language (JML) Tag Library No Longer Supported
Oracle Application Server 10g Release 3 (10.1.3) offers significant improvements in the areas of class loading and shared library support.
For complete information about how you can take advantage of these new features, see "Utilizing the OC4J Class Loading Framework" in the Oracle Containers for J2EE Developer's Guide.
That chapter in the Oracle Containers for J2EE Developer's Guide contains an overview of the new class loading framework, information about using shared libraries, as well as classloading best practices and troubleshooting information.
In previous versions of Oracle Application Server, the JavaServer Pages (JSP) Standard Tag Libraries were automatically available as part of the OC4J instance. However, application developers often want to include their own custom version of the libraries, or a newer version of the tag libraries. In previous versions of OC4J, errors could result if you included custom tag libraries in addition to the pre-packaged libraries.
As a result, for 10g Release 3 (10.1.3), the tag libraries (standard.jar and jstl.jar) are now installed in a new location in the Oracle Application Server Oracle home. If your application depends upon these libraries, you must now include the tag libraries in the WEB-INF/lib directory of your application EAR file.
Specifically, the libraries are now installed in the following directory. You can copy these libraries from this location and include them into your application before you deploy the application on 10g Release 3 (10.1.3):
1013_ORACLE_HOME/j2ee/home/default-web-app/WEB-INF/lib
|
See Also: "Support for the JavaServer Pages Standard Tag Library" in the Oracle Containers for J2EE JSP Tag Libraries and Utilities Reference |
The Oracle JSP Markup Language (JML) tag library is officially de-supported as of Oracle Application Server 10g Release 3 (10.1.3).Developers are advised to use tags provided with the JavaServer Pages Standard Tag Library (JSTL), which provide similar functionality in a standardized implementation.
For more information, see Chapter 2, "Support for the JavaServer Pages Standard Tag Library" in the Oracle Containers for J2EE Support for JavaServer Pages Developer's Guide.
The following sections provide information about using data sources in 10g Release 3 (10.1.3):
The following OC4J Data Source features and behaviors are new for this release:
Data source configuration can be performed entirely in the Oracle Enterprise Manager 10g Application Server Control Console.
The OC4J Data Source types are managed data sources and native data sources, replacing emulated, non-emulated, and native.
New connection caching mechanism that is uniform across Oracle data sources and offers integrated Real Application Clusters (RAC) failover support.
|
See Also: "Data Sources" in the Oracle Containers for J2EE Services Guide"Managing Data Sources and JDBC Connection Pools" in the Application Server Control online help |
Oracle Application Server 10g Release 3 (10.1.3) introduces a new format for the data-sources.xml file, which defines the data sources for your application, OC4J instance, or group.
However, you can still use your existing data-source.xml files. OC4J will convert the data sources to the new format at runtime. Note, however, that if you deploy an EAR file that contains a data-sources.xml file in the previous format, OC4J will convert the data-sources.xml file that is expanded on disk. It will not modify the data-sources.xml file contained within the EAR file.
Alternatively, if you are using standalone OC4J, you can use the admin.jar utility to convert the data-sources.xml file to the new format.
|
Note: Theadmin.jar utility can only be used to manage a single OC4J instance in a standalone OC4J installation.
|
For more information, see "Converting Existing Data Sources to the New Configuration" in the Oracle Containers for J2EE Configuration and Administration Guide.
If your existing applications use the Oracle JDBC Oracle Call Interface (OCI) driver, be sure to review the section, "Oracle JDBC Drivers" in the Oracle Containers for J2EE Services Guide for information on configuration and upgrade requirements.
For backward compatibility, Oracle Application Server 10g Release 3 (10.1.3) includes the underlying software required to run 10g Release 2 (10.1.2) Web services. As a result, Web services applications designed and packaged to run with Oracle Application Server 10g (9.0.4) and 10g Release 2 (10.1.2) can be used without modification with Release 3.
However, there are significant advantages to recreating your Web services for 10g Release 3 (10.1.3). For complete information on creating Web services for 10g Release 3 (10.1.3), refer to the Oracle Application Server Web Services Developer's Guide.
In addition, refer to the following sections for specific considerations when using 10g Release 3 (10.1.3) to recreate Web services that were originally created against 10g (9.0.4) or 10g Release 2 (10.1.2):
If you re-create your Web services for the 10g Release 3 (10.1.3), note that the Web Services Assembler tool for 10g Release 3 (10.1.3) is now called wsa.jar, and it is not compatible with the Web Services Assembler tool used for previous releases (WebServicesAssembler.jar). Web services and clients created with wsa.jar will be different and incompatible with Web services created with WebServicesAssembler.jar.
|
See Also: "Using WebServicesAssembler" in the Oracle Application Server Web Services Developer's Guide |
If you created a Web service based on a Java class for Oracle Application Server 10g (9.0.4) or 10g Release 2 (10.1.2), you can do the same using the new Web Services Assembler (wsa.jar) available with 10g Release 3 (10.1.3). However, you must be aware of the following:
In 10g Release 2 (10.1.2), it was possible to publish a class by itself without providing an interface. In 10g Release 3 (10.1.3), you must provide an interface (specifically, the Service Endpoint Interface) to publish a class.
|
See Also: "Writing Java Class-Based Web Services" in the Oracle Application Server Web Services Developer's Guide |
The set of Java types that are natively supported has changed with the 10g Release 3 (10.1.3) release. For a list of the supported data types, see the JAX-RPC 1.1 specification available from the following URL:
http://java.sun.com/xml/jaxrpc/index.jsp
|
See Also: "Assembling a Web Service with Java Classes" in the Oracle Application Server Web Services Developer's Guide |
If you created database Web services with Oracle Application Server 10g (9.0.4) or 10g Release 2 (10.1.2), you can do the same using the new Web Services Assembler (wsa.jar) available with 10g Release 3 (10.1.3).
Note, however, that in 10g (9.0.4) and in 10g Release 2 (10.1.2), database Web services were always created using the RPC-encoded message format. In 10g Release 3 (10.1.3), database Web services are by default created using the document-literal message format.
|
See Also: "Supported Message Formats" in the Oracle Application Server Web Services Developer's Guide |
As a result, if you use the RPC-encoded message format when you create a 10g Release 3 (10.1.3) database Web service, the Web service will not be interchangeable between 10g Release 3 (10.1.3) and previous Oracle Application Server Web services clients.
Specifically, a Web service client written for a database Web service generated under 10g (9.0.4) or 10g Release 2 (10.1.2) will fail if you try to use it against a database Web service generated under 10g Release 3 (10.1.3). This will be true even if the PL/SQL structures have remained the same.One of the reasons for this is that the SQL collection type was mapped into a complex type with a single array property in 10g (9.0.4) and 10g Release 2 (10.1.2). In release 10g Release 3 (10.1.3), it is mapped directly into an array instead.If you regenerate the Web service client, you will have to rewrite the client code. This is because the regenerated code will now be employing an array[] instead of a BeanWrappingArray.
|
See Also: "Developing Database Web Services" in the Oracle Application Server Web Services Developer's Guide |
The following sections provide information about using JMS 10g Release 3 (10.1.3):
In past releases, Oracle used the terms "OracleAS JMS" and "OJMS" when describing the In-Memory, File-Based, and Database persistence options. "OracleAS JMS" referred to the In-Memory and File-Based options; "OJMS" referred to JMS interface to Streams Advanced Queuing (AQ).
For this release, the "OracleAS JMS" and "OJMS" nomenclature is not used. The "Oracle Enterprise Messaging Service (OEMS) JMS" reference is used instead. This change reflects the fact that Oracle offers a single Java Messaging Service (JMS) interface to the three message persistence options. As a result, you do not have to change your JMS application code if you decide to change message persistence between any of the three quality of service choices.
Oracle Application Server 10g Release 3 (10.1.3) provides a J2CA 1.5-compliant resource adapter called the JMS Connector that allows OC4J-managed applications to have a unified mechanism to access any JMS provider that implements JMS 1.1 or 1.2b.
Out-of-the-box, this release provides OracleASjms, which is an instance of the JMS Connector that is pre-configured for use with the OEMS JMS In-Memory and File-Based options.
Before you redeploy 10g (9.0.4) or 10g Release 2 (10.1.2) J2EE applications that use JMS in global transactions, you must modify the corresponding deployment descriptors to use OEMS JMS In-Memory and File-Based options via the JMS Connector. For 10g Release 3 (10.1.3), OEMS JMS In-Memory and File-Based options cannot be used for global transactions without the JMS Connector.
Oracle recommends that new JMS applications be deployed using the JMS Connector. The JMS Connector provides the new features introduced in 10g Release 3 (10.1.3). Oracle will continue to support JMS applications deployed using the older proprietary OC4J Resource Provider supported in Oracle Application Server 10g (9.0.4) and 10g Release 2 (10.1.2), but you are strongly encouraged to use the JMS Connector.
|
See Also: "JMS Connector" in the "Java Message Service (JMS)" chapter of the Oracle Containers for J2EE Services Guide |
Unlike previous versions of Oracle Application Server, you can use the 10g Release 3 (10.1.3) Application Server Control Console to manage the OC4J-provided OEMS In-Memory and File-Based resource provider. For example, you can use Application Server Control to create connection factories and destinations, as well as modify specific OEMS configuration properties.
Note that in the Application Server Control Console, the OEMS JMS In-Memory and File-Based resource provider is still referred to as the OracleAS JMS provider.
|
See Also: "Managing the OracleAS JMS Provider" in the Application Server Control online help |
Oracle Application Server 10g Release 3 (10.1.3) introduces additional elements to the jms.xml configuration file, as well as changes to the format of the jms.xml file so it is compliant with the latest schema.
If you redeploy a JMS application on 10g Release 3 (10.1.3), Oracle Application Server automatically rewrites the jms.xml file to use the new configuration file format and to add additional queues if they do not exist already.
Specifically, Oracle Application Server adds additional queues that are required by the scheduler and router, and one queue that is added for demonstration purposes. The new queues defined in the updated jms.xml file include:
jms/RAExceptionQueue
jms/events
jms/jobstore
jms/notifications
When you redeploy JMS applications on Oracle Application Server 10g Release 3 (10.1.3), note the following.
When using OEMS JMS In-Memory and File-Based options directly from an application client, the JAR files that must be included in the class path are listed in Table 3–5, "Client-side JAR Files Required for OEMS JMS In-Memory and File-Based Lookup" in the Oracle Containers for J2EE Services Guide.
When using OEMS JMS Database option directly from an application client, the JAR files that must be included in the class path are listed in Table 3-7, "Client-side JAR Files Required for OEMS JMS Database Lookup" in the Oracle Containers for J2EE Services Guide.
The Java Transaction API (JTA) is a specification developed by Sun Microsystems to provide support for global (distributed) transactions in the J2EE environment. Global transactions combine multiple enterprise systems - such as databases and message queues - into a single unit of work. The JTA maps the specifications based on the Open Group Distributed Transaction Processing model into the Java environment.
The following sections highlight key changes to the OC4J JTA Support for 10g Release 3 (10.1.3). You should review these sections before deploying your existing J2EE application on 10g Release 3 (10.1.3):
Oracle Application Server 10g Release 3 (10.1.3) introduces the Middle-Tier Two-Phase Commit (2PC) Coordinator that supports all XA-compatible resources, not just those from Oracle. This feature is referred to as a "heterogeneous middle tier coordinator".
As a result, you are encouraged to use this new 2PC coordinator, instead of the deprecated in-database two-phase commit coordinator.
|
See Also: "Middle-Tier Two-Phase Commit (2PC) Coordinator" in the Oracle Containers for J2EE Services Guide |
OC4J 10g Release 3 (10.1.3) introduces JTA transaction propagation. Transaction context propagation makes it possible for multiple OC4J instances to participate in a single global transaction.
Previous versions of Oracle Application Server did not support transaction propagation. As a result, when an OC4J instance that supports transaction propagation makes a remote method invocation on a bean that is deployed on an older version of OC4J that does not support transaction propagation, no transaction context is propagated.
|
See Also: "Transaction Propagation Between OC4J Processes Over ORMI" in the Oracle Containers for J2EE Services Guide |
Oracle Application Server 10g Release 3 (10.1.3) supports several new features and changes to the OC4J Remote Method Invocation (RMI) implementation. For more information, see the following sections:
Applying Compatibility Patches for 10g (9.0.4) and 10g Release 2 (10.1.2)
New System Property for Configuring ORMI Request Load Balancing
To use ORMI to invoke a method on a remote object when the invoking object and the invoked object are running on different OC4J versions, you must install a patch on the older version. This applies when the newer version is 10g Release 3 (10.1.3) and the olde version is 10g (9.0.4) or 10g Release 2 (10.1.2).
For more information, see "Compatibility Patches for 9.0.4.x and 10.1.2.x" in the Oracle Containers for J2EE Services Guide.
In previous releases, when two or more clients in the same process retrieved an InitialContext, you could use the dedicated.connection or dedicated.rmicontext properties to be sure that each client received its own InitialContext instead of a shared context. When each client had its own InitialContext, then the clients could be load balanced.
These properties are deprecated in 10g Release 3 (10.1.3). Instead, you should use the new oracle.j2ee.rmi.loadBalance system property to specify load balancing in an application cluster. This property can be set in the client's jndi.properties file or in a Hashtable in the client code. The values for this property are:
client — The client interacts with the OC4J process that was initially chosen at the first lookup (this is the default setting).
context — The client goes to a new server when a separate context is used (this is similar to the deprecated dedicated.rmicontext property).
lookup — The client goes to a new (randomly selected) server for every request.
Oracle Application Server 10g Release 3 (10.1.3) introduces a new implementation for ORMI tunneling through HTTP. For complete information, see "Configuring ORMI Tunneling through HTTP" in the Oracle Containers for J2EE Services Guide.
Oracle Application Server 10g Release 3 (10.1.3) supports the use of Secure Socket Layer (SSL) for RMI connections. Complete instructions for configuring RMIS for your OC4J instances is included in the Oracle Containers for J2EE Security Guide.
Besides securing the RMI connections for your deployed applications, you can also secure the RMI management connections between the Administration OC4J instance (which is used to deploy the Application Server Control Console) and the other OC4J instances you are managing. For more information, see "Configuring Security for the Application Server Control Console" in the Oracle Application Server Administrator's Guide.
Oracle Application Server 10g Release 3 (10.1.3) introduces several new features and changes to JNDI for this release. For a complete list of the new and changed JNDI features, see "Oracle JNDI" in the Oracle Containers for J2EE Services Guide.
In particular, before you deploy your J2EE applications on 10g Release 3 (10.1.3), review the following sections:
JNDI-Related MBeans Now Available in the Application Server Control Console
Browsing the JNDI Context in the Application Server Control Console
Oracle Application Server 10g (9.0.4) and 10g Release 2 (10.1.2) package names for OC4J initial context factories are deprecated. They will no longer be supported in future releases. Specifically, the following context factories are deprecated:
com.evermind.server.rmi.RMIInitialContextFactory com.evermind.server.ApplicationClientInitialContextFactory com.oracle.iiop.server.IIOPInitialContextFactory
Instead, you should use the following settings when using the java.naming.factor.initial property:
oracle.j2ee.rmi.RMIInitialContextFactory oracle.j2ee.naming.ApplicationClientInitialContextFactory oracle.j2ee.iiop.IIOPInitialContextFactory
|
See Also: "Initial Context" in the Oracle Containers for J2EE Services Guide |
The following JNDI-related MBeans are now registered with OC4J and are available for use within the MBean browser in the Application Server Control Console:
JNDIResource
JNDINamespace
|
See Also: "About the MBean Browser" in the Application Server Control online help |
It is now possible to configure JNDI to perform inter-application lookups. This in contrast to the default behavior, where lookups within an application are bound to be available within the current application's namespace.
Note that for global lookup to work properly, the target application's classes must be in the classpath of the application attempting the lookup.
|
See Also: "Configuring JNDI for Deployment" in the Oracle Containers for J2EE Services Guide |
You can now browse the JNDI context for a selected application with the 10g Release 3 (10.1.3) Application Server Control Console.
To browse the JNDI context, select the JNDI Browser task on the OC4J Administration page in the Application Server Control Console.
|
See Also: "Browsing the JNDI Namespace for an OC4J Instance" in the Application Server Control online help |
Review the following sections for information on providing security for the J2EE applications you deploy on 10g Release 3 (10.1.3):
Before you redeploy your applications on 10g Release 3 (10.1.3), consider the following changes in the OC4J security features for this release:
There is a new consolidated "JAAS mode" for authorization, for both servlets and EJBs. This replaces previous runas-mode and dosasprivileged-mode functionality for servlets, and USE_JAAS functionality (introduced in preliminary 10.1.3 releases) for EJBs. The previous functionality is supported but deprecated in the OC4J 10g Release 3 (10.1.3) implementation.
The jazn-data.xml configuration file used in previous releases to store user and role configuration (for the file-based provider), policy configuration (for the file-based, external LDAP, or custom security provider), and login module configuration (for all security providers) has been renamed system-jazn-data.xml. However, an application can optionally use an application-specific jazn-data.xml repository file to store user and role configuration for the file-based provider.
The XMLUserManager class and its datastore, principals.xml, are still supported for this release, but you are strongly advised to migrate to the new JAAS Security model. The principals.xml file will no longer be supported in future releases.
Most of the classes in the com.evermind package have been replaced by oracle.j2ee. Although the com.evermind.* classes continue to exist, they are deprecated; Oracle encourages you to move your applications to oracle.j2ee.* as soon as possible.
The two exceptions are the following classes in the com.evermind package, which will be moved to the oracle.j2ee package in a future release:
com.evermind.server.rmi.RMIPermission com.evermind.server.AdministrationPermission
Custom UserManager classes are supported in this release, but will be unsupported in future releases.
|
See Also: "Standard Security Concepts" in the Oracle Containers for J2EE Security Guide |
For Oracle Application Server 10g Release 3 (10.1.3), the XMLUserManager class and its datastore, principals.xml, are supported in this release, but you are strongly encouraged to migrate to the new JAAS security model.
If an application that you want to redeploy on 10g Release 3 (10.1.3) was previously using the XMLUserManager class, you can use the JAZN Admintool to migrate the data in the principals defined in the principals.xml file to the new JAAS security model.
For more information, see "Migrating Principals from the principals.xml File" in the Oracle Containers for J2EE Security Guide.
Oracle Application Server 10g Release 3 (10.1.3) supports the use of Oracle Internet Directory as a security provider and OracleAS Single Sign-On for the applications you deploy.
Before you deploy an application that requires Oracle Internet Directory or OracleAS Single Sign-On, see "Oracle Identity Management Security Provider" in the Oracle Containers for J2EE Security Guide for complete instructions.
Use the following sections to take advantage of Oracle TopLink for your 10g Release 3 (10.1.3) applications:
In previous releases, the default persistence manager was Orion CMP. In 10g Release 3 (10.1.3), OC4J is configured by default to use Oracle TopLink as its default persistence manager.
As a result, before you redeploy your EJB applications that use Orion CMP, you must migrate persistence configuration from your original orion-ejb-jar.xml file to the toplink-ejb-jar.xml file.
Oracle provides a TopLink migration tool that you can use to automate this migration.
|
See Also: "Migrating OC4J Orion Persistence to OC4J TopLink Persistence" in the Oracle TopLink Developer's Guide |
If you have used Oracle TopLink with previous versions of Oracle Application Server, you can migrate your existing Oracle TopLink projects to TopLink 10g Release 3 (10.1.3).
For more information, see "Migrating to 10g Release 3 (10.1.3)" in the Oracle TopLink Getting Started Guide.
