| Oracle® Application Server Upgrade and Compatibility Guide 10g Release 3 (10.1.3.1.0) B31015-01 |
|
 Previous |
 Next |
| Oracle® Application Server Upgrade and Compatibility Guide 10g Release 3 (10.1.3.1.0) B31015-01 |
|
Previous |
Next |
If you are upgrading from Oracle Application Server 10g (9.0.4) or 10g Release 2 (10.1.2), Oracle Application Server 10g Release 3 (10.1.3.1.0) introduces support for the the latest J2EE 1.4 technologies and application programming interfaces (APIs). These new capabilities allow you 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.1.0).
Note that many of these features were introduced with Oracle Application Server 10g Release 3 (10.1.3.0.0), but they also apply to 10g Release 3 (10.1.3.1.0).
This chapter includes the following sections:
Oracle Application Server 10g Release 3 (10.1.3.1.0) 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.1.0)
|
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.1.0)
For complete information about deploying your J2EE applications on 10g Release 3 (10.1.3.1.0), see the Oracle Containers for J2EE Deployment Guide.
For a step-by-step example of upgrading to 10g Release 3 (10.1.3.1.0) and redeploying the FAQApp sample application on 10g Release 3 (10.1.3.1.0), see Appendix A, "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.1.0):
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.0.0) introduced significant improvements in the areas of class loading and shared library support. These improvements are also available in 10g Release 3 (10.1.3.1.0).
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.0.0) and 10g Release 3 (10.1.3.1.0), 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.1.0):
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.0.0). This applies to 10g Release 3 (10.1.3.1.0) as well.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.
In previous versions of Oracle Containers for J2EE, newly created OC4J instances included a predefined Web site named http-web-site. For 10g Release 3 (10.1.3.0.0) and 10g Release 3 (10.1.3.1.0), the http-web-site has been removed.
As as a result, if you are deploying an application that was previously configured to bind to the http-web-site, you must modify the application to bind to the new default-web-site, or create a new Web site for the OC4J instance called http-web-site.
The configuration file for the default-web-site is stored in the following location within a 10g Release 3 (10.1.3.1.0) Oracle home:
On UNIX systems:
ORACLE_HOME/j2ee/OC4J_instance/config/default-web-site.xml
On Windows systems:
ORACLE_HOME/j2ee/OC4J_instance/config/default-web-site.xml
In this example, replace OC4J_instance with the name of the OC4J instance.
|
See Also: "New and Changed Features in OC4J" in the Oracle Containers for J2EE Configuration and Administration Guide |
The following sections provide information about using data sources in 10g Release 3 (10.1.3.1.0):
Converting data-sources.xml to the New 10g Release 3 (10.1.3.1.0) Format
Using Oracle JDBC-OCI Drivers with 10g Release 3 (10.1.3.1.0)
The following OC4J Data Source features and behaviors were introduced in the 10g Release 3 (10.1.3.0.0) release and are also available for 10g Release 3 (10.1.3.1.0):
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.0.0) introduced a new format for the data-sources.xml file, which defines the data sources for your application, OC4J instance, or group. This change also applies to 10g Release 3 (10.1.3.1.0).
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.
Note that when you use the Application Server Control Console to create or modify your OC4J data sources, Application Server Control saves the updates in the data-sources.xml using the new format.
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.1.0) 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.1.0). For complete information on creating Web services for 10g Release 3 (10.1.3.1.0), 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.1.0) to recreate Web services that were originally created against 10g (9.0.4) or 10g Release 2 (10.1.2):
Assembling Web Services From Java Classes in 10g Release 3 (10.1.3.1.0)
Developing Database Web Services in 10g Release 3 (10.1.3.1.0)
If you re-create your Web services for the 10g Release 3 (10.1.3.1.0), note that the Web Services Assembler tool for 10g Release 3 (10.1.3.1.0) 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.1.0). 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.1.0), 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.1.0) 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.1.0).
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.1.0), 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.1.0) database Web service, the Web service will not be interchangeable between 10g Release 3 (10.1.3.1.0) 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.1.0). 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.1.0), 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 |
If you have existing clients for your 10g Release 2 (10.1.2) Web service, and you want to keep the same contract (or WSDL file), you can generate the 10g Release 3 (10.1.3.1.0) Web service by assembling the Web service from the WSDL file, and then reuse the implementation code for your Web service. This is also known as top down Web service generation.
For detailed information about top down Web service assembly, see "Assembling a Web Service from WSDL" in the Oracle Application Server Web Services Developer's Guide.
The following sections provide information about using JMS 10g Release 3 (10.1.3.1.0):
Using the JMS Connector Provided by 10g Release 3 (10.1.3.1.0)
Using the Application Server Control Console to Configure OEMS JMS
Additional Data Source Requirement for OEMS JMS Database Applications
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.
The following sections describe the JMS Connector resource adapter available for Oracle Application Server 10g Release 3 (10.1.3.1.0):
Oracle Application Server 10g Release 3 (10.1.3.1.0) 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.02b.
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.
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.0.0) and that are still available in 10g Release 3 (10.1.3.1.0). 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 |
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.1.0), OEMS JMS In-Memory and File-Based options cannot be used for global transactions without the JMS Connector.
If you do not modify your deployment descriptors to use OEMS JMS In-Memory and File-Based options, Oracle provides a JMS property you can use as a temporary solution until you are able to update your deployment descriptors.
If the oc4j.jms.pseudoTransactionEnlistment property is set to TRUE, then all JMS Sessions (XA and non-XA) will be enlisted into global transactions, which is in violation of J2EE 1.4 and associated specs. This allows pre-existing applications that are using unsupported, non-compliant JMS semantics to continue to run, even after the implementation of fully JMS-compliant behavior in 10g Release 3 (10.1.3.1.0).
Note that enabling this flag will have uncertain results in other JMS applications that expect compliant behavior (for example, Oracle BPEL Process Manager, Oracle Enterprise Service Bus, and other SOA applications).
You can modify JMS properties by using the using the JMSAdministrator MBean, which is available from the System MBean Browser in the Application Server Control Console.
|
See Also: "About the MBean Browser" in the Application Server Control online help"JMS Configuration Properties" in the Oracle Containers for J2EE Services Guide |
Unlike the Application Server Control Console in 10g (9.0.4) and 10g Release 2 (10.1.2), you can use the 10g Release 3 (10.1.3.1.0) 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.0.0) introduced 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. These changes also apply to 10g Release 3 (10.1.3.1.0).
If you redeploy a JMS application on 10g Release 3 (10.1.3.1.0), 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
|
See Also: "Configuration Elements" in the Oracle Containers for J2EE Services Guide |
When you redeploy JMS applications on Oracle Application Server 10g Release 3 (10.1.3.1.0), 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 the section, "Required Class Path for Application Clients Using Direct 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 the section, "Required Class Path for Application Clients Using Direct OEMS JMS Database Lookup," in the Oracle Containers for J2EE Services Guide.
Refer to the "OEMS JMS Database Certification Matrix" in theOracle Containers for J2EE Services Guide for information on which versions of the Oracle database work with the Oracle Application Server when the OJMS client is running in OC4J.
If you are deploying an OEMS JMS Database application on Oracle Application Server 10g Release (10.1.3), note that you must verify that the manage-local-transactions attribute in the data-sources.xml file is set to false.
The following example shows the managed-data-source element in the data-sources.xml file with the required attribute for OEMS JMS Database applications:
<managed-data-source name="OracleDS" connection-pool-name="Example Connection Pool" jndi-name="jdbc/OracleDS" *manage-local-transactions="false"*/>.
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.
|
See Also: "OC4J Transaction Support" in the Oracle Containers for J2EE Services Guide |
The following sections highlight key changes to the OC4J JTA Support for 10g Release 3 (10.1.3.0.0). These changes also apply to 10g Release 3 (10.1.3.1.0). You should review these sections before deploying your existing 10g (9.0.4) or 10g Release 2 (10.1.2) J2EE applications on 10g Release 3 (10.1.3.1.0):
Oracle Application Server 10g Release 3 (10.1.3.0.0) introduced 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," and it is also available in 10g Release 3 (10.1.3.1.0).
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.0.0) introduced JTA transaction propagation. Transaction context propagation makes it possible for multiple OC4J instances to participate in a single global transaction. This feature is also available in 10g Release 3 (10.1.3.1.0).
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.0.0) introduced several new features and changes to the OC4J Remote Method Invocation (RMI) implementation. These changes are also supported by 10g Release 3 (10.1.3.1.0). 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.1.0) and the older 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 Oracle Application Server 10g (9.0.4) and 10g Release 2 (10.1.2), 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.1.0). 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.0.0) introduced a new implementation for ORMI tunneling through HTTP, which also applies to 10g Release 3 (10.1.3.1.0). 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.1.0) 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.0.0) introduced several new features and changes to JNDI. These changes also apply to 10g Release 3 (10.1.3.1.0). 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.1.0), 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.factory.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 browse the JNDI context for a selected application with the 10g Release 3 (10.1.3.1.0) 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.1.0):
The security features of Oracle Application Server and Oracle Containers for J2EE have been updated significantly since Oracle Application Server 10g (9.0.4) and 10g Release 2 (10.1.2). Additional changes were implemented for 10g Release 3 (10.1.3.1.0).
Before you redeploy your applications on 10g Release 3 (10.1.3.1.0), be sure to review the changes to the OC4J security features for security changes that could affect your application deployments.
Refer to the Oracle Containers for J2EE Security Guide for complete information about the security changes introduced in Oracle Application Server 10g Release 3 (10.1.3.0.0) and 10g Release 3 (10.1.3.1.0).
The following sections provide an overview of the significant changes introduced for the 10g Release 3 (10.1.3.0.0) and 10g Release 3 (10.1.3.1.0):
This section notes changes and updated deprecation notices for the OC4J 10.1.3.1 implementation. Also review the section that follows, Section C.9.1.1, "Changes in Release 10.1.3.1".
Note the following key additions in the OC4J 10.1.3.1 implementation:
Identity management framework to support heterogeneous third-party identity management systems
Java SSO, an alternative single sign-on solution packaged with OC4J that does not require additional infrastructure (such as Oracle Single Sign-On and Oracle Access Manager single sign-on do) and decouples OC4J from any identity management system that you use
DBTableOraDataSourceLoginModule to replace DataSourceUserManager functionality. For more information, see Section C.9.4, "New DBTableOraDataSourceLoginModule OC4J Login Module".
A new user and role API framework, particularly for use with supported LDAP servers. This includes replacement functionality for the deprecated UserManager, User, and Group classes
In addition, note the following changes:
The JDK-default JSSE implementation is now the default SSL implementation for HTTPClient. (This is a step toward deprecating OracleSSL, the previous default SSL implementation, for use with HTTPClient.)
Note the following deprecations in the OC4J 10.1.3.1 implementation:
The com.evermind.security package and its classes are deprecated. They will no longer be supported in the 11g release.
UserManager class: Use JAAS custom login modules instead of custom com.evermind.security.UserManager implementations.
User class: Use standard JAAS APIs instead.
Group class: Use standard JAAS APIs instead.
The XMLUserManager class and its data store, principals.xml, are deprecated. They will no longer be supported in the 11g release. For more information, see Section C.9.2, "Converting principals.xml to the New JAAS Security Model".
The following security features and enhancements were added for the OC4J 10.1.3.0.0 implementation:
Support for the COREid Access (now Oracle Access Manager) security provider
Support for the LDAP-based provider in standalone OC4J
Digest authentication support, and client certification authentication and authorization support
Implementation of the Java Authorization Contract for Containers (JSR-115)
JAAS integration with EJBs
ORMI enhancements for SSL (ORMIS)
Support for subject propagation (with ORMI or ORMIS)
JMX and MBeans support (JSR-77) for security configuration
New OC4J user and role accounts
Enhanced Java 2 security support
Web services security
In addition, note the following changes since the OC4J 10.1.2 implementation:
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 OC4J 10.1.3.x implementations.
The instance-level 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 data store, principals.xml, are deprecated and will no longer be supported at a future release. We strongly encourage you to migrate your existing applications. For more information, see Section C.9.2, "Converting principals.xml to the New JAAS Security Model".
Custom UserManager classes are still supported at this release, but will be deprecated at a future release. We recommend that you use JAAS custom login modules instead of custom com.evermind.security.UserManager implementations.
For the Oracle Identity Management security provider, the application realm and external realm are deprecated.
The external.synchronization property is no longer supported.
The default setting of the jaas.username.simple property is now "true"; in the 10.1.2 implementation, the default setting was "false". This now means that by default, realm names are omitted from the names of authenticated principals returned by such methods as getUserPrincipal() and getRemoteUser() for servlets, and getCallerPrincipal() for EJBs.
There have been some OC4J account name changes: the admin account is now oc4jadmin; the administrators role is now oc4j-administrators; the jmx-users role is now oc4j-app-administrators. For the file-based provider in standalone OC4J, oc4jadmin is initially deactivated. See Section C.9.5, "New Default OC4J Administration Users and Roles".
Required OC4J accounts are created automatically in Oracle Internet Directory when you associate an OC4J instance with an OID instance. See "Required Accounts Created in Oracle Internet Directory" in the Oracle Containers for J2EE Security Guide.
Setting LD_LIBRARY_PATH is no longer necessary in 10.1.3.x implementations.
The jazn.debug.log.enable flag is no longer supported for logging. Use regular OC4J logging features. See "Logging" in the Oracle Containers for J2EE Security Guide.
For Oracle Application Server 10g Release 3 (10.1.3.1.0), the XMLUserManager class and its datastore, principals.xml, are supported, 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.1.0) 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.1.0) supports the use of Oracle Internet Directory as a security provider and Oracle Single Sign-On for the applications you deploy.
Before you deploy an application that requires Oracle Internet Directory or Oracle Single Sign-On, see "Oracle Identity Management" in the Oracle Containers for J2EE Security Guide for complete instructions.
Note that when you associate an OC4J instance with an Oracle Internet Directory instance, a set of required OC4J accounts are created automatically in Oracle Internet Directory. For more information, see "Required Accounts Created in Oracle Internet Directory" in the Oracle Containers for J2EE Security Guide.
For 10g Release 3 (10.1.3.1.0), the OC4J implementation supplies a login module you can use if you have a user identity store in a database:
oracle.security.jazn.login.module.db.DBTableOraDataSourceLoginModule
This replaces previous functionality of the following class, now deprecated (but still supported for backward compatibility):
com.evermind.sql.DataSourceUserManager
The new login module also replaces some authentication functionality of the deprecated com.evermind.security.User class.
Once you have created your database schema and an Oracle datasource to connect to the database, you are ready to configure the login module.
DBTableOraDataSourceLoginModule supports a number of options for specifying such items as data location (table and column names) and password encryption. You can set these options through Application Server Control or the OracleAS JAAS Provider Admintool, with the settings being reflected in the <jazn-loginconfig> element of the system-jazn-data.xml file.
|
See Also: "DBTableOraDataSourceLoginModule" in the Oracle Containers for J2EE Security Guide |
Refer to the following sections for information about the new OC4J default administrator accounts available with 10g Release 3 (10.1.3.0.0) and 10g Release 3 (10.1.3.1.0):
Oracle Application Server 10g Release 3 (10.1.3.0.0) and 10g Release 3 (10.1.3.1.0) introduce changes to the following default OC4J users and roles that were previously defined by default in Oracle Application Server 10g (9.0.4) and 10g Release 2 (10.1.2):
The admin account is now oc4jadmin
The administrators role is now oc4j-administrators
The jmx-users role is now oc4j-app-administrators
If any of your 10g (9.0.4) or 10g Release 2 (10.1.2) applications depend upon the admin account or the administrators role, you can map your application-specific security roles to the new OC4J default security roles.
You can perform this task from the Application Server Control Console during the deployment of your application, or you can modify the appropriate orion-application.xml, orion-ejb-jar.xml, or orion-web.xml configuration file after deployment.
The helloworld EJB sample application, available on the Oracle Technology Network, is an example of an application that depends upon the admin user account. The application was designed to work with the default administration users and roles defined for OC4J 10g (9.0.4) and 10g Release 2 (10.1.2).
As a result, if you deploy the helloworld application on 10g Release 3 (10.1.3.1.0) without mapping the security roles, you will be unable to log in to the sample application. To remedy this problem, map the users role of the helloworld application to the oc4j-administrators role available in 10g Release 3 (10.1.3.1.0).
|
Note: The following procedure assumes you have a copy of thehelloworld.ear application archive available on your local hard disk. The sample application is available from the Enterprise JavaBeans Samples page on the Oracle Technology Network. |
If you perform the following steps, then you can log in to the helloworld application using the 10g Release 3 (10.1.3.1.0) oc4jadmin account.
Task 1 Use Application Server Control to Map the Security Roles and Deploy the Application
Log in to the 10g Release 3 (10.1.3.1.0) Application Server Control Console and navigate to the OC4J home page.
Click Applications to display the OC4J Applications page.
Click Deploy to start the Application Server Control deployment wizard.
Follow the instructions on the screen and proceed through the wizard until Application Server Control displays the Deployment Settings page.
Use the Map Security Roles task to map the helloworld security roles to the security roles defined for the 10g Release 3 (10.1.3.1.0) OC4J instance:
On the Deployment Tasks page, click the Go to Task icon for the Map Security Roles deployment task.
On the Map Security Roles page, notice that a security role called users is defined for the helloworld application. The users role is configured for the hello EJB module, as well as for the helloworld web application.
Click the Map Role icon for the hello EJB module.
Application Server Control displays the Map Security Role page (Figure C-1).
Select Map selected users and groups to this role.
In the Map Roles to Groups section of the page, enter oc4j-administrators in the Group field and click Add.
The oc4j-administrators role appears in the table above the field. This indicates that Application Server Control will map the users role, which is defined for the application, to the oc4jadmin-administrators role, which is defined in the system-jazn-data.xml of the 10g Release 3 (10.1.3.1.0) OC4J instance.
Figure C-1 Deployment Settings: Map Security Roles Page
Click Continue to return to the Map Security Role page.
Repeat steps b through e for the helloworld web application.
Click OK to return to the Deployment Tasks page.
Click Deploy to deploy the helloworld application.
Application Server Control shows the status of the deployment and displays a success message when the deployment is complete.
Click Return to return to the OC4J Applications page.
Task 2 Verify that Security Roles are Mapped Correctly
Click the name of the helloworld application in the list of deployed applications.
Application Server Control displays the Application Home page for the helloworld application.
Click helloworld-web to display the helloworld web application page.
Test the Web module to verify that you can log into the helloworld application using the oc4jadmin user credentials:
Click the Test Web Module icon to display the Test Web module page.
Select a valid listener from the table and click Test Web Module.
On the first test page, click the word here to display the login prompt for the helloworld application.
Enter oc4jadmin and the password you defined for the account during the Oracle Application Server installation.
If the security roles are mapped correctly, the helloworld application displays the following, which confirms that the application is working successfully:
Hello James Earl
Task 3 Verify the Changes Made to the orion-web.xml Configuration File
Return to the Web Module page for the helloworld-web Web module.
Click Administration to display the list of tasks you can perform for a selected Web module.
Click the task icon for the View Proprietary Deployment Descriptor task.
Scroll through the orion-web.xml configuration file and locate the following entry:
<security-role-mapping name="users"> <group name="oc4j-administrators" /> </security-role-mapping>
This is the entry that is added when you map the users security role to the oc4j-administrators group defined by the system-jazn-data.xml file for the 10g Release 3 (10.1.3.1.0) OC4J instance.
|
See Also: "Overview of Security Role Mapping" in the Oracle Containers for J2EE Security Guide |
Use the following sections to take advantage of Oracle TopLink for your 10g Release 3 (10.1.3.1.0) applications:
In Oracle Application Server 10g (9.0.4) and 10g Release 2 (10.1.2), the default persistence manager was Orion CMP. In 10g Release 3 (10.1.3.0.0) and 10g Release 3 (10.1.3), OC4J is configured by default to use Oracle TopLink as its default persistence manager.
|
Note: OrionCMP was deprecated in 10g Release 3 (10.1.3.0.0) 10g Release 3 (10.1.3.1.0), and it will be desupported in future versions of Oracle Application Server. |
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.
