Welcome!!!

This blog is completely dedicated to SOA.
It gives you a clear idea on what SOA is all about, and how it is realized using Oracle SOA Suite 11g, common issues you find with SOA Suite.
All blogs published in my site are completely my own observations and learning, and in no way copied from any other resource.

PS : Blog under construction. Will update whenever I find some time.

Dehydration in BPEL - Oracle SOA Suite 11g

Dehydration - Offers Reliability, fail-over protection

Over the life cycle of a BPEL instance, the instance with its current state of execution may be saved in a database. When a BPEL instance is saved to a database, the instance is known as being dehydrated. The database where the BPEL instance is saved is called a dehydration store.

Once a BPEL instance is dehydrated, Oracle BPEL Server can off load it from the memory of Oracle BPEL Server. When a certain event occurs, such as the arrival of a message or the expiration of a timer, Oracle BPEL Server locates and loads the persistent BPEL instance from the dehydration store back into the memory of Oracle BPEL Server and resumes the execution of the process instance. Dehydrating BPEL instances offers reliability. If Oracle BPEL Server crashes in the middle of executing a process, the instance can be recovered automatically, programmatically, or manually from the dehydrated states. When Oracle BPEL Server resumes the execution of the process instance, it resumes from the last dehydration point, which is the last state of the instance that Oracle BPEL Server saves to the dehydration store.

                When and how the dehydration occurs differs based on the process types:

■ Transient process — Oracle BPEL Server dehydrates the process instance only once at the end of the process. When a host crashes in the middle of running the process instance, the instances are not visible from Oracle BPEL Control.

■ Durable process/idempotent — Oracle BPEL Server dehydrates the process instance in-flight at all midprocess breakpoint and non-idempotent activities, plus the end of the process. When the server crashes, this process instance appears in Oracle BPEL Control up to the last dehydration point (breakpoint activity) once the server restarts. If the server crashes before the process instance reaches the first midprocess breakpoint activity, the instance is not visible in Oracle BPEL Control after the server restarts.

        There are three cases in which dehydration occurs:

1. When the BPEL instance encounters a mid-process breakpoint activity (not including the initial receive)

Activities like wait, receive, onMessage, onAlarm, call to an async WSDL

That is where an existing BPEL instance must wait for an event, which can be either a timer expiration or message arrival. When the event occurs (the alarm expires or the message arrives), the instance is loaded from the dehydration store and execution is resumed. This type of dehydration occurs only in durable processes, which have mid-process breakpoint activities. A transient process does not have any midprocess breakpoint activities.

2. When the BPEL instance encounters a non-idempotent activity

When Oracle BPEL Server recovers after a crash, it retries the activities in the process instance. However, it should only retry the idempotent activities. Therefore, when Oracle BPEL Server encounters a nonidempotent activity, it dehydrates it. This enables Oracle BPEL Server to memorize that this activity was performed once and is not performed again when Oracle BPEL Server recovers from a crash.

Idempotent activities are those activities where the result is the same irrespective of no. of times you execute the process.

Repeated invocations have the same affect as one invocation.

Ex : Read-Only services

3. When the BPEL instance finishes

At the end of the BPEL process, Oracle BPEL Server saves the process instance to the dehydration store, unless you explicitly configure it not to do so. This happens to both durable and transient processes. For transient processes, the end of the process is the only point where the process instance is saved. This is because a transient process does not have any mid-process breakpoint activities and nonidempotent activities where the in-flight dehydration can occur.

------------------

Dehydration triggered by:

(a)Breakpoint activities: <receive>, <onMessage> (including <pick>), <onAlarm>, <wait>, and <reply>

(b)When using checkPoint()within a <bpelx:exec>activity

------------------

A BPEL invoke activity is by default an idempotent activity, meaning that the BPEL process does not dehydrate instances immediately after invoke activities. Therefore, if idempotent is set to true and Oracle BPEL Server fails right after an invoke activity executes, Oracle BPEL Server performs the invoke again after restarting. This is because no record exists that the invoke activity has executed. This property is applicable to both durable and transient processes.

If idempotent is set to false, the invoke activity is dehydrated immediately after execution and recorded in the dehydration store. If Oracle BPEL Server then fails and is restarted, the invoke activity is not repeated, because Oracle BPEL Process Manager sees that the invoke already executed.

When idempotent is set to false, it provides better failover protection, but at the cost of some performance, since the BPEL process accesses the dehydration store much more frequently. This setting can be configured for each partner link in the bpel.xml file.

Some examples of where this property can be set to true are read-only services (for example, CreditRatingService) or local EJB/WSIF invocations that share the instance's transaction.

--------------------

BPEL Dehydration Stores

As already explained, when a BPEL process instance is saved in the database, it uses the schema that is configured using Repository Creation Utility(RCU) that you would use during SOA environment setup.

