bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Migration Guide

Other Migration Topics

This section provides information about the following topics:

- Clustering

- Configuring Application Integration Adapter EAR Files

- Trusted Relationships

- RosettaNet Schema Changes

Clustering

Clustering is supported by the business process management (BPM) and application integration functionality provided, in turn, by WebLogic Integration 2.1, 2.1 SP1, and 7.0. The configuration requirements for a 7.0 cluster application, however, are different from those for a 2.1 or 2.1 SP1 cluster application, resulting in differences in the clustering sections of the config.xml files for the 2.1 and 7.0 releases. In addition, WebLogic Integration 7.0 supports clustering of the business-to-business functionality provided by WebLogic Integration.

If you are migrating a WebLogic Integration cluster application from Release 2.1 or 2.1 SP1 to Release 7.0, you must first create a new WebLogic Integration domain with clustering enabled, and then migrate application-specific entities (such as JMS queues) to it, as described in Step 7. Migrate Components of Your WebLogic Integration Application. For more information about creating a WebLogic Integration domain with clustering enabled, see Configuring a Clustered Deployment in Deploying BEA WebLogic Integration Solutions.

The configuration requirements related to clustering have been changed in Release 7.0, for the following BPM resources:

- JMS connection factories

- JMS servers

- JMS destinations, which are now distributed destinations for WebLogic Integration 7.0. The following distributed destinations are required for a BPM-cluster configuration:

- BPM audit topic (com.bea.wli.bpm.AuditTopic)

- BPM error topic (com.bea.wli.bpm.ErrorTopic)

- BPM notifications topic (com.bea.wli.bpm.NotifyTopic)

- BPM event queue (com.bea.wli.bpm.EventQueue)

- BPM validating event queues (com.bea.wli.bpm.ValidatingEventQueue)

- wli error queue (com.bea.wli.FailedEventQueue)

The configuration requirements related to clustering have been changed, in Release 7.0, for the following application integration resources:

- JMS connection factories

- JMS servers

- JMS destinations, which are now distributed destinations for WebLogic Integration 7.0. The following distributed destinations are required for an application integration-cluster configuration:

- wlai event queue (com.bea.wlai.EVENT_QUEUE)

- wlai event topic (com.bea.wlai.EVENT_TOPIC)

- wlai asynchronous request queue (com.bea.wlai.ASYNC_REQUEST_QUEUE)

- wlai asynchronous response queue (com.bea.wlai.ASYNC_RESPONSE_QUEUE)

- wli error queue (com.bea.wli.FailedEventQueue)

For more information, see "Understanding JMS Resources" in Understanding WebLogic Integration Clusters in Deploying BEA WebLogic Integration Solutions.

Configuring Application Integration Adapter EAR Files

This section provides a procedure for configuring an EAR file for an application integration adapter to be used in a sample WebLogic Integration 7.0 application. This sample is based on the following scenario.

A WebLogic Integration 2.1 customer called Acme is migrating a WebLogic Integration application to WebLogic Integration 7.0. The Acme application contains one application view called EastCoast.Sales.CustomerManagement, which uses a relational database adapter called ACME_DBMS. The ACME_DBMS adapter was developed by Acme's IT developers.

To configure an application integration adapter EAR file for the Acme application, do one of the following:

- Edit the Configuration File for the New Domain

- Invoke the WebLogic Server Deployer

- If you are deploying your adapter EAR file in a cluster environment, you must follow the instructions in "Deploying Adapters" in Understanding WebLogic Integration Clusters in Deploying BEA WebLogic Integration Solutions.

Edit the Configuration File for the New Domain

Open the config.xml file for the new domain (the one created in Step 5. Create a New Domain and Configure Database Information) and add the configuration information for the adapter. To do so, complete the following procedure:

1. In a text editor, open the WebLogic Integration 2.1 application config.xml file that deployed the adapter EAR file.

2. Copy the section of the file that deploys your adapter EAR file (part of the Application element) as shown in the following listing for the Acme example.

Listing 3-1 WebLogic Integration 2.1 Deployment of an Adapter Ear File

