Enterprise Java for Forms and 4GL Developers: A Simple Web Services and BPEL Example
SOA for Forms and 4GL Developers: A Simple Web Services
and BPEL example
Purpose
In
this tutorial, you are introduced to BPEL (Business Process Execution Language)
and web services. Using simple examples, you will see how you can publish Java
code as web services, orchestrate those web services together into a BPEL service,
and then call that BPEL service from your application. You will use JDeveloper
and Oracle ADF to build your application with minimum of coding.
Place
the cursor over this icon to load and view all the
screenshots for this tutorial. (Caution: This action loads all screenshots simultaneously,
so, depending on your Internet connection, may result in a slow response time.)
Note:
Alternatively, you can place the cursor over an individual icon in the following
steps to load and view only the screenshot associated with that step. You can
hide an individual screenshot by clicking it.
Overview
While
this example uses very simple coding examples, it shows how you can take functionality
from your application and publish as a web services so that other applications
can use those services. Then, by orchestrating web services together into a BPEL
service, you can provide a richer service which is easily consumed from your application.
The
scenario for this application will be kept as simple as possible in order to focus
on the elements of the technology; however once you have an understanding of the
simple case it can be easily applied to more "real world" examples.
The scenario is to create two simple Java classes, both take a string input and
return a string output. The first will accept a string and return the string prefixed
with "Hello ". The second Java class will accept a string and then concatenate"how
are you?". Finally, these two web services will be orchestrated together
such the the first is called and then passes the result to the second. So, given
the initial input of "John Doe" the result will be "Hello John
Doe, how are you?
The
first step of this tutorial will be to install the relevant software. The instructions
are based on Oracle JDeveloper 10.1.3.1 Developer Preview and SOA Suite 10.1.3.1
Preview.
In
this section of the document we assume that Winzip is installed on the computer.
You will unzip and install the application server that will run your web and BPEL
services.
Accept
the license agreements and download Developer Preview for the Oracle SOA
Suite to a temporary location on your hard drive.
In
the file explorer right click on the file choose Winzip > Extract to...
2.
In
the Extract dialog enter the folder where you want to install the products (eg:
c:\oracleDevDay\soasuite), and click Extract.
Click
OK, and wait for the extract to finish.
3.
In
a file explorer, navigate to the location where you extracted the soasuite files.
Double click setup.exe.
4.
In the Oracle
Application Server SOA Suite 10.1.3.1.0 Installation dialog, specify the Installation
Directory, e.g. c:\oracledevday\OracleAS_1. Select Basic
Install and set the AS Instance Name to soademo. Specify
welcome1 as the AS Administrator Password. Confirm the password
and click Install.
5.
During
installation, a series of configuration assistants will run. Do not stop the process.
Once the configuration assistants have successfully completed, the End of Installation
dialog appears.
Click Exit
to exit the Installer, and click Yes to confirm.
Note:
The Oracle SOA Suite installation will set the ORACLE_HOME environment variable
for your computer. In some cases, this setting can cause a conflict with the Oracle
RDBMS. Specifically you may get errors from your Oracle Net Listener. If this
is the case, then reset the ORACLE_HOME to your database location. On Windows,
you may need to restart your PC.
You now have successfully installed
Oracle SOA Suite 10.1.3.1 preview.
You will now create connections
to the SOA suite application server.
1.
Click
on the Connections tab in JDeveloper. Create the application server connection.
Double-click the Application Server
folder to open the Create Application Server Connection wizard. Click Next
on the Welcome screen.
2.
On
the Step 1 of 4: Type page, enter the following values:
Element
Action
Connection
Name
OrderBookingAS
Connection Type
Oracle Application
Server 10g 10.1.3.
Click Next.
3.
On
the Step 2 of 4: Authentication page, enter the following values:
Element
Action
User
oc4jadmin
Password
welcome1
Deploy Password
Selected
Click Next.
4.
On the Step 3 of 4: Connection
page, enter the following values:
Element
Action
Connect
To
Single Instance
Host Name
Enter the host name in which
you installed Oracle SOA Suite, e.g. localhost
OPMN
Enter the OPMN request port. The
default is 6003.
If your installation in the previous section
resulted in different port numbers than the default, enter the correct port number.
OC4J
Instance Name
Enter home.
Click Next.
5.
On the Step 4 of 4: Test
page, click Test Connection.
If the test does not succeed,
use the Back button to verify and change values, if needed.
Click Finish.
6.
Create
a connection to the Oracle BPEL Process Manager and Enterprise Service Bus integration
server.
Creating this connection enables you to deploy business processes
to Oracle BPEL Process Manager and services to the Enterprise Service Bus.
Double-click
Integration Server to open the Create Integration Server Connection
Wizard.
Click Next on the Welcome screen
7.
On Step
1 of 3: Name, enter OrderBookingIS in the Name field. Click Next.
On
Step 2 of 3: Connection, enter the following values:
Element
Action
Application
Server
Select OrderBookingAS, which is the
name of the application server connection you created.
Host Name
Enter the host name in which
you installed Oracle SOA Suite, e.g., localhost
Port
Enter the port for the Oracle HTTP
Server installed with the SOA Suite. The default is 8888.
If your installation
in the previous section resulted in different port numbers than the default, enter
the correct port number.
Click Next.
8.
On Step
3 of 3, Test, click Test Connection.
You should see the
following results:
Application Server:
OK BPEL Process Manager Server: OK ESB Server: OK
If
the test does not succeed, use the Back button to verify and change values, if
needed.
You
will now create the application in which your business logic code will be placed.
1.
In the Applications Navigator, right-click the Applications
node and select New Application... from the context menu.
2.
In the
Create Application dialog, enter the Application Name WebServicesApp.
Notice that as you enter the application name, the directory name changes automatically.
Select the Application Template No Template [All technologies]
from the Application Template dropdown list.
Click OK.
3.
In the Create Project dialog, enter
the Project Name WebService.
Click OK.
The Applications Navigator shows the
WebServiceApp application and the new project
4.
Click
Save All
or select File | Save All to save your work.
You will now publish these two classes a
web services.
1.
In the Applications
Navigator, right-click the helloWorld Java class you created
earlier and choose Create J2EE Web Service... from the context
menu.
2.
In the Select J2EE
Web Service Version dialog select J2EE 1.4
Click
OK.
3.
In the step 1 of 8 in the dialog enter
the Web Service Name helloWorldWS, leave other fields as default.
You
can now click Finish since you will be accepting all the defaults.
4.
Repeat
steps 1-3 for the howAreYou Java class, naming this web Service
howAreYouWS
5.
Click Save All
or select File | Save All to save your work.
6.
Finally, you need to deploy
the web services to the Application Server. In the Applications
Navigator, right-click the WebServices.deploy node choose Deploy
To and then the name of your Application Server connection
Click
OK on the Configure Application dialog and check you get a successful
deployment message in the deployment log.
Using the application server management
page, you will test the web services.
1.
To test the web services
you need to create a client stub which is based on the WSDL of the deployed web
service. Alternatively, you can use the features of Oracle Enterprise Manager
to test your services.
From your Windows desktop select Start, Programs,
<App Server Instance>, Launch SOA Console.
2.
Click the
link Application Server Control on the top right of the page.
3.
If prompted, enter the username
and password
Click OK.
4.
Click
the Home link under the Members heading.
5.
Click the Web
Services link
6.
Find the name of the web Service
you created and click on that name
7.
Click the Test Service
link
8.
At this point, copy the URL of
the web Service to notepad. You will need to use this URL in a later step. Click
the Test Web Service button.
9.
Enter a string in the parameter
field and click Invoke
10.
The resulting page will show
the XML message including the resulting string form the web Service which concatenates
the input parameter with "Hello"
11.
Repeat with
the second web Service to ensure the correct result.
In this
sessions you will orchestrate the web services such that the output of one web
service is the input to the other web service. To do so, perform the
following steps:
The creation of the BPEL process is complete separate from the work done earlier
so will be done in a separate Application. In the Applications Navigator, right-click
the Applications node and select New Application...
from the context menu.
2.
In the
Create Application dialog, enter the Application Name SimpleBPEL.
Notice that as you enter the application name, the directory name changes automatically.
Select the Application Template No Template [All technologies]
from the Application Template dropdown list.
Click OK.
3.
When prompted for the name of the project click Cancel. You
will create the project in the next step.
4.
Right-click
the SimpleBPEL application in the Applications Navigator, and
click New Project... in the context menu.
In the New Gallery
select BPEL Process Project. .
click
OK
5.
In the BPEL Project Create Dialog enter
HandsOnBPELProcess for the Name and Synchronous BPEL Process
for Template.
ClickFinish
6.
Click
Save All
or select File | Save All to save your work.
In this section you will create
a BPEL service by diagrammatically"hooking" up the flow from the various
web services.
1.
This next stage is to "hook"
the web services into a flow and indicate how the data is passed from one web
service to the next. If the BPEL Process diagram has not appeared then double-click
on the SimpleBPEL.bpel node under the HandsOnBPELProcess project.
2.
From the component palette,
drag a Scope component onto the BPEL diagram between the ReceiveInput
and ReplyOutput nodes (Ensure All Process Activities is selected
in the component palette drop down).
3.
From the component palette, drag a Partner
Link component onto the right hand "swim lane" of the BPEL
diagram. This is the "node" that will represent one of your web services.
4.
In the
Create Partner Link dialog paste in the URL of the sayHello web service (as saved
earlier) and append with "?wsdl" and tab out the field
5.
If a dialog
appears indicating: "There are no Partner Link Types defines in current WSDL,
do you want to create a new WSDL file that will by default create Partner Link
Types for you?" click Yes.
6.
Set the
Partner Role to helloWebService_Role
Click
OK.
7.
Repeat steps 2-6 for howAreYouWS
8.
Click the + on the Scope node to expand
it. From the component palette drop two Invoke nodes into the
newly expanded Scope area. Double-click on the name of each and
call the first invokeHello and the second invokeHowAreYou. These are the BPEL
invoke actions that will call your web services.
9.
Drag the arrow from the invokeHello
node to the helloWorthWebService partner link in the right hand
swim lane
10.
In the
Edit Invoke dialog click the Automatically Create Input Variable
button and the Automatically Create Output Variable button. Accept
the default values in the Create Variable dialog. In this step, you are creating
two variables: one to represent the input to the invoke action, and one to represent
the output from the invoke.
Click OK.
11.
Drag the arrow from the invokeHowAreYou node
to the howAreYouWebService partner link in the right hand swim
lane
12.
In the
Edit Invoke dialog click the Automatically Create Input Variable
button and the Automatically Create Output Variable button. Accept
the default values in the Create Variable dialog.
Click OK.
13.
From the component palette, drag an Assign
component and place it before invokeHello, name it Assign_1.
Repeat and place one before invokeHowAreYou and after invokeHowAreYou;
calling them Assign_2 and Assign_3 respectively.
14.
Double-click
on Assign_1. Select the Copy Operation tab and click Create
and then Copy Operation
15.
In the Create Copy Operation dialog, in
the left hand From list, expand inputVariable to its most granular
node (client:input) and select that node.
16.
In the right hand To list,expand the
tree to find the name of the input parameter to the invokeHello node to its most
granualar node and select that node.
Click
OK on to close the Create Copy Operation and then click OK to close
the tabbed dialog.
17.
Repeat steps 14-16 for Assign_2 and Assign_3. Ensure that the
value defined in the From list is the output parameter from the previous
invoke node. And that the value defined in the To list is the input to
the next invoke node. For Assign_3 the value defined in the To list should
be outputVariable
Click
OK on to close the Create Copy Operation and then click OK to close
the tabbed dialog.
18.
Click Save All
or select File | Save All to save your work.
Now that you have orchestrated
a number of web Services into a single BPEL service, you need to deploy that service
to your application server
To deploy the
BPEL service, perform the following steps:
1.
In
the Applications Navigator, right-click the HandsOnBPELProcess project and select
Deploy... from the context menu and select the name of your BPEL application
server (note the name may be different to that in the screenshot).
2.
In the Message Log and Apache Ant window,
you will see a message indicating that the BPEL Service has been successfully
deployed.
3.
You
can now test the BPEL service. From the SOA Launch console, click the link Application
Server Control on the top right of the page.
4.
If prompted, enter the username
and password
Click OK.
5.
Click
the Home link under the Members heading.
6.
Click the Web Services
link
7.
Find the name of the BPEL Service
you created (the name will contain the name of the project in which you built
the service) and click on that name
8.
Click the Test Service
link
9.
Copy the URL of the BPEL Service
to notepad. You will need to use this URL in a later step. Click the Test
Web Service button.
10.
Enter a string for the parameter
and click Invoke
11.
The resulting page will show
the XML message including the resulting string form the BPEL Service which concatenates
the input parameter with "Hello" <parameter> ", how are you?".
The
final step is to show that this BPEL service can now be easily consumed from your
own application code.
1.
In
the Applications Navigator, right-click the Applications node
and select New Application... from the context menu.
2.
In the Create Application dialog, enter the Application Name CallBPEL.
Select the Application Template No Template [All technologies]
from the Application Template dropdown list.
Click OK
and accept the default project name.
3.
Right-click
the new project and select New from the context menu.
In the New Gallery
select Web Service under the Business Tier node
and then Web Service Proxy.
ClickOK
4.
In
the Create Web Service Proxy dialog click Next if the Welcome screen is displayed.
When prompted for the WSDL Document URL paste the URL of the BPEL Process noted
earlier. Concatenate with ?wsdl
click
Next then Finish.
5.
JDeveloper will now display a Java client
file in the code editor. You need to add the following code:
HandsOnBPELProcessProcessRequest
payload = new HandsOnBPELProcessProcessRequest(); payload.setInput("Grant
Ronald"); System.out.println(myPort.process(payload).getResult());
click
Next then Finish.
6.
Click Save
All
or select File | Save All to save your work. Then compile all.
7.
Right
-click on the Java client and select Run from the context menu.
This will run the client which will call the BPEL Service and display the result
out to the Message Log
You
have used this simple example to publish business code as web services, and to
then combine those web services into a BPEL service which can then be called from
any application.
Bookmark
or select File | Save All to save your work. 
