Setting Unit Of Order in OSB Producer

Unit Of Order is used in Weblogic JMS queues/topics to group messages into a single unit that can be processed sequentially even if the message are being processed by multiple consumers.  For example, you can use CustomerID for the Unit Of Order to ensure that you will always process a given customers transactions in order.

Follow the link for more information on Unit Of Order

Setting the Unit Of Order in an OSB Producer is quite simple.

1) Add a Transport Header action in the Request Action section of your communication node (Route, Publish, Service Call Out)

2) Set the Transport Header Properties
     a) For Direction select  Outbount Request.   
     b) Click on the Add Header button.
     c) Select Defined, jms, JMS_BEA_UnitOfOrder under the Name column.
     d) Select Set header to and set the <Expression> you want to use to set your Unit of Work in the Action column.

OSB Retry Application Errors

Recently our OSB administrator asked me how OSB determined what an application error was for the "Retry Application Errors" setting on the Transport page of a Business Service.  It turns out there is not much documentation on this at all.   So I did some testing.

OSB looks at the  response-code in the Response Metadata to flag an application error.  If this value is a non-zero, then it is treated as an application error.

The easiest way to manipulate this value is to add a Reply with Failure in the OSB service you are calling.

You can also manipulate the response code by inserting a response-code element in $inbound as shown below.  Note: This must be done in the response pipeline 

Note:  I only researched this for Business Services that were calling OSB Proxy Services as that was the architecture for the context of the question asked.  More research would need to be done to determine this behavior when call services outside the OSB.

Using CDATA to handle embedded XML

We ran into an issue when we were trying to pass embedded XML through one of our OSB processes.  The problem came up when we had duplicate namespaces between the embedded XML and the XML for our process.   OSB was combining namespace declarations and removing the namespace declaration from our embedded XML since it was already declared in the XML for our OSB process.

