Oracle Service Bus Migration (ESB to OSB)

Many customers have already build services with the Oracle SOA Suite. A part of these services are implemented with Oracle Enterprise Service Bus (ESB). After the acquisition of BEA System, Oracle introduced the new product; the Oracle Service Bus (OSB).

This product is positioned as standalone Service Bus. The ESB will be integrated into the new Oracle 11g SOA stack, and renamed into mediator as a component of the Service Component Architecture (SCA).

Business requirements can result that instead of using the ESB the OSB is required. This could result that customers already have implemented ESB services and they need to migrate to the OSB.

This article describes the approach on migration from ESB to OSB.

Assumptions
Migrating to the Oracle Service Bus requires knowledge of various technologies.

• Oracle Enterprise Service Bus
• Oracle Service Bus
• Oracle WebLogic
• Web Service Definition Language (WSDL)
• XML Schema definitions (XSD)
• XML Style sheets (XSLT)
• XML Query (Xquery)
• XPath

Tools
There are no tools yet for automatic migration of ESB services to OSB. That is why document give you best practise on this.

Tools that are used for the migration are:

• Oracle JDeveloper
• Oracle Workshop (Eclipse development)

Oracle JDeveloper
Oracle JDeveloper is use to view the ESB services. It is used to determine the dependencies of the artefacts that it is using.

Oracle Workshop
Oracle Workshop is used to build and deploy the new OSB services.

Approach
While there is no automatic migration, we need to rebuild the services in OSB. The approach is as follows.

Reuse the artifacts from ESB as much as possible. This means in practices that we will reuse the WSDL definitions, schema definitions and style sheets.

Open in JDeveloper the ESB services and determine the artifacts it is using;

• WSDL files
• XSD schema's
• Used elements
• Used namespaces
• Stylsheets
• Filters
• Adapters

Describe for each ESB service the artifacts in structured way; for example in a table format:


Based on these artefacts, the OSB services can be build.

Development environment
Depending on the complexity of the OESB services, a different sequence of steps should be followed. First of all a project structure should be in place. In this project structure various components will be stored.

Projects
The Workspace (OSB Project Structure) should contain one OSB Configuration Project, give this configuration a name "MyOSBConfig" and an OSB Project called "MyOSBMigration". The former contains the server definition for an OSB Server running on :, the latter all project resources.

Folder Structure
Create for every ESB service, an OSB service with the following directory structure.

ESBName	<ESBName>
Input
	WSDL		<WSDLFile>
	Schema		<SchemaFile>
	Element		<elementused>
	Adapter?
		DB
			DatasourceJNDI	<JNDIdatasource>
			Query	<query>
		JMS
			JMSConnectionfactory	<jmsconfactory>
			Queue/Topic	<queue/topicname>
		File
			Directory	<directory>
			Filename	<filename>
Output#1
	FilterUsed	<Y/N>	<XPATHfilter>
	WSDL		<WSDLFile>
	Schema		<SchemaFile>
	Element		<elementused>
	Adapter?
		WS	<endpoint>	(MarkifthisaBPELWS)
		DB
			DatasourceJNDI	<JNDIdatasource>
			Query	<query>
		JMS
			JMSConnectionfactory	<jmsconfactory>
			Queue/Topic	<queue/topicname>
		File
			Directory	<directory>
			Filename	<filename>
Output#2
	<nextoutput>

Folder	Description
BusinessService	All the business services are located here.
ProxyService	All the proxy services are located here.
Schema	Local schema's in the project are located here.
Transformation	Local transformation files (XSLT & XQuery).
Wsdl	The interface definitions.

For each ESB project copy the used XSLT files into the transformation directory.