Here are some of the tables that a BPEL engine uses to store its current instance state.

cube_instance - stores instance metadata, eg. instance creation date, current state, title, process identifier

cube_scope - stores the scope data for an instance

work_item - stores activities created by an instance

document - stores large XML variables, etc.

Working with a Database Adapter - Part 1

This blogs helps you to work with a Database Adapterprovided in Oracle SOA Suite.

Please go through my previous blog on configuring a Database Adapter.

Why Database Adapter?

Service Oriented Architecture is all about services, its about your entire business application modeled as Services.

In a Business Application, it is obvious that you need database to interact with. But a database by itself cannot be exposed as a service. For ex, in order to interact with it, you need to write a Java program, and using JDBC connectivity, you connect and interact with the database. If this is the case, how can you use it in a 100% SOA based application?

The only way to use it is to expose it as a service.  And how is a database exposed as a Service?

The Answer to it will be to introduce a layer over it, so that it uses the database it covers, and yet exposes it as a service, i.e. something like a wrapper.

And Oracle SOA Suite 11g provides a similar solution to it called a Database Adapter. With this, you can use your existing database as a service in your SOA Application.

It also provides various other functionalities like polling a database, checking for any changes in a specific table in a database, etc.

The Example below gives you an idea on how to use Database Adapter with the SOA Suite.

It is assumed that you have a database up and running.

In this example, we take the user input which will be the EmployeeId, and return his FullName, Salary.

This example uses the concepts of mediator, transformation of data, webservice.

Working with a DBAdapter

Create a new SOA Project, name it DBAdapterExample 

This creates a new project folder, with an empty composite.xml
You need  to first define the input and output xml formats used in the example.

In this example, Input is EmployeeId(Int) and Output is FullName, Salary

Create a new XML schema that has 2 nodes with input and output format types

rt click on xsd folder in the project --> new XML Schema, name it DBAdapterFormat.xsd

Define the schema as below

Creating a Database Adapter

• Drag and Drop a Database Adapter from the Component Pallette, into the "External References" swimline in the composite.xml, name it EmpDBAdapterService
• Create a database connection, and give the JNDI name for the outbound connection pool for the DBAdapter that you've configured(verify my prev<link> post for this)
• Select the operation that you want, Select in this case
• Import the database table you want to interact with, Employees in this case
• You may remove the relationships that you see in Step 6, or leave it as it is
• Select all the fields that you will use in this application(no problem if you even select all and later on do not use it)
• In Step 8, you have to create a bind variable(parameter), and use it in the where clause of the SQL query. In this example, we send the employeeId, and so, create a bind variable by some name(bndEmpId), and use it in the where clause as shown
• Finish the wizard to last step, and you will see a new Database Adapter in the composite.xml

Now that DBAdapter is created, in other words, the underlying database is exposed as a service, you can talk to the service to get its data.

But since the service is not exposed directly to clients (Services only in Exposed Services swim lane can be accessed by external clients)

So, you now have to create an exposed web service whose input and output parameters are same as the Database Adapter. Please remember that the Exposed service is just a client to access the Database Adapter, and has no relevance to the database or its created Adapter.

contd. in Part 2

Working with a Database Adapter - Part 2

contd. after Part 1

Creating a webservice Client

Drag and drop "Web Service" from the component palette to the exposed Services swim lane. This opens up the WebService Wizard

Name it DBServiceClient.

Choose Generate WSDL from Schema option in the WSDL URL field in the wizard (shown in the figure)

 

This opens up a Create WSDL wizard, where you'll choose Synchronous Interface, and map its input and output parameters as per the defined schema

Click on Add Message Part in Input of the wizard, click on browse button in URL section, select the request part from DBAdapterFormat.xsd that we have created in the initial phase

Similarly, add the output message part as well.

 

After adding both input and output message parts, the wizard looks similar to this

 

This finishes the creation of the client web service.

Now, the question is how the client web service and the DBAdapter Service communicate with each other.

We make use of a Mediator for this task of linking each of the services.

A mediator, as its name implies, mediates between two different services, and offers various functionalities intercepting the request. In this case, it manipulates the response from the DBAdapterService to transform firstName and lastName to fullName.

Creating a Mediator

Drag and drop a Mediator from the component Palette in to the Components swimlane.

You may choose to Define Interface Later during its creation.

 

Now, wire DBServiceClient to Mediator and Mediator to EmpDBAdapterService

Double click on the Mediator to open its configuration file, a .mplan file.

In this file, we can configure various options for the mediator.

If you observe, the mplan file has 2 sections in the Static Routing Section, one for request and the other for the reply.

In our case, we will map the DBServiceClient's input to the EmpDBAdapterService's input and EmpDBAdapterService's output to the DBServiceClient's output

