|
|
This Oracle Service Bus Upgrade Guide includes the following sections:
For a description of what’s new in the latest version of Oracle Service Bus, see the Oracle Service Bus Release Notes.
| Caution: | Uninstall of Oracle Service Bus 10g Release 3 Maintenance Pack 1 is not supported. If after upgrading to Maintenance Pack 1 you want to revert to your previously installed version of Oracle Service Bus, you must restore your Oracle Service Bus environment from backup. |
You can upgrade AquaLogic Service Bus (ALSB) configurations from versions 2.5, 2.6, 2.6RP1, or 3.0 directly to Oracle Service Bus version 10g Release 3 Maintenance Pack 1 (10.3.1).
You cannot upgrade ALSB versions 2.0 and 2.1 to Oracle Service Bus version 10g Release 3 (10.3.1), directly. You must first upgrade ALSB versions 2.0 and 2.1 to one of ALSB versions 2.5, 2.6, 2.6RP1, or 3.0 and then upgrade to Oracle Service Bus version 10g Release 3 Maintenance Pack 1 (10.3.1) according to the instructions in this guide.
Upgrade involves two fundamental processes:
Product upgrade involves installing the latest version of Oracle Service Bus, which includes the latest development and run-time tooling. After installation, new resources are available for updating your existing Oracle Service Bus domains.
After you install the latest version of Oracle Service Bus, you can upgrade your domains with the latest Oracle Service Bus functionality.
Automated in-place upgrade of pre-Oracle Service Bus 10gR3 domains is not supported; only a Migration Upgrade method is supported. That is, you must create a new domain with the latest version of Oracle Service Bus, then import a configuration that was exported from an ALSB 2.5, 2.6, 2.6RP1, or 3.0 domain into the newly created Oracle Service Bus domain. In effect, you move the configuration from the old ALSB domain to the new Oracle Service Bus domain.
The upgrade to new Oracle Service Bus domains is supported for both clustered and non-clustered domains.
Before starting the upgrade process, please read Upgrade Considerations.
Table 1 identifies the version of WebLogic Server on which each version of ALSB or Oracle Service Bus runs.
This guide contains the following upgrade paths:
If you are already using Oracle Service Bus 10g Release 3, this section describes the steps for upgrading your product and domains to Oracle Service Bus 10g Release 3 Maintenance Pack 1.
Perform the following steps to upgrade the Oracle Service Bus product.
Your domain JMS configurations determine which of the following set of instructions you will use to upgrade your domains:
Follow these domain upgrade instructions for each domain that does not employ JMS resources with connection factories targeted to subdeployments.
Perform the following steps for each domain to be upgraded.
Follow these domain upgrade instructions for each domain that employs JMS resources with connection factories targeted to subdeployments.
Using Oracle Smart Update tool, apply the following public patch to your Oracle Service Bus installation: 3YG8.
Perform the following steps for each domain to be upgraded:
DOMAIN/bin/setDomainEnv.cmd/sh command.ALSB_HOME/common/upgrade.
Linux/Solaris: java weblogic.WLST ./upgradeDomain.py
Windows: java weblogic.WLST upgradeDomain.py
All migration steps are manual; no wizard is provided to facilitate the migration of an ALSB 2.5, 2.6, 2.6RP1, or 3.0 domain to an Oracle Service Bus 10g Release 3 Maintenance Pack 1 (10.3.1) domain. To upgrade an ALSB domain, complete the steps described in this section.
After performing the following steps, review the relevant information in Upgrade Considerations. Use Table 3 for guidance on upgrade considerations for your current version of AquaLogic Service Bus.
Use the ALSB Administration Console to export the ALSB 2.5, 2.6, 2.6RP1, or 3.0 configuration that you want to upgrade. To do so, log on as Administrator, and select Export Resources from the System Administration panel in the Console. For information about exporting ALSB configurations, see the appropriate Using the ALSB Console document:
You can also export configurations using the ALSBConfigurationMBean for
3.0,
2.6, and
2.5. For information, see the appropriate ALSB Deployment Guide: “Using the Deployment APIs” for
3.0,
2.6, and
2.5.
| Note: | In most cases, you cannot export WebLogic Server resources, such as the JMS resources, SNMP trap settings, or the Work Manager definitions. You must re-create these objects in the new Oracle Service Bus domain, as described in Step 6. Recreate Other Oracle WebLogic Server Objects. |
Use the WebLogic Server Administration Console to export security data from the domain. In the WebLogic Server Administration Console, select Domain Structure > Security Realms, then choose the security realm. Select Migration > Export to export the data. Table 2 summarizes the security data and the types of security providers in which it is stored.
| Note: | The set of providers to export is different depending on what version you are upgrading from as described in the following sections: |
Starting with the ALSB 2.5 release, both PKI and username/password credentials are stored in both the WebLogic Server realm and in the ALSB configuration repository. Consequently, these credentials are exported as part of the configuration JAR that was generated and exported in Step 1. Export ALSB Configuration. When the JAR is imported into the new domain, the realm data is populated based on the contents of the JAR file. This means that you do not need to export PKI Credentials or username/password credentials when you upgrade from ALSB 2.5 and later.
For more information, see Migrating Security Data in Securing Oracle WebLogic Server.
Install the Oracle Service Bus 10g Release 3 Maintenance Pack 1 (10.3.1) software as described in the Oracle Service Bus Installation Guide.
Create a new Oracle Service Bus domain using the Domain Configuration Wizard or using the offline configuration tools, as described in:
In the new domain, configure the Oracle WebLogic security framework with SSL and the security providers needed to support your proxy and business services. See Configuring the WebLogic Security Framework: Main Steps in the Oracle Service Bus Security Guide.
Note the following security-related information about importing an ALSB 2.5, 2.6, 2.6RP1, or 3.0 configuration:
UseX509ForIdentity property to the _SERVICE_BUS_INBOUND_WEB_SERVICE_SECURITY_MBEAN_ configuration (which is required to support inbound authentication with an X.509 token), add the property in the new domain. See
Use X.509 certificates to establish identity in The Oracle WebLogic Server Administration Console Online Help.In the new Oracle Service Bus domain, recreate the Oracle WebLogic Server objects that could not be exported in Step 1. Export ALSB Configuration, including:
For more information about configuring Oracle WebLogic Server domain resources, see Overview of Oracle WebLogic Server System Administration in Introduction to Oracle WebLogic Server and Oracle WebLogic Express.
| Note: | You should configure the domain-scoped SNMP agent in the Oracle WebLogic Server Console. Oracle WebLogic Server 10.x has enhanced SNMP features. For more information about SNMP, see the Oracle WebLogic SNMP Management Guide. |
Add the Tuxedo domain ID as an Oracle WebLogic Server user (this is a requirement to invoke a successful request to a Tuxedo service)
Configure WTC Local Access Point and Remote Access Point resources when your configuration includes Tuxedo transport-based services
For information, see Configuring Oracle WebLogic Tuxedo Connector for Tuxedo Transport in Interoperability Solution for Tuxedo.
Use the Oracle WebLogic Server Administration Console to import the security data that you exported in Step 2. Export the Security Configurations into the new Oracle Service Bus domain. See Import data into a security provider in the Oracle WebLogic Server Administration Console Online Help.
Import the ALSB configuration data that you exported in Step 1. Export ALSB Configuration into the new domain.
| Note: | You can either import the configuration data into a newly created domain, or you can import a configuration JAR that contains only projects, folders, or services unrelated to the artifacts you are importing into an existing domain. Importing artifacts from an ALSB 2.5, 2.6, 2.6RP1, or 3.0 domain into an Oracle Service Bus 10g Release 3 Maintenance Pack 1 (10.3.1) domain of the same type and name as in the Oracle Service Bus 10g Release 3 Maintenance Pack 1 (10.3.1) domain is undefined. |
To import configuration data, log on to the Oracle Service Bus Console as Administrator, and select Import Resources from the System Administration panel. For information about importing Oracle Service Bus configurations, see Importing Resources in Using the Oracle Service Bus Plug-in for Workshop for WebLogic.
Some Oracle Service Bus domain configuration changes are not automated and must be implemented manually. See Upgrade Considerations next.
This section describes considerations for upgrading various Oracle Service Bus configuration artifacts. It describes how ALSB 2.5, 2.6, and 3.0 differ in behavior from Oracle Service Bus 10g Release 3 Maintenance Pack 1 (10.3.1) in areas that may impact the configurations you are upgrading.
For each valid upgrade path, Table 3 lists the upgrade information you must consider.
Please read the following upgrade considerations when you are upgrading ALSB 2.5 or 2.6 configurations to ALSB 3.0:
Many of the design time features available in the ALSB Console are available in Workshop for WebLogic, the ALSB development environment.
If you want to use the IDE instead of the Console, you can import a 2.6 configuration JAR directly into the 3.0 IDE. For information about importing a JAR file into the 3.0 IDE, see Importing Resources in Using the Oracle Service Bus Plug-in for Workshop for WebLogic.
To import a 2.5 configuration JAR into the 3.0 IDE, you must first import the JAR into the 3.0 ALSB Console. From the console, export the configuration JAR file and then import it into the 3.0 IDE.
| Note: | When you import any configuration JAR into the 3.0 IDE, the operational and administrative settings are removed. To retain these settings first import the configuration JAR file into the console, export and import into the 3.0 IDE, as described above. When you later move configuration from IDE to Console, enable Preserve operational settings, so that operational settings that were imported in the first step are preserved. |
For information about exporting JAR files, see Step 1. Export ALSB Configuration.
The SLA alert rules functionality in ALSB 3.0 differ slightly from previous releases. These changes do not affect the run-time evaluation or how alerts are issued. However, you may notice the following changes:
Unlike previous releases where you could see distinct entries of alert rules in the ALSB Console, references to alert destinations through alert rules from proxy and business services are maintained and displayed as a single reference. For example, in a proxy service, if multiple alert rules and multiple pipeline alert actions use the same alert destination, only one entry for the alert destination is displayed in the Referenced By page for that alert destination. For more information, see Alert Destinations in Using the Oracle Service Bus Console.
Since Alerts are no longer separate resources in ALSB 3.0, the way references from alerts to alert destinations are displayed is different from previous releases. Two pages in the Console are affected. First, the Referenced By field in the Alert Destination page no longer displays the Alert Rule that is referencing the destination. Instead, the Reference By field displays the service that contains the alert. A side effect of this is that if a service has multiple alerts (SLA alerts or pipeline alerts) that reference the same Alert destination, the associated service is listed only once in the Referenced By field. Second, the Alert Rule page no longer contains the Reference information. Instead, the Service Summary page for the associated service contains the Alert Destinations referenced in the References field. For more information, see Alert Destinations in Using the Oracle Service Bus Console.
When an SLA alert is issued to configured destinations, the alert details include a Rule ID as in previous releases. However, in ALSB 3.0, the value of the Rule ID is set to a combination of the parent service's global name and the alert rule name. For the SNMP trap, the Rule ID is truncated to 64 characters, as in previous releases.
Unlike ALSB 2.6, which during import merged alerts with any existing alerts, ALSB 3.0 provides users with preserve-overwrite semantics. This allows you to either keep all existing alerts or overwrite them, regardless of whether the alerts have the same name or not.
The exported JARs from ALSB 2.5 or 2.6 do not contain any access control policies. Before importing a configuration JAR from an earlier release, ALSB 3.0 uses a pre-import access control policy to do an in-place upgrade of the JAR to 3.0. To perform the in-place upgrade, the pre-processor queries all manageable authorization providers for each proxy service and retrieves a list of applicable access control policies. It then inserts those policies into the service definition of the proxy service. This is done on best-effort basis.
A manageable authorization provider is an authorization provider that implements the PolicyEditorMBean interface. Such providers expose read-write APIs that allow the WebLogic Server and the ALSB console to add, modify, and delete policies stored in them.
For transport level and default message-level policies, the system queries only those providers that expose the PolicyEditorMBean and retrieves any applicable policies and inserts these policies into the service definition.
For operational message-level policies, the system can only query providers that have implemented the PolicyListerMBean. For providers that have not implemented the PolicyListerMBean interface, the operation-level policies are not retrieved.
After the in-place upgrade finishes, the import process proceeds as if the configuration JAR is of type 3.0, including the access control policies retrieved from the authorization providers. Table 4 explains various combinations of the applicable parameters and the outcome of the import process. Note the outcome is the result of the import process and does not represent anything done after the configuration is imported.
If an authorization provider does not exist in the target ALSB 3.0 system, the import ignores the imported ACLs for the authorization provider and displays a warning. In this case, you can discard the session, or undo the import task, and then add the authorization providers to the server and re-import. Alternately, you can do a dummy update operation of security parameters in the ALSB Console and the system will auto-correct any conflicts that it can on best-effort basis. These changes are atomic and reversible if you discard the session.
For more information about the updating security parameters, see Message Level Security Configuration in Using the Oracle Service Bus Console.
The following changes may impact the ALSB configuration:
In ALSB 2.6, the message retry count applies to the list of URIs for a business service. In 3.0, the retry count applies to the individual URL endpoints. The upgrade process maintains the 2.6 behavior as follows:
new_retries = N-1 + old_retries*N
where N is the total number of URIs and old_retries is the 2.6 retry count.
For example, suppose that in ALSB 2.6 you have three URLs configured for the business service and a retry count of one. With the 2.6 retry mechanism all three URLs are tried. Then after the retry delay, all three URLs are retried again. To obtain the same behavior in 3.0, the retry count is changed to five, which is obtained by applying the formula: (3 -1) + (1*3) = 5. The net effect is exactly the same: all three URLs are tried once (using two of the five retries), then after the retry delay, the three URLs are tried once more (using the last three of the five retries).
If only a single URL is configured, the old behavior and the new behavior are the same; the retry count does not change during the upgrade.
For more information, see Business Services: Creating and Managing in Using the Oracle Service Bus Console.
When importing business services into ALSB 3.0, the import process removes the duplicate URIs in the 2.6 configurations. If the URIs use randomly-weighted load balancing algorithms and the weights are set, the weights are adjusted accordingly. For example, if the business service is configured with the following URIs and weights:
For Business services configured with other algorithms, the upgrade removes the duplicate URIs and no other changes are made.
For more information about setting the parameters for the load balancing algorithm, see Business Services: Creating and Managing in Using the Oracle Service Bus Console.
In case of delivery failure when sending outbound requests, ALSB allows you to specify whether to retry endpoint URIs for application errors, such as a SOAP fault. This does not affect retries for communication errors. This new option is available on the Transport Configuration page for business services. For more information, see Transport Configuration Page in Using the Oracle Service Bus Console. After the number of retries is exceeded, an error is issued.
To maintain the 2.6 behavior, the default value for upgrading is set to Yes on the Transport Configuration page.
To use this option, you must configure the transport provider to convey to the Transport SDK whether the exception is communication error or application error. In ALSB 3.0, the Transport SDK is enhanced for this purpose. For more information, see Developing a Transport Provider in the Transport SDK User Guide.
| Note: | This functionality is only applicable to HTTP proxy services. |
To simplify switching between HTTP and HTTPS, in the ALSB 3.0 Console, the HTTPS transport configuration has been removed and its functionality has been added to the 3.0 inbound HTTP transport provider. The 3.0 HTTP Transport Configuration page contains a check box to enable to HTTPS.
A new element, use-https, is added to the schema of the HTTP Transport inbound properties.
<xs:element name="use-https" type="xs:boolean" minOccurs="0"/>
Any existing HTTPS Transport configurations are upgraded to HTTP transport with this flag set to true.
In prior releases, ALSB transports were configured only through the ALSB Console. However, starting in ALSB 3.0, the transports can be designed on Eclipse. For more information, see Developing Oracle Service Bus Transports for Workshop for WebLogic in the Transport SDK User Guide.
Please read the following considerations when you upgrade ALSB 2.5 configurations to ALSB 3.0:
ALSB JMS services (proxy and business) have a “Use SSL” attribute that controls whether SSL should be used to access the JMS queues. However, in ALSB 2.5, JMS business services did not use SSL when reading the outbound responses even if “Use SSL” was specified. This was corrected in ALSB 2.6.This means that when such a business service (JMS request/response business service with “Use SSL” selected) from ALSB 2.5 is imported into a newer domain, there may be a problem if the outbound response URL corresponds to a non-SSL port. Attempts to use SSL to talk to this non-SSL port results in an error.
Workaround: When you import an ALSB 2.5 configuration JAR that contains a request/response outbound JMS business service with “Use SSL” specified, a warning is issued in the ALSB Console. To fix change the outbound response queue URL to use the SSL port.
All of the SOAP services imported from ALSB 2.5 JARs use SOAP 1.1 by default. ALSB 2.6 and 3.0 releases support SOAP 1.2.
The UDDI auto import feature is enhanced in ALSB 2.6 and later releases to allow the auto synchronization with UDDI registries. When a change occurs in the registry for a service to which ALSB is subscribed, notifications are sent from the UDDI registry to ALSB.
For a single node, the notification is sent to the managed server HTTP address. In clustered configurations, the notification is sent to the Admin server HTTP address.
An Auto Import flag is added to the registry configuration to indicate whether auto synchronization is enabled for the registry. While importing an ALSB 2.5 JAR file, ALSB disables this flag to retain the original behavior.
Operational parameters were enhanced in ALSB starting with 2.6 and subsequent releases. Consequently, values that were set for some parameters in ALSB 2.5 configurations are set differently in the later versions. The following table describes the values that ALSB uses for Service Operational Parameters in 3.0.
Parameters set in an ALSB 2.6 configuration will retain the value specified in the imported JAR when imported into an ALSB 3.0 domain.
Please read the following upgrade considerations when you are upgrading ALSB 3.0 configurations to Oracle Service Bus 10g Release 3 Maintenance Pack 1 (10.3.1):
To upgrade an ALSB 3.0 workspace in Workshop for WebLogic 10g Release 3 Maintenance Pack 1 (10.3.1), perform the following steps.
| Note: | After you upgrade the workspace, you can no longer open it in WorkSpace Studio 1.1 for ALSB 3.0. |
In 10g Release 3 (10.3), the jndi-service-account is deprecated.
After upgrading to 10g Release 3 Maintenance Pack 1 (10.3.1), the Oracle Service Bus JMS business service uses the jms-service-account for both JMS and JNDI purposes.
The following table shows how the Oracle Service Bus JMS business service migrates JNDI and JMS accounts.
After upgrading to10g Release 3 Maintenance Pack 1 (10.3.1), all the actions in a pipeline are assigned a unique ID.
In 10g Release 3 (10.3), proxy services use a new monitoring flag to control the level of statistics collected. The three levels are:
The upgrade sets the monitoring flag to a value of Pipeline.
As of Oracle Service Bus 10g Release 3 (10.3), validation rules in the following areas have been made more strict and may result in design time or run time errors:
[OSB Kernel:398022]No corresponding mapping was found in the service definition for the WSDL operation: OPERATION-NAME[OSB Kernel:398034]Two operations expect the same incoming message, you must use a selector different than message bodyIn this case, update your WSDL or service as the error message indicates.
Variable 'VARIABLE-NAME' is being referenced before it has been initialized with a value.: Fault [{http://docs.oasis-open.org/wsbpel/2.0/process/executable}uninitializedVariable]If your Split-Join works in ALSB 3.0 and fails in Oracle Service Bus 10g Release 3 Maintenance Pack 1 (10.3.1) with the above error, then modify the Split-Join to initialize the variable before insert.
For more information, see the Oracle Service Bus Release Notes.
|