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.

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. 

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.

Creating a Business Service to Publish to a JMS Queue/Topic

The following steps outline how to create a business service that will publish to a JMS Queue or Topic.  For this example, I created the Business Service in the OSB Console.  You could also use Eclipse and the steps would be very similar.

1.  Log into OSB Console.

2.  Create new project.  For this example I used the project name of PublishJMSQueue.

3.  Create a new folder called BusinessServices to hold the service we are going to create.

4.  Navigate to the BusinessServices folder and select Business Service from the Create Resource menu.

5.  Enter Service Name, select Messaging Service for the Service Type and click on Next.

6.  Select the Request Message Type, Response Message Type and click on Next.  For this example I am using Text for the Request Message Type and None for the Response Message Type.  Below is information on the other types from the Oracle Documentation.

None - Select this option if there is no request message (HTTP GET example)

Binary - Select this option if the content-type of the message is unknown or not important.

Text - Select this option if the message can be restricted to text.

MFL - Select this option if the message is a binary document conforming to an MFL definition. You can configure only one MFL file.

For MFLs, you can click Browse to select an MFL from the MFL Browser, then click Submit.

XML - Select this option if the message is an XML document. To provide some type information, you can choose to declare the XML schema type of the XML document exchanged.

7.  Select jms for Protocol, enter the Endpoint URI for the queue/topic you are publishing to, click on Add and then click on Next.  You can leave everything else with the default values.

Note:  The Endpoing URI follow the format of “jms://host:port(,host:port)*/FactoryJndiName/DestJndiName”.   If you are using a Weblogic queue/topic you do not need to change the FactoryJndiName, OSB will prepopulated the correct JNDI name.  You can get the DestJndiName from the Weblogic console (domain -> Services -> Messaging -> JMS Modules -> <Module Containing the Queue/Topic you are publishing to> -> JNDI Name)

8.  Set Destination Type, Message Type and then click on Last.  Everything else can remain at the default value.  For this example, we are using a queue for destination type and Text for message type.

       9.   Review Settings and then click Save.

      

     

     10.  Test Business Service.