Web Services

Web Services are a self defined services which can be two way request and response or can be one way.A web service can be registered in a UDDI Universal description,discover and Integration Registry so that other applications can locate it.
IT can be called asynchronously or synchronously.It can interact with other software packages using XML based messages and internet based protocols.If mathematically web services has to be defined then i will say

web services = XML + HTTP

i.e. you can say web service is composed of a message protocol (XML) and a transport protocol (HTTP)

Web services standards

SOAP Simple Object Access Protocol
===================================

SOAP is a simple XML based protocol which allows the applications to exchange information over the HTTP.In relation to web-services we can call it as a protocol for accessing a web-service.The best feature of SOAP is that it is protocol independent,language independent,Platform and operating system independent.


A SOAP has following building blocks

1>Envelope.
2>Soap Header.
3>Soap Body.
4>Fault handler.

Ok lets understand this

When we post a letter to some one we have wrap it in the envelope then have to provide the address where we want to post it.Envelope is in the same way an element that indentifies the XML document as a SOAP Message.

The general syntax for a SOAP message is

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header>
...
</soap:Header>

<soap:Body>
...
<soap:Fault>
...
</soap:Fault>
</soap:Body>

</soap:Envelope>

As you can see it must include the root element envelope and within the envelope we have to mention the header ,body and then fault.The namespace that we have defined must contain the value "http://www.w3.org/2001/12/soap-envelope".

The SOAP header contains the application specific information about the SOAP message.


WSIL Web Service Inspection Language.(WS-Inspection)
=======================================

WSIL is an XML format that helps in assisting inspection of a site for available services and a set of rules for how inspection related information should be retrieved for consumption.It provides a means for collecting references to pre-existing service description documents which are published in any number of formats.

Web Service Interoperability(WS-I)
===================================

It is an organization that helps web services to be operable across platform, application and programming languages.

WSDL Web Service Description Language
======================================
It is an XML based language for describing web services and how to access them.
A WSDL document contains the following elements.

1>Type-Data type used by the web service.
2>Messages-Messages used by the web service.
3>PortType-Operation performed by web service.
4>Binding-Communication protocol used by web service.

So a WSDL document should essentially look like this

<definitions>

<types>
.......
</types>

<message>
....
</message>

<portType>
.......
</portType>

<binding>
....
</binding>

</definitions>

Port element is very important as it defines the operational capability of the web services.Operation can be one or two-way.

Binding element

The binding element has two attributes - name and type.

The name attribute defines the name of the binding, and the type attribute points to the port for the binding.

The soap:binding element has two attributes - style and transport.

The style attribute can be "rpc" or "document". In this case we use document. The transport attribute defines the SOAP protocol to use.

<binding type="callArpit" name="Arpit">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
........................
</binding>

Here Arpit is the name of binding and callArpit is the operation which should be defined in port element.

Calling external Java code in a Java Activity in BPEL

Create a simple asynchronous BPEL process and give it some logical name




Now select the folder you have created just now and right click on it select new



and chosse java class and say ok



Now give some name to the class just created.I will call it Calculate.



A java code will be created where in we will put some simple logic

public int getValue(String val) {
return 420;}



Now our aim is to call this java class from out Java Embed activity in BPEL.

Just drag and drop a simple java activity in the designer.




now double click on the java embed activity and start coding.

i will use the following code

Element inputValue = (Element)getVariableData("inputVariable", "payload","/client:JavaUsageProcessRequest/client:input");

Calculate calculate =new Calculate();


int newVal=calculate.getValue(inputValue.getNodeValue());

setVariableData("outputVariable", "payload","/client:JavaUsageProcessResponse/client:result", new Integer(newVal));

If you have knowledge of java then you can easily get that i am accessing the input variable and then i have created an object for the Calculator class.

Then i am calling the getValue function in the Calculate class where in i am providing the inputValue

finally i am setting the output variable the result of the getValue() function.

this is the only coding in java Embed activity but we also need to import some class file so we will add the following import statement


<bpelx:exec import="java.util.*"/>
<bpelx:exec import="java.lang.*"/>
<bpelx:exec import="java.rmi.RemoteException"/>
<bpelx:exec import="javax.naming.NamingException"/>
<bpelx:exec import="org.w3c.dom.Element"/>

this you have to provide in the source of the BPEL code.

Again you need to import one more class file that is the Calculate class.