Naming Convention
A recommended approach for naming conventions of OSB resources is to add the
prefix `PS_' for Proxy Services, `BS_' for Business Services, `XQ_' for XQuery
transformations, and append a version indication `_v1r0'. Examples:

Project: CollectOrderInformation
Proxy service: PS_GetOrder_RS_v1r0
PS_GetOrderLines_RS_v1r0

Bus. Service: BS_GetOrder_v1r0
BS_GetOrderLines_v1r0

Proxy Endpoints:
The enpoints of the proxy services will be renamed to

/<logical_name><proxyname_v1r0>

Common Schemas
All schemas of the Common data Model are imported in the OSB project in folder Common/Schema/. All generated or imported WSDLs should preferably refer to these schemas, potentially importing service specific schemas in the "Schema" folder of the respective service.

Implementation
Based on the pervious table the OSB service can be build. Execute the following steps to perform this.

• Create the business services
• Create the proxy service
• Implement the message flow

Create the business services
Create a new business service for each output definition. If an external web service is called, import or consume the WSDL definition of that web service. The same applies if this service is a BPEL process. In this case some additional changes should be made, this is described in the next paragraphs..

If you are calling a BPEL process, you could use the BPEL transport instead of normal http protocol. The BPEL protocol is more efficient implementation on calling BPEL from OSB.

When the business service is created, the WSDL and schemas are copied into a folder of your project. After creating the business service move the WSDL files to the WSDL directory and the schemas to the Schema directory or to the Common/Schema directory.

Note: With BEA ALSB 3.0, you should remove the partner link bindings, otherwise the WSDL is invalid. This is fixed in OSB 10gR3.

Create the proxy service
Create a new proxy service for each input definition. If the service is based on a interface definition from an external web service is called, import or consume the WSDL definition of that web services.

When the proxy service is created, the WSDL and schemas are copied into a folder of your project. After creating the proxy service move the WSDL files to the WSDL directory and the schemas to the Schema directory or the Common/Schema directory.

Implement the message flow
Implementing the flow is the most important step of the migration. Based on the various output from the ESB, you should route the message to the various business services.

The most simple one is just create a routing node to call the services.
Often we need a transformation call the business service
In the replace action we define the transformation., this is based on the style sheet of the ESB.
When there are filters defined in ESB service, this can be replaces in OSB via If-Then actions or conditional branches actions.

Stylesheets
Note that there can be issues with style sheets. The style sheet is based on the JDeveloper diagrammer, it is using namespaces and namespace aliases based on the interface definition of the ESB. Execute the test action on the replace action of the Oracle Workshop (Eclipse).
It could be that the style sheet is using Oracle SOA specific extensions or custom functions, these are not available in OSB. If this is the case, you should change the style sheet or, which is easier, create a XQuery transformation.

Deployment and Test
Deploy and test the OSB service, you could use various test scenarios and tools to perform this.

• Test style sheets and XQueries from Eclipse.
• Test business services from the OSB Console.
• Test proxy services from the OSB Console.
• Use tools such as SoapUI to perform end-to-end tests.

Adapters
Database Adapter
Note that the current version of OSB does not have a DB adapters as in the ESB.

Therefore you should create the DB adapter in BPEL as a simple wrapper for this
query. The BPEL process should use the same input and output schema's and namespaces as generated in the partner link of the DB adapter. The future version of OSB 10gR3 will have support of the DB adapter.

JMS Adapter
The OSB has full support of the using JMS messaging.

Import WSDL from BPEL
The ESB service has both the Proxy Service as the Business Service based on the same WSDL that is `consumed' from the BPEL process. The steps to create a similar service in OSB are:

1. Import the WSDL from the BPEL process URI (?WSDL) by consuming froma URI. All included schemas are imported as well and stored in the samefolder.
2. Leave the WSDL itself in the `WSDL' folder.
3. Drag and drop the service specific schema to the `Schema' folder thereby automatically changing the reference in the WSDL.
   
4. Change the references from either the WSDL or the service specific schema to the CDM schemas by changing the "schemaLocation" property of the "import"tag.
5. Remove the imported CDM schemas from the `wsdl' directory.
6. Add a Business Service in the `BusinessService' directory based on the imported WSDL.
7. Add a Proxy Service in the `ProxyService' directory based on that same WSDL.
8. Add a `Routing Node' to the Proxy Service and route to the Business Service.

Imported WSDL from ESB
The ESB service has a Proxy Service based on a ESB "generated" WSDL and the Business Service based on the WSDL of a BPEL process. The steps to create a similar service in OSB are:

1. Import the OESB "generated" WSDL in the Workspace `wsdl' folder.
2. Add a "service" and a "binding" to that WSDL, because the WSDL is not well-defined, refer to the PortType of the WSDL.
3. Create a Proxy Service in the `ProxyService' directory based on that WSDL.
4. Import the WSDL from the BPEL process as described for the previous service migration; don't forget to move the schemas.
5. Add a Business Service in the `BusinessService' directory based on the imported WSDL.
6. Add a `PipelinePair' to the Message Flow of the Proxy Service.
7. In the request Pipeline, add a `stage' with a `replace' action, change the XPath to `.', enter variable `body', in the expression select the XSL file and add the rootelement of the body (request) to the `Binding' box, check `replace node contents'.
8. Same for the response `Pipeline', but obviously for the response XSL and the response rootelement.
9. Add a `Routing Node' to the Proxy Service and route to the Business Service.