For this, click on the browse-like button(highlighted in the figure above) on the Transform Using option. It opens up a new window, where we select Create New Mapper File option.

This opens up the xsl transformation wizard where we map input from client to the service. It is straight forward, just drag a line b/w empId in the left to the right as shown in the figure below

 

Now, create a new mapper file for the response, in the Synchronous Reply section

The transformation that you do here is to concat the firstName and lastName from the Service to the fullName in the client.

From the component palette, In String Functions, drag concat function to the middle of the transform wizard

 

You can double click the concat function icon to do any additional modifications like adding spaces, extra characters, etc.

Similarly, link salary on both sides

This completes our example. Lets deploy and test it.

To deploy, right click on the prj --> Deploy --> select SOA Server

Oracle SOA Suite 11g provides a unified console to test and manage all the Fusion Middleware deployments by Fusion Enterprise Manager, also called EM.

http://<host>:<port>/em

Go to soa_domain --> SOA --> DBAdapterExample --> Test

Give an input of 101 (employeeId), and check the result.

 Input

 Output

 

Hope this gives you a good understanding on what is a Database Adapter, and how to use it in SOA Applications.

In my next blog, I'll take you through some of many nice to know features of the Database Adapter.

- RaviKiran

Configuring Database Adapter in Oracle SOA Suite 11g

This blog gives you a detailed approach to configure a DataSource, JNDI, DBAdapter, and its underlying technologies, facts and common issues.

Every single component used in a SOA Application has to be a service, and this applies to the database also. A database by itself cannot act as a service that can be exposed to the service.  Inorder to use the database in a SOA application, you need to expose it as a service in some way.

Oracle SOA Suite provides you this capability by using a JCA-build wrapper called the DBAdapter.

Using this adapter in your application is quite straight forward, provided it is configured correctly.

Many times, developers come across errors like

Please make sure that the JCA connection factory and any dependent connection factories have been configured with a sufficient limit for max connections. Please also make sure that the physical connection to the backend EIS is available and the backend  itself is accepting connections.

The invoked JCA adapter raised a resource exception.

Please examine the above error message carefully to determine a resolution.

at oracle.integration.platform.blocks.adapter.fw.jca.cci.EndpointInteractionException.getFabricInvocationException(EndpointInteractionException.java:75)

...

 while working with the DBAdapters. This is due to incorrect setup of the adapter.

Datasource setup is a one time step, and it is always good to know the underlying steps and technologies involved.

Before we go to the steps in configuring a DBAdapter, lets have a look at the various concepts involved in this.

DataSource

 A datasource, as its name implies, is anything that acts as a source for data. Database is a source of data, and it has to be configured as a datasource to the SOA infrastrucure.

Datasource in specific to the Weblogic Server is the connection to the actual underlying data provider.

Connection Pool

WebLogic communicates with the database through a connection pool. The connection pool enables WebLogic to use a fixed number of connections to databases rather than incur the   overhead of constantly creating and disposing of connections.

A data source has a connection pool attached to it, which it uses for connecting to the actual data provider(Database in this case). While creating a datasource, you give a JNDI name, which is  used by the JNDI infrastructure to call the datasource.

JNDI

JNDI, the Java Naming and Directory Interface is a standard interface for the Java based application clients to access the underlying naming and directory services.

This forms a wrapper over the underlying naming and directory services like DNS, LDAP, etc. and lets the client access different services in a standard way.

 

JNDI is independent of any specific naming or directory service implementations, and allows any service provider implementations to be plugged into the JNDI framework using the standard  Service Provider Interface(SPI).

There are basically 3 steps inorder to setup and configure a DBAdapter in a SOA Application.

1. Configure a datasource for the underlying database, associate a JNDI name to it.
2. Configure an outbound connection pool, and link it with the datasource using the same JNDI name.
3. Use this JNDI name while configuring the DB Adapter.

Step 1 : Configure a Datasource for the underlying Database, associate a JNDI name to it

This step is done using the Weblogic Admin Console. Please make sure your database is up and running before this step.

Soa_domain --> Services --> Data Sources --> New --> Generic Data Source -->

 

Standard naming  convention for database sources would have a JNDI name prefixed with "jdbc/". You will use this name later to associate a connection pool to this datasource.

Select the appropriate driver

Give the underlying Database details, test the connection in the next screen(not shown here)

 

Select the server that is running the SOA infrastructure. This makes this datasource to run on that particular server, making this available to all the apps running on that server

 

Click on finish. After this, you should see this newly configured datasource in the Data Sources summary screen.

Now that the datasource is setup, and a JNDI name associated to it,

you need to create a connection pool for this datasource, in other words connections to this database.

Step 2 : Configure an outbound connection pool, link it to the datasource using the JNDI name

In Weblogic Admin Console,