Go to the jdeveloper and find the package for the Calculate class.



so now we need to add one more import statment

<bpelx:exec import="BusinessProcess.Calculate"/>

So now our BPEL process is complete .Just deploy the project.

and invoke it

You will get an ouput

<outputVariable>
- <part xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="payload">
- <JavaEmbedProcessResponse xmlns="http://xmlns.oracle.com/JavaEmbed">

<result>

420

</result>

</JavaEmbedProcessResponse>

</part>
</outputVariable>

As you can see it is the value returned from getValue() function in the Calculate class.So you can use this concept and do your coding.

If there is any external java files are there then Jar up the Java class you want to use and copy the jarfile to the
SOA_HOME\bpel\services\lib directory.

Now you can use the Java coding in java embed activity

Pick Activity in BPEL

Pick activity is one of the most important activity in BPEL.It works on the principle that we have invoked a process and we are waiting for the results .Pick has two activity associated with it one is onMessage and other is onAlaram.

It works like we define a alram for the process if the response does not comes in the time period defined in alarm then it start executing the flow in the onAlarm scope and if the result comes before the expiration of onAlram then onMessage scope is followed.I will just provide a simple flow to understand the scenario.

First of all create a simple aysnchronous BPEL process which will be picked by our main BPEL process we will call this process as ToBePicked.





Drag and drop an assign activity and create a copy operation in assign activity where in map the input variable to the output variable.



Save and deploy the project.

Now again create a new asynchronous BPEL process give it some logical name i will call it Picker



Drag and drop a partnerlink and provide the WSDL of the ToBePicked process

So it should appear like



Now drag and drop a assign and a invoke activity in the process as below



Now select the invoke activity and drag and drop a connection from invoke to the partnerlink a pop up window will come up.click on create instance and create a instance as shown below.



Say apply and ok and you will find a link between the invoke and partnerlink as





Now double click on assign activity create a copy operataion and assign the input variable to the input of invoke.



Say apply and ok and now drag and drop a pick activity after the invoke activity





Now expand the pick activity fully and drag and drop assign activity in them as below




Now in the first assign activity just pass a value Arpit to the output variable.




Similarly create a copy operation in the second assign activity and assign value Ankit to the output variable.

Now double click on the watch icon and specify the time as 1 second



Again double click on the onMessage



A window will come up just click on the partner link choosing wizard.




and select the partnerlink that you have created earlier



Again click on the marked icon to create a default variable.




Say ok and save the project and deploy it.Now if you will check the process output you will get the following as output

<outputVariable>
- <part xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="payload">
- <PickerProcessResponse xmlns="http://xmlns.oracle.com/Picker">

<result>

Arpit

</result>

</PickerProcessResponse>

</part>
</outputVariable>

This is because the process completed in milliseconds and entered the onMessage loop and exceuted the assign where in we are assigning the value Arpit to the output variable.

Now we will do some change in our ToBePicked process.We will add a wait activity there and give it a time period of 10 seconds and check how it behaves.

Add a wait activity by draggin and dropping it



now double click on wait activity and configure it for 10 seconds



Now deploy the process again .

Go to the Picker process and refresh the partnerlink to include the latest value of the ToBePicked process.

Now again deploy the Picker Process and invoke it.


now if you will review the output you will get

Your test request was processed synchronously. It took 1.094seconds to finish and generated the following output:
Value:
<PickerProcessResponsehttp://xmlns.oracle.com/Picker>
<result>Ankit</result>
</PickerProcessResponse>

The output will say

<outputVariable>
- <part xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="payload">
- <PickerProcessResponse xmlns="http://xmlns.oracle.com/Picker">

<result>

Ankit

</result>

</PickerProcessResponse>

</part>
</outputVariable>

This is because the ToBePicked process took 10 seconds to complete and by that time the onAlaram gets activated since it is defined for 1 second so it start the execution Hence you got the time as 1.094seconds,the one second for the onAlaram and .094 for completion of the bpel process.

So now you can just imagine the speed of BPEL

Wait Activity in BPEL

Wait activity in BPEL is used to put an delay in processing of the bpel process.It is done intentionally in some cases.Lets assume some use cases, we have some process which needs to be invoked only after 10 seconds .In general bpel processing is very fast and a simple bpel process it it does not include and dehydration process the request in milli seconds.But in our case we need to wait to 10 seconds so we will put a wait activity in between so that our process can wait for 10 seconds before its get ready to be invoked.