>     <Application Deployed="true" Name="ACME_DBMS" Path="d:\ACME_DBMS.ear">
>     	<ConnectorComponent Name="ACME_DBMS"
>     		Targets="myserver"
>     		URI="ACME_DBMS.rar"/>
>     	<WebAppComponent Name="DbmsEventRouter"
>     		Targets="myserver"
>     		URI="DbmsEventRouter.war"/>
>     	<WebAppComponent Name="ACME_DBMS_Web"
>     		Targets="myserver"
>     		URI="ACME_DBMS_Web.war"/>
>     </Application>

1. Open the config.xml file for the new WebLogic Integration 7.0 domain (the one you created in Step 5. Create a New Domain and Configure Database Information) and paste the Application element into it.

2. Add the TwoPhase attribute to the Application element, as shown, in bold, in the following figure. Set the value of this element to "true".

Listing 3-2 Add the TwoPhase Attribute to the Application Element

>     <Application Deployed="true" Name="ACME_DBMS" TwoPhase="true" Path="d:\ACME_DBMS.ear">

1. If the location of the EAR file has changed, update the Path attribute of the Application element for your adapter as shown, in bold, in the following figure.

Listing 3-3 Update the Path of the EAR file

>     <Application Deployed="true" Name="ACME_DBMS" TwoPhase="true" Path="c:\adk\ACME_DBMS.ear">

Warning: If your adapter EAR file is located in the home directory of your WebLogic Integration 2.1 or WebLogic Integration 2.1 SP1 installation (for example, %WLI_HOME%\lib on a Windows system), we recommend you move it to a location outside the WebLogic Integration 2.1 installation, such as c:\adk.

1. Update the setting of the Targets attribute of the Application element for your adapter so it matches the name of the server for the new domain (the one you created in Step 5. Create a New Domain and Configure Database Information). For example, if your domain was created from the WLI domain template, the name of the server is set to myserver, as shown, in bold, in the following example listing.

Listing 3-4 Get the Server Name from the Config.xml File

>     <Domain Name="mydomain">
>     	<!-- Domain log -->
>     	<Log FileName="c:/bea/user_projects/mydomain/logs/mydomain.log" Name="mydomain"/>
>     	<Server ListenPort="7001"
>     		Name="myserver"
>     		TransactionLogFilePrefix="c:/bea/user_projects/mydomain/logs/"
>     		NativeIOEnabled="true">
>     .
>     .
>     .
>     </Domain>

Update the setting of the Targets attribute of the Application element for your adapter, as shown in bold in the following listing.

Listing 3-5 Update the Targets Attribute

>     <Application Deployed="true" TwoPhase="true" Name="ACME_DBMS" Path="c:\adk\ACME_DBMS.ear">
>     	<ConnectorComponent Name="ACME_DBMS"
>     		Targets="myserver"
>     		URI="ACME_DBMS.rar"/>
>     	<WebAppComponent Name="DbmsEventRouter"
>     		Targets="myserver"
>     		URI="DbmsEventRouter.war"/>
>     	<WebAppComponent Name="ACME_DBMS_Web"
>     		Targets="myserver"
>     		URI="ACME_DBMS_Web.war"/>
>     </Application>

Invoke the WebLogic Server Deployer

Use the WebLogic Server deployer command-line utility to deploy the adapter EAR. For example, to deploy the ACME_DBMS.ear file on a Windows system, enter the following command:

>     java -classpath %BEA_HOME%\weblogic700\lib\weblogic.jar
>     weblogic.Deployer -adminurl
>     http://wls_admin_host:wls_admin_port -user wls_admin_user
>     -password wls_admin_pass -verbose -stage -activate -source
>     c:\adk\ACME_DBMS.ear -name ACME_DBMS -targets server_name

Table 3-1 Substitutable Strings Used in Deployer Example

This string . . . | Represents . . .
--- | ---
BEA_HOME | Directory in which BEA product software is installed, such as c:\bea on a Windows system
wls_admin_host | Hostname or IP address of the WebLogic Server instance being used
wls_admin_port | Port number of the WebLogic Server instance being used
wls_admin_user | Username used to log in to the WebLogic Server Adminstration Console. (This name is the username you specified when you used the Configuration Wizard to create a domain in Step 5. Create a New Domain and Configure Database Information.)
wls_admin_pass | Password for the login to the WebLogic Server Adminstration Console. (This password is the one you specified when you used the Configuration Wizard to create a domain in Step 5. Create a New Domain and Configure Database Information.)
server_name | Name of the server for the domain you created in Step 5. Create a New Domain and Configure Database Information.