Deploy to Oracle Service Bus does not work

When deploying services from Oracle Workshop (Eclipse) to the Oracle Service Bus (OSB) fails when you did an out-of-the-box installation. Eclipse is responding with:


While the log file of the OSB Server is like this:

<Error> <ConfigFwk> <BEA-390101> <Activation of session OSB_Publish failed: com.bea.wli.config.deployment.server.ServerLockException: Failed to obtain WLS Edit lock; it is currently held by user weblogic. This indicates that you have either started a WLS change and forgotten to activate it, or another user is performing WLS changes which have yet to be activated. The WLS Edit lock can be released by logging into WLS console and either releasing the lock or activating the pending WLS changes. com.bea.wli.config.deployment.server.ServerLockException: Failed to obtain WLS Edit lock; it is currently held by user weblogic. This indicates that you have either started a WLS change and forgotten to activate it, or another user is performing WLS changes which have yet to be activated. The WLS Edit lock can be released by logging into WLS console and either releasing the lock or activating the pending WLS changes. at com.bea.wli.config.deployment.server.ServerDeploymentInitiator.__serverCommit(Unknown Source) at com.bea.wli.config.deployment.server.ServerDeploymentInitiator.access$200(Unknown Source) at com.bea.wli.config.deployment.server.ServerDeploymentInitiator$1.run(Unknown Source) at weblogic.security.acl.internal.AuthenticatedSubject.doAs(AuthenticatedSubject.java:363) at weblogic.security.service.SecurityManager.runAs(Unknown Source) Truncated. see log file for complete stacktrace sssd
sadasd

The reason for this error, is the fact the OSB is configured for automatic apply of changes made OSB. This option is default in OSB 10gR3 and should be switched off. This can be done via the WLS console.

• Logon to Console
• Select Preferences
• Uncheck the option "Automatically Acquire Lock and Activate Changes":

• Click on Save
• Activate Changes

Remove namespaces in OSB and BPEL/ESB

Removing name spaces from your XML payload is sometimes needed. Various reasons require this. This article shows you how to remove namesapces in your XML payload. There are two solutions.

XML Stylesheets (XSLT)

For BPEL and ESB you can use the XSLT solution to remove namespaces. The next example show you how to implement this in BPEL. First of all we need to create a XSLT file. The file shoudl looks like this:

TrX_RemoveNamespace.xsl

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
          exclude-result-prefixes="xsl">
<xsl:template match="comment()|processing-instruction()|/">
<xsl:copy>
<xsl:apply-templates/>
</xsl:copy>
</xsl:template>
<xsl:template match="*">
<xsl:element name="{local-name()}">
<xsl:apply-templates select="@*|node()"/>
</xsl:element>
</xsl:template>
<xsl:template match="@*">
<xsl:choose>
<xsl:when test="name() != 'xmlns'">
  <xsl:attribute name="{local-name()}">
    <xsl:value-of select="."/>
  </xsl:attribute>
</xsl:when>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>

The BPEL code to call this XSLT is as follows.

<assign name="Transform_1">
<copy>
  <from expression="ora:getContentAsString(
            ora:processXSLT('TrX_RemoveNamespace.xsl'
          , bpws:getVariableData('inputVariable','payload'))
          )"/>
  <to variable="outputVariable" part="payload"
      query="/client:BPELRemoveNameSpaceProcessResponse/client:result"/>
</copy>
</assign>

The above example will remove the namespaces from the input payload, then it will convert it to a string and put the output into the result element.

XQuery

The solution for OSB can alo apply via XLST, but in OSB the XQuery technology is used.. Removing the namespace in XQuery is done via the following function.

declare namespace xf = "http://tempuri.org/vijfhuizen/com/myMessage/";

declare function xf:strip-namespace($e as element())
as element()
{
element { xs:QName(local-name($e)) }
{
 for $child in $e/(@*,node())
 return
   if ($child instance of element())
   then xf:strip-namespace($child)
   else $child
}
};

You can call this function in your XQuery file as follows.

<ns0:Data>
{
concat('<?xml version="1.0" encoding="UTF-8"?>', fn-bea:serialize(xf:strip-namespace($varMessage)))
}
</ns0:Data>