The solution was to wrap the embedded xml in a CDATA wrapper.  This is very easy to do in OSB by using the fn-bea:serialize function shown below.

     <content>{fn-bea:serialize($body/*)}</content>

Removing the  CDATA wrapper is also easy and can be done using the fn-bea:inlinedXML function.

  {fn-bea:inlinedXML($body/content)}

Weblogic Server Not Starting Due to Expired Database Accounts

If you are unable to start your weblogic server and you are getting the following errors, it is being caused by your oracle accounts expiring and the fix is quite easy.

Errors

####<Apr 23, 2013 9:09:16 AM MST> <Error> <Deployer> <localhost.osbsoavm> <AdminServer> <[ACTIVE] ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'> <<WLS Kernel>> <> <0000JsrdyCXFw000jzwkno1HTf7V000002> <1366733356615> <BEA-149205> <Failed to initialize the application 'wlsbjmsrpDataSource' due to error weblogic.application.ModuleException: .
weblogic.application.ModuleException:
 .........
Caused By: weblogic.common.ResourceException: weblogic.common.ResourceException: Could not create pool connection. The DBMS driver exception was: ORA-28001: the password has expired

<BEA-280061> <The persistent store "JDBCStore-0" could not be deployed: weblogic.store.PersistentStoreException: Can't find JDBC DataSource wlsbjmsrpDataSource: javax.naming.NameNotFoundException: Unable to resolve 'wlsbjmsrpDataSource'. Resolved ''; remaining name 'wlsbjmsrpDataSource'
weblogic.store.PersistentStoreException: Can't find JDBC DataSource wlsbjmsrpDataSource: javax.naming.NameNotFoundException: Unable to resolve 'wlsbjmsrpDataSource'. Resolved ''; remaining name 'wlsbjmsrpDataSource'

Fix 

            1. Check to see if any of the accounts are expired

                           select username, profile, account_status, expiry_date from dba_users;

2. If no accounts are expired, you can skip to step 7

3.  Dynamically create SQL that will unexpired the expired accounts.  You can unexpired the 

     account by resetting the password.   NOTE: You will need to substitute <password> for the password you are using for your user.

                            select 'ALTER USER ' || username || ' identified by <password>;'

                            from dba_users where account_status like 'EXPIRED%' and username != 'XS$NULL';

                  4. Execute the SQL generated in Step 3

                  5.  Dynamically create SQL that will unlock the locked accounts.

                             select 'ALTER USER ' || username || ' account unlock;' from dba_users where 

                             account_status like 'LOCKED%' and username != 'XS$NULL';

6.  Execute the SQL generated in Step 5

7. Modify the profile assigned to the accounts that you don’t want to expire so the 

    PASSWORD_LIFE_TIME is set to UNLIMITED.  This will keep them from expiring 

    again.  In my case, I needed to update the DEFAULT profile.

alter profile DEFAULT LIMIT PASSWORD_LIFE_TIME UNLIMITED ;

OSB Error Handler Tutorial

Error handling in OSB is fairly straight forward but can seem more complex than needed.  The following exercises will provide hands-on examples of how error handlers function in OSB.  I have also included a sample project which makes it very easy to try different scenarios that can help broaden your understanding of OSB Error Handling.  These examples are meant to give some guidance but please try different scenarios and if there is something you are curious about add it to one of the proxy services and see what OSB does.

Before we start with the hands-on exercises below is a quick overview of the key points in OSB Error Handling. 

OSB Error Handling Overview

Error handling can be configured at 4 different areas in and OSB Proxy Service.

1. Proxy Service
2. Route Node
3. Pipeline
4. Stage Node

If an error is not handled in any of these areas then it will be caught in the System error handler.

An error will be handled by the inner-most encompassing error handler.  In other words, if there is no error handler configured at the level the error occurred then the error will be processed by the next level error handler.  Below is an outline of how the error handlers are nested.

Stage Node -> Pipeline -> Proxy Service -> System Error Handler

Route Node ->  Proxy Service -> System Error Handler

Choosing an error handler action

An Error Handler is not considered completely configured until it has a Resume or Reply Action configured.  If an error handler is missing one of these actions then the other steps in the error handler will be completed but the error will be bubbled up to the next level error handler.

Reply – Will immediately reply back to the calling process with an error response and all further message processing stops. 

Resume – Message flow process will continue as if no error occurred.   The processing will continure after the node or stage that the error handler is configure in.  

Configuring Error Handlers

Error handlers are just another pipeline and can be configured like any other pipeline.  You may use an assign action, publish action…. Etc.

In the error handler a new context variable is available ($fault).  The $fault context variable contains information about any error that occurs during message flow processing and is populated before the error handler is invoked.

For more information on the contents of the $fault variable see  OSB Context Variables

Error Handler Exercises

The following exercises are simple and are meant to demonstrate how error handlers behave in OSB.  Specifically we are going to focus on how error handlers are nested and the behavior of OSB when there are no error handlers. 

To complete these exercises please import the Error_Handler_Demo project.

You can download the project at the following link.

https://docs.google.com/file/d/0B5g0v_BbuvHUV05NaVFOUWxFamM/edit

The Error_Handler_Demo project consists of 3 proxy services.

1)      ValidateID – This proxy service will look at the value of the ID passed in. 

If the ID is <= 5, then it will return a status of “Success” and reply with Success.

If the ID is between 6 and 10, it will return a status of “BusinessFault” and reply with Fault.   

If the ID is between 11 and 20 it will return a status of “TechnicalFault” and reply with Fault.

2)      ErrorHandlerDemoImpl – This proxy service will call the ValidateID proxy service.  We primarily will use this service to demonstrate how OSB handles errors that are returned from a child process.

3)      ErrorHandlerDemo – This proxy service will call the ErrorHandlerDemoImpl proxy service.  This service will be used to show how errors are handled when the error is thrown from a nested service.

ErrorHandlerDemoImpl Service

We will start with calling the ErrorHandlerDemoImpl service directly to demonstrate how it will handle errors returned from the ValidateID service.

For these examples remember that error handler order of execution is as follows when a route node is involved.

Route Node ->  Proxy Service -> System Error Handler

No Error Handler

In the following exercise we will run through several requests to show how the service will behave with no configured error handlers.

1)      Call the ErrorHandlerDemoImpl service and pass in an ID of 2.

§  Based on this ID we would expect a status value of Success to be returned in the response message. Since there were no faults, it will process as expected even though we do not have any error handlers defined.

  

2)      Call the ErrorHandlerDemoImpl service and pass in an ID of 8.

§  Based on this ID we would expect a status of BusinessFault to be returned in the response message.  Unfortunately no status gets returned.  Instead you see a soap fault with a faultstring of “BEA-380000”.   

§  This is because we do not have any error handlers configured.  When the ValidateID service returns a failure it automatically gets processed through the system error handler.  If you look at the Invocation Trace of your test call, you will see that the ValidateID service returns the correct status in the body.  It also returns a response-code of 1.  You can see this in the $outbound context variable.  We are not seeing these in the response because any unhandled faults will be processed through the system error handler and a SOAP fault will be returned.

Proxy Service Error Handler

We will now add a Proxy Service Error Handler to see how it changes the services behavior.

          1)      Add an error handler at the proxy service level.

a.       For detailed instructions on how to do this visit the following link. http://docs.oracle.com/cd/E14571_01/doc.1111/e15867/proxy_errors.htm

b.      In the error handler add a Reply and configure it to Reply With Failure.  Remember the error handler will not be considered completely configured unless it has a Reply or Resume node.

          2)      Call the ErrorHandlerDemoImpl and pass in an ID of 8.

§  Based on this value we would expect to see a response message with a status of BusinessFault returned.   This is because we now have now configured an error handler that will handle the error returned from the ValidateID service and the correct response message should be passed on.

          3)      Try passing in different values for IDs to see how the service behaves.

Route Node Error Handler

Let’s see what happens when we add a route node error handler to our proxy service.

          1)      Add a Route Node Error Handler to the ErrorHandlerDemoImpl proxy service.

a.       For details on how to do this see the following link http://docs.oracle.com/cd/E14571_01/doc.1111/e15867/proxy_errors.htm#autoId4

b.      In your Route Node Error Handler add a Reply which is configured to Reply With Failure.

          2)      Test ErrorHandlerDemoImpl with an ID of 12.

a.       As expected a response message with a  status of TechnicalFault gets returned.  Also note how the error is processed through the Route Node Error Handler instead of the Service Error Handler.

ErrorHandlerDemo Service

Now that we have the error handlers configured in the ErrorHandlerDemoImpl process, let’s look to see how that error information will get propagated to a calling service.  

For these examples remember that error handler order of execution is as follows when a stage node is involved.

Stage Node -> Pipeline -> Proxy Service -> System Error Handler

No Error Handler

The ErrorHandlerDemo proxy service does not have any error handlers defined.

Note:  Remember that the ErrorHandlerDemo service is configure to call the ErrorHandlerDemoImpl service using a Service Callout.

1)      Try calling the ErrorHandlerDemo service with an ID of 10.   When we call the ErrorHandlerDemoImpl process with this value it will return a response message with a status of “Technical Fault”.  This is something that we tested in the previous exercise. The ErrorHandlerDemo service is still going to return a SOAP fault not the correct response message with a status of TechnicalFault.  Since we do not have any error handlers defined the message will be handled by the system error handler which as we saw in our previous exercise will return a SOAP fault.

Proxy Service Error Handler

          1)      In the ErrorHandlerDemo proxy service, add a Proxy Service Error Handler.

          2)      Execute ErrorHandlerDemo service and pass in an ID value of 11.

a.       Based on our previous exercises we would now expect the service to return a response message that contains a status of TechnicalFault and this holds true in this example.  Also if you look in the invocation trace, you will see that the error is getting processed through the service handler.

Pipeline Error Handler

          1)      Add an error handler on the Request pipeline in the ErrorHandlerDemo service.

a.       For detailed steps on how to add this error handler, see the following link

http://docs.oracle.com/cd/E14571_01/doc.1111/e15867/proxy_errors.htm#autoId2

          2)      Execute the ErrorHandlerDemo service and pass in an ID value of 15.

a.       Once again we will see that there is a response message that contains a status of TechnicalFault.  The only thing that is different with this example is that the error is now being handled by the Pipeline Error Handler instead of the System Error Handler.

Stage Node Error Handler

For our last example, we will add a Stage Node Error Handler to demonstrate that it will process the error before the Pipeline or Service Error Handler.

          1)      Add an error handler on the Stage Node in the ErrorHandlerDemo service which calls the    ErrorHandlerDemoImpl service.

a.       For detailed steps on how to add this error handler, see the following link

http://docs.oracle.com/cd/E14571_01/doc.1111/e15867/proxy_errors.htm#autoId3

          2)      Execute the ErrorHandlerDemo service and pass in an ID value of 11.

a.       The response message should contain a status of TechnicalFault and the error will be processed through the Stage Node Error Handler. 

Choosing Between Route, Service Callout and Publish

When you are first starting with OSB it can be a little tricky to determine when to use a Route, Service Callout or a Publish node.  All three can be used to call either a Business service or a local Proxy service.  You can use the following lists to determine which will best fit your needs.

Route

1. Last node in request processing.  It can be thought of as a bridge between request pipeline processing and the response pipeline processing.
2. You can only execute one route in your Proxy Service.
3. Can only be created in a route node.
4. OSB will wait for the Route call to finish before continuing to process.
   1. If you are calling a Business service and you specify Best Effort for QoS (Quality of Service), then OSB will release the thread it is holding while the business service executes.
   2. If you are calling a Business service and you specify Exactly Once or At Least Once for QoS, then OSB will hold onto the thread while the business service executes.
   3. If you are calling a local Proxy service, then OSB will hold onto the thread until the Proxy service finishes executing.

Service Callout

1. Can have multiple Service Callout nodes in a Proxy service.
2. Pipeline processing will continue after a Service Callout.
3. Can be invoked from the request and/or response pipelines.
4. Used to enrich the incoming request or outgoing response. For example, a call to get a country code.
5. Used for real time request/response calls (Synchronous calls).
6. OSB will hold a thread and not continue until the Service Callout completes.
7. Can tie up resources and degrade performance under heavy loads.

Publish

1. Can be synchronous or asynchronous
   1. If you are calling a business service with a Quality of Service of Best Effort , then it will be an asynchronous call.
   2. If you call a business service with a Quality of Service of Exactly Once or At Least Once, OSB will wait until the processing completes in the business service completes before proceeding and it is effectively a synchronous call.
   3. If you are calling a local proxy service, OSB will wait until the processing in the local proxy service completes and it is effectively a synchronous call.
2. Can be invoked from the request and/or response pipelines.
3. Best to use when you do not need to wait for a response from the process you are calling (Fire and Forget.... Asynchronous Calls)

For more detailed information on the differences between a Route and a Service Callout including how OSB handles threads during each of these calls see OSB, Service Callouts and OQL - Part 1.

Creating a Business Service to Access a Database Table in OSB

There are several steps that need to be completed before you can create a business service in OSB to access/modify data in a database table.  At a high level you will need to create the JCA Adapter files in JDeveloper, create the data source/connection pools in Weblogic and then import the JCA Adapter files into OSB.  Below are the detailed steps.
1.   Create JCA Adapter in JDeveloper
         a.  See Creating a JCA Database Adapter in JDeveloper for more details.
2.  Create a zip file with the JCA Adapter files that you need for the import.  It needs to be in a zip file to import into OSB.  Note: You can get the location of these files by clicking on them in JDeveloper.
         a. Add the following to the zip file
                  i. <Project>.wsdl
                  ii. <Project>_db.jca
                  iii. <Project>_db-or-mappings.xml
                  iv. <Project>_table.xsd
3. Create a New Data Source in  Weblogic
         a.  For more details on this step see  Steps for Creating a New Data Source in Weblogic
4. Link DB Adapter outbound connection pool to a data source
         a. For more details on this step see Linking DB Adapter Outbound Connection Pool to Data Source
5.  Import JCA Adapter files
         a. Log into the OSB Console
         b. Navigate to the project you are working on
         c. Create a directory to hold the JCA Adapter files (<Project>/Resources/jca)
         d. In the Create Resource menu, select Bulk -> Zipped Resources

         e. Select the zip file created in step 2.

         f. Select Next

         g. All of the files that you added to your zip file in step 2 should now be displayed on the Review Loaded Resources page.

         h. Select Import.

         i . Fix Conflicts.   

Note: You will need to fix any path conflicts caused by moving all of the files into the same area. In JDev the schema files are in a different directory.

                  i. Click on View Conflicts.

                   ii. Start by fixing the wsdl conflict as this should resolve all of the conflicts. This can be fixed by changing the schemaLocation.

                  iii. Activate Changes.

4. Create Business Service

         a.  Create WSDL that will be used by the Business Service. This WSDL will have the operations that you specified when you were creating the JCA Database Adapter in step 1.

                  i.  Navigate to the *.jca file that was imported in Step 3 (<Project>/Resources/jca)

                  ii. In the Actions column next to the JCA Binding file imported click on the Generate WSDL and Service from this JCA binding resource button.

                  iii.  Specify the new WSDL Name and New Service Name. Also, choose a location for the new WSDL file. To avoid confusion, we put it in the BuisnessServices folder.

                  iv. Select Generate. 

Creating a new Data Source in Weblogic

The below steps outline how to create a new Data Source in Weblogic.  These steps are intended for
developers who want to create a new data source in their own virtual machines or the development
server.

1. Create Connection Information in Weblogic
      a.  Create New Data Source
            i. Navigate to <domain> -> Services -> Data Sources and select New -> Generic 
Data Source.

           ii. Fill in the Name, the JNDI Name and the Database Type for your new data
source on the JDBC Data Source Properties Page.

            iii. Select the database driver that will be used for this connection.

    














            iv. Fill in Transaction Options if available.  If you choose a XA JDBC Driver, you will not have any options.

            v. Fill in Connection Properties information for the database you want to connect
to.

           vi. Test your configuration

           vi.i. Select Next and then select where to deploy the data source you created.  If
you are not using a managed server for OSB you can select the AdminServer.

Deploying OSB code from Eclipse

The following outlines the steps needed to deploy OSB code from Eclipse

1.  Add a new server connection in Eclipse

      a. Go to File -> New -> Server

     b.  Set the Server Type, Server Host Name and Server Name.  The server name is the name of the server that will be displayed in Eclipse

      c.  Set the Server Type and then browse to find the location of the OSB domain that you want to access.  This is usually in $MiddlewareHome/user_projects/domains/<domain>.

      d.  If you have any OSB configuration projects in OSB, you can associate them with this server( We will do this after we create the OSB configuration project in step 2).  Then select Finish.

      2.  Create a new Oracle Service Bus Configuration Project. 

            a.  Go to File -> New -> Oracle Service Bus Configuration Project

           b.   Fill in information on the Oracle Service Bus Configuration Project and then select Finish.   The session name and description will be used when saving the changes in OSB.

         3.  Link the OSB Configuration project to the server you want to deploy to. 

       a.  Right click on the server in the Servers tab and select  Add and Remove.

      b.   Move the OSB configuration project that you created in step 2 from the Available section to the Configured section and then select Finish.  You want to be careful on how many OSB configuration projects that you associate with the server at one time.  Keep in mind that changes in all of the OSB configuration projects associated with a server will be published when you publish changes to a server.  It is much cleaner and safer to only have one OSB configuration project associated with a server at a time.

      4.  Create new project in the OSB Configuration Project

            a.  You can either create a new project or import a project.

      b.  Make any changes needed to your new or imported project.
5.  Publish Changes
      a.  Right click on the server and select Publish.