For more information about the Deployer utility, see "Deployment Tools and Procedures" in "WebLogic Server Deployment" in Developing WebLogic Server Applications. This document is available, in the BEA WebLogic Server document set, at the following URL:

>     http://edocs.bea.com/wls/docs70/programming/deploying.html

Warning: The DBMS Sample Adapter has been changed in Release 7.0 of WebLogic Integration. This change may affect your Application View for this adapter. For details, see "Changes to DBMS Sample Adapter for Services Not Requiring Request Data" in Migrating Adapters to WebLogic Integration 7.0 in Developing Adapters.

For more information about application integration adapter migration, see Migrating Adapters to WebLogic Integration 7.0 in Developing Adapters.

Trusted Relationships

The security model for WebLogic Server trusted relationships has been changed for Release 7.0 of WebLogic Server. A WebLogic Server 7.0 server (acting as a client) authenticates another WebLogic 7.0 server in another domain. Both domains must have the same Credential attribute on their SecurityConfigurationMBean. If they do not, the following exception is thrown: java.lang.SecurityException Invalid Subject.

You can change the Credential attribute of the domain by doing one of the following:

- Use the WebLogic Server Administration Console to change the credential. For details, see the BEA WebLogic Server Administration Guide. This document is available, in the BEA WebLogic Server document set, at the following URL:

>     http://e-docs.bea.com/wls/docs70/admin.html

- In a text editor, open the config.xml file and change the credential for the following element:

>     <SecurityConfiguration Credential="foobar" Name="mydomain"/>

Note: Any cleartext credential is encrypted the first time the config.xml file is generated.

Generating a New SerializedSystemIni.dat File

If, when starting the WebLogic Integration 7.0 server, you get an exception similar to the following, you must regenerate your SerializedSystemIni.dat file.

>     weblogic.security.internal.FileUtilsException: Couldn't
>     rename DOMAIN_HOME\SerializedSystemIni.dat to
>     DOMAIN_HOME\SerializedSystemIni.dat42698.old

In these messages, DOMAIN_HOME represents the pathname of the new domain you created in Step 5. Create a New Domain and Configure Database Information.

To generate a new SerializedSystemIni.dat file for your domain, complete the following steps:

1. Go to the directory in which your domain resides:

   >     cd DOMAIN_HOME

   DOMAIN_HOME represents the pathname of the new domain that you created in Step 5. Create a New Domain and Configure Database Information.

2. Open the config.xml file and remove any encrypted sections from the Credential attributes. For example, remove the configuration section shown in Listing 3-6 and replace it with the configuration section shown in Listing 3-7.

Listing 3-6 Credential Elements with Encryption

>     <EmbeddedLDAP
>     	Credential="{3DES}CUnX5jDsmxluwzO45cb+kErCo+3pa92oXcPZl8L23pwx" Name="mydomain"/>
>     	<SecurityConfiguration Credential="{3DES}aKaA3CEY4TIx" Name="mydomain"/>

Listing 3-7 Encryption Removed from Credential Elements

>     <EmbeddedLDAP
>     	Credential="" Name="mydomain"/>
>     	<SecurityConfiguration Credential="" Name="mydomain"/>

1. Make a copy of the fileRealm.properties file and call the copy fileRealm.properties.src, by running the command appropriate for your platform:

   - Windows:

   >     copy fileRealm.properties fileRealm.properties.src

   - UNIX:

   >     cp fileRealm.properties fileRealm.properties.src

2. Delete the boot.properties file by running the command appropriate for your platform:

   - Windows:

   >     delete boot.properties

   - UNIX:

   >     rm boot.properties

3. Rename the SerializedSystemIni.dat file by running the command appropriate for your platform:

   - Windows:

   >     rename SerializedSystemIni.dat SerializedSystemIni.dat.old

   - UNIX:

   >     mv SerializedSystemIni.dat SerializedSystemIni.dat.old

