Zenflow Weather2 Tutorial
Table of Contents
Chapter 3. Weather2
Process Flow
Chapter 4. Load
“weather2” BPEL Process Into Zenflow
4.1 Create a New Project in the Workspace
4.2 Import the weather2 Sample
4.3 Open the Weather2 File for Display
4.4 Import the Associated WSDL File
Chapter 5. Examine
Weather2 Steps in Zenflow
5.1 Step 1 – BPEL Process Receives Input From Client
Application
5.2 Step 2 – BPEL Process Passes US Address to the Geocoder Web
Service
5.3 Step 3 – Geocoder Returns Latitude and Longitude
5.4 Step 4 – BPEL Process Passes Latitude, Longitude, and Date
to NWS
5.5 Step 5 – NWS Returns Weather Forecast
5.6 Step 6 – BPEL Process Returns Weather Forecast to Client
Application
Chapter 6. Deploying
and Running the “weather2” BPEL Process
6.1 Clean Any Existing Deployment
6.2 Deploy the New "weather2" Process
6.3 Run the “weather2” Process
List of Figures
Figure 3‑1. Weather2 Data Flow
Figure 4‑1. “weather2.bpel” Node and outline displays
Figure 4‑2. WSDL File Information Dialog Box
Figure 5‑1. “Receive” Activity Properties for Weather2
Figure 5‑2. Partner Links Definition Dialog
Figure 5‑3. Variables Definition Dialog
Figure 5‑4. Assign Definition Dialog
Figure 5‑5. “Invoke” Activity Properties Dialog
Figure 5‑6. Output Variable in Variables Definition
Dialog
Figure 5‑7. Assign Statement Following the “Invoke”
Activity
Figure 5‑8. “nwsRequest” Variable in Variables Definition
Dialog
Figure 5‑9. Assign Definition Dialog Showing Final
”Assign” Activity
Figure 5‑10. Properties Dialog for Final “Reply” Activity
Preface
This tutorial is oriented to the user that has some experience with Zenflow, BPEL, and WSDL. It is intended to demonstrate how Zenflow represents various aspects of BPEL and WSDL.
This tutorial will use Zenflow to examine the “weather2” sample. This sample is an extension of the “weather” sample. The “weather2” sample is closer to a real world BPEL application than the “weather” sample. It uses data from two independent Web services in order to achieve the desired result.
Two external Web services are used in this tutorial. The Geocoder Web service returns the latitude and longitude for a US street address. The second Web service returns the weather forecast for a given US location identified by latitude and longitude. The user should examine these target Web services at:
This tutorial assumes the following:
· the Zenflow plug-in is installed in Eclipse 3.2 or later
· the user is familiar with basic Eclipse concepts
· the user has some working knowledge of Zenflow, BPEL, and WSDL
This tutorial will examine the weather2 Orchestra sample. No changes will be made to that sample.
The “weather2” sample makes use of two external Web services:
1. Geocoder – This Web service takes a US address as an input parameter and returns the latitude and longitude for that address.
2. National Weather Service – This Web service takes a US location in the form of latitude and longitude as parameters and returns the weather forecast for that location.
By “Orchestrating” these two Web services together, the “weather2” sample is able to return a weather forecast for a given US address. This is illustrated in the following diagram.
Figure 3‑1. Weather2 Data Flow
The process flows as follows:
3. The java client application sends a US address and the current date to the weather2 BPEL process.
4. The BPEL process invokes the Geocoder Web service, passing the US address as a parameter.
5. The Geocoder Web service returns the latitude and longitude for the specified address.
6. The BPEL process extracts the latitude and longitude from the Geocoder response and invokes the National Weather Service. The current date from the java client is also used as a parameter to the NWS.
7. The NWS returns the weather forecast for the specified location.
8. The forecast is extracted from the NWS response and is returned to the java client.
The Zenflow plug-in works on BPEL files that are part of a project in a workspace. Perform the steps described in this chapter to create a new Eclipse project and import the weather2 BPEL file into that project.
1. Start Eclipse and select a workspace.
2.
Then use the following menu sequence "File ‑>
New -> Project" and select
General‑> Project to create a new "Simple" project. The project name is user defined;
"weather2" is used here as an example.
1. Right click on the "weather2" project folder in the package explorer view and select the "Import" menu item.
2. Then select the option for importing from the "File System".
3. Use the Browse button to go to the "weather2" samples folder that is part of the Orchestra installation. This will be in a location similar to:
"Orchestra installation
location"\BPEL\samples\weather2
4. Expand this directory in the "File System Import" dialog and select the check box next to the "weather2.bpel" file. DO NOT import the WSDL file using this dialog.
In the package explorer, expand the "weather2" project node. Then double click on the "weather2.bpel" node to open it in the main display window. The display should look similar to the following.
Figure 4‑1. “weather2.bpel” Node and outline displays
Notice the problems identified in the "Problems" window. These have occurred because the Zenflow syntactic analyzer cannot find definitions for all the data types used in the BPEL file. The definitions are not available because the WSDL file for the process has not been loaded yet.
Go to the next step to load the WSDL file for the process.
Once the Zenflow plug-in has been referenced by opening a BPEL file, a new "Zenflow" main menu is added to the Eclipse menu bar.
Now use the WSDL dialog to import the necessary WSDL files. Use the main menu "Zenflow -> Link WSDL files..." to access this dialog. If the menu is disabled, left click on the blue background of the graphic window to enable it. Then use the "Add local WSDL file" button to add each of the following WSDL files:
"Orchestra installation location"\BPEL\samples\weather2\weather2.wsdl
"Orchestra installation location"\BPEL\samples\weather2\nws\ndfdXML.wsdl
"Orchestra installation location"\BPEL\samples\weather2\geocoder\GeoCoder.wsdl
The WSDL dialog should now appear as follows.
Figure 4‑2. WSDL File Information Dialog Box
Notice that there is now a file associated with each namespace. A missing definition of the BPELJ namespace is OK at this point. Press the "OK" button to close the dialog.
|
Note: A current program bug prevents the "Problems" window from being refreshed at this time. Closing and opening the project containing the BPEL file, and then double clicking on the BPEL file in the package explorer view will refresh the Problems view. |
This section will use Zenflow to examine the BPEL activities and data associated with the weather2 BPEL process. Each section below describes one of the “steps” identified in Section 3, Figure 3‑1. Various aspects of the BPEL and WSDL relations will be described. However, this is not intended to be an exhaustive analysis of the process. The descriptions concentrate primarily on the data flow within the process.
A BPEL process receives data from clients in the context of BPEL “receive” activities. In the Bull Orchestra engine, the receive activity, together with a reply activity, constitute a method with input and output messages in a Web service that is represent by the BPEL process. Displaying the properties for the “receive” activity in weather2 shows the following:
Figure 5‑1. “Receive” Activity Properties for Weather2
The important properties are as follows:
Create Instance = Yes – This property tells the BPEL engine that a new process instance is to be created when a client program calls the method represented by this receive activity.
Partner = weather – This property is the reference to the partner link. Use the main menu Zenflow -> PartnerLinks to display this dialog:
Figure 5‑2. Partner Links Definition Dialog
Notice that a “weather” partner has been defined in which “myRole” is “service” and the partner Link Type is “p3859:weatherPLT”.
Now use the main menu Zenflow -> Link WSDL Files and select the “WSDL Element definition tab”. This displays all the WSDL elements that have been loaded as a result of importing the WSDL files. Notice the following lines:
PartnerLinkType:(Ref:1)p3859:weatherPLT
Role:(Ref:p3859)service Ref:6
PortType (Ref:6):Name: 6:weatherPT
Operation:process
input:6:weatherSoapRequest
output:6:weatherSoapResponse
This indicates that the Web service implementing weatherPLT has a “service” role that defines a “weatherPT” port type, which in turn has a “process” operation that has input/output parameters of weatherSoapRequest and weatherSoapResponse respectively.
Collectively, this means that the “receive” statement in the weather2 BPEL process is implementing the input side of the above function definition.
Port Type = p3859:weatherPT – This is the reference to the port type. As seen in the WSDL elements above, this indicates that this receive statement is implementing the port type defined in the WSDL.
Variable = weatherRequest – This is the BPEL variable that will receive the data passed as a parameter by the client application. The variables type must be weatherSoapRequest, as defined in the WSDL element above. Use the main menu Zenflow -> Variables to display the variable definitions for the process as shown:
Figure 5‑3. Variables Definition Dialog
As can be seen, the “weatherRequest” variable referenced in the receive activity is of type “p3859:weatherSoapRequest” as is needed to satisfy the requirements of the interface.
The first “Assign” activity copies the address from the input variable to the variable used to invoke the Geocoder Web service. Select the “Assign” activity and look at the “Assign definition”. The copy statements are shown below:
Figure 5‑4. Assign Definition Dialog
The first copy statement is for debug purposes only. It copies the input address from the “location” part of the input message to the “result” part of the output message.
The second copy statement copies the input address to the “location” part of the geocodeRequest variable. This variable is of type “p2210:geocodeRequest”. This type can be seen by using Zenflow -> Link WSDL Files and select the “WSDL Element definition tab”. The message definition is shown below:
message (Ref:13):geocodeRequest Ref:13NamRef:p2210
part name:location Ref:13 type:string Ref:9
The geocodeRequest variable is passed to the Geocoder via the “Invoke” activity. This can be observed in the properties of the “Invoke” activity as shown below:
Figure 5‑5. “Invoke” Activity Properties Dialog
In addition, notice that the “Output variable” is “geocodeResponse”. These variables can be seen in the variables dialog as shown in the following figure.
Figure 5‑6. Output Variable in Variables Definition Dialog
The Geocoder Web service returns its results in the geocoderResponse variable. The geocodeResponse variable is of type “p2210:geocodeAddressResponse”. Again displaying the WSDL element in the WSDL dialog shown the following message definition:
message (Ref:13):geocodeAddressResponse Ref:13NamRef:p2210
part
name:results Ref:13 type:ArrayOf_GeocoderAddressResult Ref:13
Now examine the properties for the assign statement following the geocode invoke, and examine the “Assign definition”. The copy statements are shown below:
Figure 5‑7. Assign Statement Following the “Invoke” Activity
The first two copy statements extract the latitude and longitude from the geocodeResponse variable to the nwsRequest variable. The third copy statement copies the current data from the weatherRequest input variable to the nwsReqeust variable. The final two copy statements set up the other required data in the nwsRequest variable.
The variables dialog can be used to examine the type of each variable as shown below:
Figure 5‑8. “nwsRequest” Variable in Variables Definition Dialog
It can be seen that the nwsRequest variable is of type “p9807:NDFDgenByDayRequest”. This type can be seen by using Zenflow -> Link WSDL Files and select the “WSDL Element definition tab”. The message definition is shown below:
message (Ref:6):NDFDgenByDayRequest Ref:6NamRef:p9807
part name:latitude Ref:6 type:decimal Ref:9
part name:longitude Ref:6 type:decimal Ref:9
part name:startDate Ref:6 type:date Ref:9
part name:numDays Ref:6 type:integer Ref:9
part name:format Ref:6 type:string Ref:9
It can be seen that there is a copy statement to initialize each part of the message definition. It is necessary to consult the NWS Web service definition and WSDL to fully understand this interface.
The final invoke passes the above information to the NWS Web service. The returned weather forecast is returned in a string containing an XML document. This string is returned in the nwsResponse variable. This variable is of type “p9807:NDFDgenByDayResponse”. This message type can be seen by using Zenflow -> Link WSDL Files and select the “WSDL Element definition tab”. The message definition is shown below:
message (Ref:6):NDFDgenByDayResponse Ref:6NamRef:p9807
part name:dwmlByDayOut Ref:6 type:string Ref:9
The final “Assign” activity copies the NWS return data to the variable that is returned to the client of the BPEL process. The copy statement for this is shown below:
Figure 5‑9. Assign Definition Dialog Showing Final ”Assign” Activity
As can be seen, this copy statement extracts the dwmlByDayOut part and puts it into the weatherResponse “result” part. This is returned to the original client in the final “Reply” activity. The properties for the final reply are shown below:
Figure 5‑10. Properties Dialog for Final “Reply” Activity
This section explains how to run the “weather2” BPEL process that has been described in this tutorial. This assumes that the user has the BSOA Orchestra engine running (use “bsoap start”, if it is not), and the computer has Internet connectivity to www.weather.gov and rpc.geocoder.us in order to actually call these external Web services.
|
Note: Check the Orchestra proxy settings in the “Orchestra_install_dir”/bpel/build.properties to ensure that access to external networks is properly configured. |
Each time a new version of the process is defined, it is necessary to ensure that any previous deployment of the process is removed. This can be done with the following Orchestra command line:
bsoap clean -p weather2 -samples
|
Note: The Deploy action described in Section 4.2, “Deploy the New “weather2” Process,” does a “clean” operation as part of its processing. |
The weather2 process can be deployed into the BPEL engine. This causes the WSDL and BPEL files to be scanned and the corresponding code is generated and compiled.
From the “Orchestra installation location”\BPEL\samples\weather2 directory, use the following command line:
bsoap
deploy -p weather2 -samples nws/ndfdXML.wsdl geocoder/GeoCoder.wsdl
During this step, there is a significant amount of output in the Orchestra command window about the results of the deployment. This should be examined carefully to determine if the deployment is successful. Errors at this point are likely to be typographical errors.
Now it is time to run the weather2 BPEL process. To do so, it is necessary to have a client program that accesses the first "Receive" statement by sending the appropriate message. The client is provided for the weather2 sample. The source code for this client can be seen at:
This client program takes one input parameter, and builds the input message needed by the weather2.bpel process. The input parameter is either an integer from the following list, or a US address in single quotes. If no parameter is entered, or an invalid parameter is entered, then the following is displayed:
>>>>> ERROR: Enter a single integer value to select an address from the following list:
>>>>> 1 = 1600 Pennsylvania Avenue, Washington DC
>>>>> 2 = 601 Whitehead St, Key West, Fl
>>>>> 3 = 13430 N Black Canyon Highway, Phoenix Az
>>>>> 4 = 400 Broad St, Seattle Wa
>>>>> 5 = 233 Wacker Drive, Chicago Il
>>>>> 6 = 350 Fifth Ave, New York NY
>>>>>
>>>>> Or enter a complete US address within single quotes.
For example, the following command line will display the weather forecast for the US Capitol:
bsoap launch -p weather2 -cc org.objectweb.orchestra.samples.weather2.Weather2Client 1
The following is an example of entering an address directly:
bsoap launch -p weather2 -cc org.objectweb.orchestra.samples.weather2.Weather2Client '233 Wacker Drive, Chicago Il'
|
Note: This address should be entered on one line. It is displayed on two lines here due to the page-size limitation. |
When a valid parameter is entered, the BPEL process is invoked, which in turn sends the data along to the Geocoder and National Weather Service Web services as described in this tutorial. The resulting xml document, which contains the weather forecast for the selected location, is displayed.