Another reason for discussin wait activity here is the next topic i will be covering is about pick activity ,there we will find the proper use case for this.for now we will just creat a simple process and check how it delays the processing.

Create a new application and a new asynchronous BPEL process.Give it some logical name.



Now drag and drop a assign activity in between the input variable and the call back client.



Now double click on the assign activity create a copy opearation and assign the input varialbe to the output variable.



Now if you will deploy this process and try to invoke it you will get the response in milli seconds as bpel process server works in milliseconds but we don't want to get the output in milli seconds we want to delay for 10 seconds.In that case we will add a wait activity in there.Drag and drop a wait activity in between the input variable and the assign activity.




Now doule click on wait activity.


One important point that most of the people miss is that by default the wait time is specified as 1 day.SO when ever you are adding some time delay keep in mind that the wait is already set to 1 day so please make it zero or set it as per your requirement.In my case i want it to be delayed for 10 seconds so i will put the value as




Now apply the changes save the project and deploy it to the server.Once deployed invoke the process and you will get the response this time with some error.So you might get a screen like this



This is because the wait activity has not yet expired it will wait for its wait time that is 10 seconds and then only it will provide the result so we will just wait for few seconds and referesh the list so that we will get the following results after refreshing the flow.





There are some issues with wait activities that is it does not wake up on time this happens mostly in case of high loaded server.Again restart of server proceed this but you also need to fine tune your quartz scheduler settings to avoid this issue.

To fine tune it
Stop your server using opmnctl stopall
Now go to the following directory
SOA_HOME\bpel\domains\default\config\resources-quartz.properties

Take a backup of the file. and now edit the following value

com.oracle.bpel.expirationAgent.threadCount

By default it is set to 10 increase it to some higher value lets say 100.

Their are no documents or guidelines for setting this thread count.you just have to tweak its value and find out the best possible value for your environment.Once the changes are done.Save the changes and restart the server.

Switch activity in BPEL

Switch activity in BPEL is again like simple switch statment of any programming language.In bpel switch activity comes with two option one is user defined condition and other is default.However you can add extra conditions as per your requirement.We will have a look in the activity use case.Create an application then within that a simple asynchronous BPEL process .Assign it some logical name.





Now drag and drop a switch activity in between the receive input and callback client



Now expand the switch activity and put two assign activity in there.



Now double click on first assign activity and assign some value to the output variable.I am assigning Arpit .



Similarly create a copy operation for the second assign activity and assign it some value,i assigned it Ankit.

Now we will provide the condition for the switch activity.

just click on the expression buttion on the top of the switch activity.



Once you will click on that a new winodw like this will come up




Just click on the xpath expression builder and a new window will come up .there in select the input variable from the BPEL variable list and double click on it so that it will now appear on the top window.Provide a condition like

the input varialbe should be less than 420

so in my case the condition is something like this

bpws:getVariableData('inputVariable','payload','/client:SwitchDemoProcessRequest/client:input')<420



Save all the changes and dploy the project.

Now invoke the process in bpel console with follwing input



Now if you will check the output in the callback client you will find the folllowing output

<outputVariable>
- <part xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="payload">
- <SwitchDemoProcessResponse xmlns="http://xmlns.oracle.com/SwitchDemo">

<result>

Arpit

</result>

</SwitchDemoProcessResponse>

</part>
</outputVariable>

Now invoke the same process again with value 421 and you will get value

<outputVariable>
- <part xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="payload">
- <SwitchDemoProcessResponse xmlns="http://xmlns.oracle.com/SwitchDemo">

<result>

Ankit

</result>

</SwitchDemoProcessResponse>

</part>
</outputVariable>

This is because our condition is if the input <420 then assign "Arpit" to the output variable otherwise for all other input the value should be "Ankit"

So this illustrate its use case.You can add more conditional braches as per your wish by clicking on this button



you can further provide your own condition for this new switch block you can again add some more otherwise block by click on the buttion next to the previous button.

Flow Activity in BPEL

Create a new application and a new asynchronous bpel process.Give it some logical name



Drag and drop a flow activity in between the receiveInput and the callback client.



Now expand the Flow activity and drag and drop two assign activity


Now double click on assign activity and create a copy operataion .Provide some value to the output variable.
For first assign activity i am assigning Arpit as value.