4. Open the fileRealm.properties.src file and change all the hashed passwords to cleartext passwords. (Passwords are set by the user.user_name element, where user_name represents the user identity, as shown, in bold, in the following partial listing.) For example, remove the password encrypted in Listing 3-8 and replace it with the text version, as shown in Listing 3-9.

Listing 3-8 Partial Listing of the fileRealm.properties file with Password Encrypted

>     group.ConfigureSystem=admin,joe,mary,guest,wlisystem
>     acl.lookup.weblogic.jndi.weblogic.fileSystem=everyone
>     acl.enablermonitor.WLCAdmin=admin
>     user.joe=0xa078cb45e6f6c4eefdd1f14495ff739b5536904c
>     group.DeleteTemplate=admin,joe,mary,guest,wlisystem
>     group.AdministerUser=admin,joe,mary,guest,wlisystem
>     group.Deployers=Administrators

Listing 3-9 Partial Listing of the fileRealm.properties file with Password in Cleartext

>     group.ConfigureSystem=admin,joe,mary,guest,wlisystem
>     acl.lookup.weblogic.jndi.weblogic.fileSystem=everyone
>     acl.enablermonitor.WLCAdmin=admin
>     user.joe=password
>     group.DeleteTemplate=admin,joe,mary,guest,wlisystem
>     group.AdministerUser=admin,joe,mary,guest,wlisystem
>     group.Deployers=Administrators

1. Rename the SerializedSystemIni.dat file by running the command appropriate for your platform:

   - Windows:

   >     rename SerializedSystemIni.dat SerializedSystemIni.dat.old

   - UNIX:

   >     mv SerializedSystemIni.dat SerializedSystemIni.dat.old

2. Use the FileRealm utility to regenerate the SerializedSystemIni.dat file. Specifically, run the following command:

   >     java weblogic.security.internal.acl.FileRealm
   >     fileRealm.properties SerializedSystemIni.dat

RosettaNet Schema Changes

WebLogic Integration provides schema validation of RosettaNet messages. The schemas provided for this validation with WebLogic Integration 2.1 and WebLogic Integration 2.1 SP1 are based on the World Wide Web Consortium (W3C) 2000 XML Schema Definitions (XSD) schema. The schemas provided for this validation with WebLogic Integration 7.0 are based on the World Wide Web Consortium (W3C) 2001 XML Schema Definitions (XSD) schema.

A RosettaNet message is made up of two parts: a message header XML document (Service-Header) and an XML business document or payload. The XSD schemas used for validating both the message header XML document and the XML business document have been converted to use the W3C 2001 XSD schema. If you have developed schemas for WebLogic Integration message validation, you must update them to use the 2001 XSD schema. (The schema must start with the schema element shown in Listing 3-11 or Listing 3-12.) WebLogic Integration 7.0 supports only the validation of RosettaNet messages against 2001 XSD schemas.

RosettaNet message validation schemas are located in the WLI_HOME\lib\xmlschema\rosettanet directory. (WLI_HOME represents the WebLogic Integration home directory.)

2000 XSD schemas start with the schema element shown in the following listing.

Listing 3-10 2000 XSD Schema Element

>     <schema xmlns="http://www.w3.org/2000/10/XMLSchema">
>     	<!-- schema content goes here -->
>     </schema>

2001 XSD schemas start with a schema element similar to the one shown in Listing 3-11 or Listing 3-12. The XSD schema element in Listing 3-12 uses the namespace xsd to fully qualify elements of the XSD schema.

Listing 3-11 2001 XSD Schema Element

>     <schema xmlns="http://www.w3.org/2001/XMLSchema">
>     	<!-- schema content goes here -->
>     </schema>

Listing 3-12 2001 XSD Schema Element with the xsd Namespace

>     <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
>     	<!-- schema content goes here -->
>     </schema>

xml: Namespace

WebLogic Integration 7.0 supports the use of the xml: namespace. The xml: namespace is a standard W3C namespace that contains the following attribute names:

- xml:lang—identifies the natural language being used

- xml:space—specifies whether white space is significant to the element

- xml:base—defines the base URIs for parts of XML documents

In WebLogic Integration 2.1 or 2.1 SP1 XSD schema files, xml:lang is converted to a string, as follows:

>     <xsd:attribute name="xml:lang" type="xsd:string"/>