soa_domain --> Deployments --> dbAdapter --> Configuration --> Outbound Connection Pools --> New

 

In the above screen, you are giving a new JNDI name, and this will be used in the SOA Suite's DBAdapter configuration wizard to obtain reference to this connection pool.

Now, you can see the newly configured JNDI name in the list of Outbound Connection Pools.

This new connection pool has to be linked to the datasource that you've created before.

There might be a bit confusion in the JNDI names. Here is how it is.

Both the datasource and Connection Pool has their specific JNDI Names

Datasource myDataSource has a JNDI Name	jdbc/myDataSource
Connection Pool has a JNDI Name	myConnPoolForDB, and this connection pool will use the name jdbc/myDataSource as its xaDataSourceName, and hence the linking to the datasource is done

After this setup, you need to redeploy the dbAdapter

Select the DBAdapter in deployments, Update-->Redeploy

Step 3 : Use this JNDI name while configuring the DB Adapter

While setting up the DBAdapter in the SOA Suite, in the configuration wizard, use the same JNDI Name

 

I Hope it is clear now what all goes into a dbAdapter setup.

My next post explains about working with a DatabaseAdapter in Oracle SOA Suite 11g

Thanks for going through my post, feel free to provide a feedback!

-RaviKiran

Error(42,53): SCAC-50012 during Composite Build

Often, you come across the following compilation issue in SOA

Error(42,53): SCAC-50012 during Composite Build

For Instance, 

in Java Embedding in BPEL, usage of bpelx:getVariableData(..) will cause this.

Correct Usage is bpws:getVariableData(..)

- Ravi Kiran

Invoking specific operation in a WS in BPEL

If a WS has multiple operations and if you want to invoke a particular operation from a BPEL invoke activity, the process is no different than invoking a simple WS with one operation.

Steps:

1. Create an external reference for the WS by drag/dropping the WebService component from the component pallete to the SOA Composite and select the wsdl of the appropriate WS. I assume the WS is already deployed.
2. Create a BPEL process and create a wire between the BPEL and the WS.
3. With this, a partner link is created in the .bpel file.
4. Create an invoke activity in the BPEL process and wire to the partner link. In the Edit Invoke popup, under the partner role, you can find the operation dropdown from which you select the appropriate operation. Based on the operation selected, the variable gets created(just in case you opt to automatically create a new one).

Dynamic Outbound Directory and FileName in File Adapters - Oracle SOA Suite 11g

Often, we'll have a requirement to change the directory to which the files are to be written dynamically. In such cases, Oracle SOA Suite 11g provides the option to do so.

While configuring a File Adapter, we specify the output directory and the file name pattern at design time.

But if we want to derive the output directory file dynamically at runtime, the process is simple.

Steps:

1. Configure the File Adapter normally as you do for anyother one, ie., you specify a directory name and the file name pattern at design time.
2. In the Invoke activity in the BPEL process, as you wire it to a File Adapter partner link, you get the Edit Invoke dialogue.
3. Go to properties and configure jca.file.Directory and jca.file.FileName with values set to variables that will be populated at  runtime in some assign activity before the invoke activity.
4. This overrides the directory and name mentioned at the design time.
5. Note that if the filename is set to the same value at runtime again and again, the same file gets overridden. So take care to set a value that uses diff file names if you dont need the files to be overridden.

Build Issue : WSDL messageType "{http://schemas.oracle.com/bpel/extension}remoteFault" of variable "" is not defined in any of the WSDL files

When you select a system fault like remotefault in a catch activity/fault handler, JDeveloper copies a wsdl named RuntimeFault.wsdl  from your

<JDEVELOPER_HOME%\\integration\seed\soa\shared\bpel directory to your project and this wsdl contains following msg :

<?xml version="1.0" encoding="UTF-8"?>

<definitions name="RuntimeFault"

             targetNamespace="http://schemas.oracle.com/bpel/extension"

             xmlns:xsd="http://www.w3.org/2001/XMLSchema"

             xmlns="http://schemas.xmlsoap.org/wsdl/">

    <message name="RuntimeFaultMessage">

        <part name="code" type="xsd:string"/>

        <part name="summary" type="xsd:string"/>

        <part name="detail" type="xsd:string"/>

    </message>

</definitions>

And secondly, JDeveloper create the faultVariable in your BPEL file (.bepl) like this :

<variable messageType="bpelx:remoteFault" name="FaultVar"/>

Now if you observe, the RuntimeFault.wsdl is having the message name as "RuntimeFaultMessage" where as

the variable's messageType is messageType="bpelx:remoteFault".

Change all those instances to RuntimeFaultMessage, and add an import to map the wsdl in the composite.xml

  <import namespace="http://schemas.oracle.com/bpel/extension" location="RuntimeFault.wsdl"

          importType="wsdl"/>