Similarly for the second assign activity i am assigning Ankit as the output variable.


Now your bpel process is complete.

Deploy the process.The flow activity is used to perform two processes in parallel.I have illustrate here a simple test,In real life scenario the two flow will be calling two partnerlink which will be performing some complex task.


Now go tot he bpel console and initiate the task.Then check the flow of the data.it will be something like this



thus it depicts that the two assign activity are being processed in a parallel flow.

However the final ececution result comes from the right most assign activity.That is in the left assign activity i have assigned value as Arpit and in right assign activity i have assigned the value as Ankit.Sine flow execution ends in the right most assign activity so the final out put of this flow activity will be Ankit.

<outputVariable>
- <part xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="payload">
- <FlowDemoProcessResponse xmlns="http://xmlns.oracle.com/FlowDemo">

<result>

Ankit

</result>

</FlowDemoProcessResponse>

</part>
</outputVariable>

JAVA embedding in BPEL

we will now see a use case on how to use a java embedding activity in our BPEL process.

Just create a new application and within that application create a new BPEL process make this process asynchronous bpel process and provide some logical name to it.



now select Process activities in component pallete and drag and drop a assign activity in between the input and call back client as below




now double click on assign activity and create a sopy operation.Assign the input variable to the output variable as below



now drag and drop a java activity and place it after the assign activity.



Now we will try to get the value of the input variable through java coding.

Since bpel is written in xml langauge all the input and output variables are called as elements.

/* accessing a variable within the complex type */

Element inputValue = (Element)getVariableData("inputVariable", "payload","/client:JavaEmbedProcessRequest/client:input");

This command is used to get the input value.

here inputValue is a temporary element to store the value of the input that we will pass from the console.

getVariableData is a predefined function to get the data stored in the variable.

now we will check how we have reached to this command

"inputVariable", "payload","/client:JavaEmbedProcessRequest/client:input"

Just go to your assign activity and edit the copy operation.

now expand it fully to get see the root input.





Now as you can see here we have first inputVariable

then payload

then copy the xpath



the value we got needs to be converted to string

so we will use the code

String inputVal = inputValue.getTextContent();

Further if we want to add the entry to the audit trail in the bpel console we use the following command


addAuditTrailEntry("Value Entered is : " + inputVal);

i will show the result where does it reflect in audit trail.

Next is setting the value to the output variable

setVariableData("outputVariable", "payload","/client:JavaEmbedProcessResponse/client:result", inputVal);

Again we will use the same concept to reach to the output variable.

so in all i am using the following command in my java embedding

System.out.println("Hello, World") ;

Element inputValue = (Element)getVariableData("inputVariable", "payload","/client:JavaUsageProcessRequest/client:input");
String inputVal = inputValue.getTextContent();

addAuditTrailEntry("Value Entered is : " + inputVal);

setVariableData("outputVariable", "payload","/client:JavaUsageProcessResponse/client:result", inputVal);


the logic of this program is to get the input value and assing it to output variable.

and my activity is looking something like this



This is not it we need to import some packages also.So go to the source of the BPEL and add the following statments

<bpelx:exec import="java.util.*"/>
<bpelx:exec import="java.lang.*"/>
<bpelx:exec import="java.rmi.RemoteException"/>
<bpelx:exec import="javax.naming.NamingException"/>
<bpelx:exec import="org.w3c.dom.Element"/>

Now save the project and deploy it.Now try to run the program and check the output.

The assign activity is giving the following output

<outputVariable>
- <part xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="payload">
- <JavaEmbedProcessResponse xmlns="http://xmlns.oracle.com/JavaUsage">

<result>

arpit

</result>

</JavaEmbedProcessResponse>

</part>
</outputVariable>


If you click on java embedding here you will get the value that we have provided using audit trail so it will be



Now if you will check the callback client we will get the following output

<outputVariable>
- <part xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="payload">
- <JavaEmbedProcessResponse xmlns="http://xmlns.oracle.com/JavaUsage">

<result>

Arpit rahi

</result>

</JavaEmbedProcessResponse>

</part>
</outputVariable>

As you can see the output here is Arpit Rahi because that is the value we have provided when we invoked the process.In the assign step we assigned arpit to the output variable but in java embed activity we are assigning the input variable to the output variable so we got the output as Arpit rahi