In WebLogic Integration 7.0 XSD schema files, the value of xml:lang is determined by xml: namespace. If you develop your own schemas for message validation, change the xml:lang attribute as shown in the following listing:

>     <xsd:attribute ref="xml:lang"/>

By default, WebLogic Integration 7.0 obtains the xml: namespace XSD schema from the local filesystem, instead of from the following standard xml: namespace URL:

>     http://www.w3.org/2001/xml.xsd

Looking up the namespace on the local filesystem, allows WebLogic Integration to improve performance and reduce network traffic.

By obtaining schema from a local filesystem instead of a URL, WebLogic Integration 7.0 can reduce network traffic and thus, improve performance. For example, the 0A1_MS_V02_00_FailureNotification.xsd schema sets the value of the schemaLocation attribute to schemas/xml.xsd, as shown in the following listing. This setting means that WebLogic Integration will get the xml: namespace schema from the local file system.

Listing 3-13 0A1_MS_V02_00_FailureNotification.xsd Using Local Schema

>     <?xml version = "1.0" encoding = "UTF-8"?>
>     <xsd:schema xmlns:xsd = "http://www.w3.org/2001/XMLSchema">
>     <xsd:import namespace = "http://www.w3.org/XML/1998/namespace"
>     schemaLocation = "schemas/xml.xsd"/>
>     .
>     .
>     .

In Listing 3-14, the value of the schemaLocation attribute is http://www.w3.org/2001/xml.xsd. When this setting is used, WebLogic Integration optains the xml: namespace schema using the URL.

Listing 3-14 0A1_MS_V02_00_FailureNotification.xsd Using URL Schema

>     <?xml version = "1.0" encoding = "UTF-8"?>
>     <xsd:schema xmlns:xsd = "http://www.w3.org/2001/XMLSchema">
>     <xsd:import namespace = "http://www.w3.org/XML/1998/namespace"
>     schemaLocation = "http://www.w3.org/2001/xml.xsd"/>
>     .
>     .
>     .

If you prefer to validate the xml: namespace from the URL, you can replace the XSD schema files in the WLI_HOME\lib\xmlschema\rosettanet directory with a set of XSD schema files that set the value of the schemaLocation attribute to the standard xml: namespace URL. To do so, complete the following steps:

1. Go to the RosettaNet XSD schema directory by running the command appropriate for your platform:

   - Windows:

   >     cd WLI_HOME\lib\xmlschema\rosettanet

   - UNIX:

   >     cd WLI_HOME/lib/xmlschema/rosettanet

   On both command lines, WLI_HOME represents the WebLogic Integration home directory.

2. Create a backup directory by running the command appropriate for your platform:

   - Windows:

   >     md backup

   - UNIX:

   >     mkdir backup

3. Move the XSD schema files that point to the local xml: namespace schema file to the backup directory by completing the command appropriate for your platform:

   - Windows:

   >     move *.xsd backup

   - UNIX:

   >     mv *.xsd backup

4. Extract the XSD schema files that point to the standard xml: namespace URL:

   >     jar xvf schemas.jar

Additional 2001 XSD Schema Changes

If you develop your own schemas for message validation, you may need to make the following changes to your schemas:

- Replace the appInfo element with the documentation element. This replacement was made in WebLogic Integration 7.0 schemas to accommodate a change in the DTD grammar.

- Remove the content="elementOnly" and content="textOnly" attributes, as shown in the following example listings.

Listing 3-15 Example 2000 XSD Schema (WebLogic Integration 2.1 or 2.1 SP1)

>     <xsd:complexType content = "elementOnly">
>     <xsd:choice>
>     	<xsd:element ref = "GlobalLocationIdentifier"/>
>     	<xsd:group ref = "StreetAddress"/>
>     	<xsd:group ref = "GlobalLocationIdAndStreetAddress"/>
>     </xsd:choice>

Listing 3-16 Example 2001 XSD Schema (WebLogic Integration 7.0)

>     <xsd:complexType>
>     <xsd:choice>
>     	<xsd:element ref = "GlobalLocationIdentifier"/>
>     	<xsd:group ref = "StreetAddress"/>
>     	<xsd:group ref = "GlobalLocationIdAndStreetAddress"/>
>     </xsd:choice>