Comparison: WLI File Control and the Oracle File Adapter

by Daniel Amadei and Heidi Buelow

This installment of the SOA Suite Essentials for WLI Users series maps WebLogic Integration's file control capabilities to their equivalents in Oracle BPEL Process Manager.

Published May 2009

Downloads for this article: Oracle SOA Suite

[ Page 1] [ Page 2] [ Page 3] [ Page 4]

Implementing the use case in Oracle BPEL Process Manager

To implement the use cases in this article using O racle BPEL Process Manager you must have Oracle SOA Suite and Oracle JDeveloper installed. You can use either the OC4J or WebLogic server for your SOA Suite.

Be sure to retain the password for the SOA Suite oc4jadmin or weblogic user.

Getting Started

You need the sample files provided for the use cases which includes schemas and input data. Unzip the sample files to a location on your machine such as C:\CompareWLI_BPEL\samplefiles. We will refer to this directory throughout the article. You will want to create an input and output directory to contain the files for testing, for example: C:\AdapterFiles\In and C:\AdapterFiles\Out.

Make sure your SOA Suite is running and start JDeveloper. Open the Connections Navigator from the View menu to create an Application Server connection to your SOA Suite. Right-click on Application Server and select New Application Server Connection. The selections are slightly different depending on your server.

• OC4J: Enter AppServerConnection as the name and select Oracle Application Server 10g 10.1.3 as the Connection Type and select Next. Enter oc4jadmin as the user name and enter the password for your installation. Select the Deploy Password checkbox and select Next. Enter the Host name for your server. The default OPMN port is 6003 and the default OC4J Instance home is home (these may be different on your installation). Select Next. Select Test Configuration and when you see the Success! message, select OK.
  
  
• WebLogic Server: Enter AppServerConnection as the name and select WebLogic Server 9.x as the Connection Type, then select Next. Enter weblogic as the user name and enter the password for your installation. Select the Deploy Password checkbox and select Next. Enter the Host name for your server, the port number (default is 8001), the target (default is OracleSOAServer), and the location of your weblogic.jar. (The default values may need to be changed for your configuration.) Select Next. Select Test Configuration and when you see the Success! message, select OK.

Next create an Integration Server connection using the Application Server connection you just created. Right-click on Integration Server and select New Integration Server Connection. Enter IntServerConnection as the name and select Next.

Select the Application Server that you created previously and enter the port number for the http protocol on your server. The default value for this is 8888 and 9700 for WebLogic (this may be different on your installation). Select Next.

Select Test Configuration and you should see a success message for the Application Server, the BPEL Process Manager Server and the ESB Server. Select OK.

Now let's create the application. This top-level application will contain three projects, one for each of the use cases. Each use case is implemented by a BPEL process, and each project can contain a single BPEL process. In the Oracle BPEL Process Manager runtime, each BPEL project runs independently, but in JDeveloper, you can include them all in one application.

The three use cases mirror the WLI use cases in this article as closely as possible. In WLI, the file control is similar to the BPEL file adapter. Where possible, the same naming has been used with the file adapter implementations to help correlate the similarities. When you are finished with all three use cases, your application in JDeveloper should resemble the the image below.

Now let's begin. Select the Application Navigator (if it is not visible, you can select it from the View menu). Right-click on Application and select New Application.

Enter FCTLApp for the application name and select OK.

A default project dialog opens. Because we want to create a BPEL project, not a default project, select Cancel on this dialog. The application is created.

Reading a Plain String from a File using BPEL

Now let's create the first BPEL project. This project is for our first use case, which reads a string from a file. First, we set up a web service which reads a file in a directory. We create this service using the BPEL file adapter. Next, we invoke the service and the service reads the file and passes the string to the BPEL process. If the file is not there, the service raises an error.

Right-click on your new application and select New Project.

Select BPEL Process Project under General/Projects for the project type.

Enter GetFileContentAsString for the process name. Select Synchronous BPEL Process for the template type. Select Finish.

The BPEL process is created with receive and reply activities. The BPEL process is a web service so a WSDL file is also created. We chose the default message type for the input and output for the web service, which is a string. Two variables are also created, inputvariable and outputvariable, which correspond to the input and output data for the web service.

All we have to do now is set up the file adapter web service and then call it.

On the Component Palette select Services from the drop down to see the service-related items. If you do not see the Component Palette, open it from the View menu. Drag a File Adapter to the Services pane on the right side of the BPEL designer screen to launch the file adapter wizard. Select Next to go to step 1.

Enter StringReaderFileControl for the service name and select Next.

Select Synchronous Read File for the operation type and select Next.

Enter the directory from where you will read the file. This should be a directory that is accessible by the server running your SOA Suite. It should be in the Windows or Linux path syntax as appropriate. Leave the remaining values at their defaults and select Next.

For the File name, enter stringContent.txt and select Next.

The last step is to set the format for the data being read. Select the Define Schema For Native Format button to start the native format builder wizard.

In step 1, select the Create new native format and Delimited radio buttons and select Next.

Use the Browse button to open the sample stringContent.txt file provided in your sample files directory. You'll see the text in the window. Select Next.

Select File contains only one record and select Next.

Enter the namespace as desired and enter mystring as the element name and select Next.

Select Next three more times to accept the defaults for the format specification and then select Finish.

Back in the adapter wizard you'll see the newly created xsd which defines your string data. Select Next and then select Finish.

The adapter service is now configured and you see the dialog for Create Partner Link. In BPEL, a partner link is simply a reference to a service. Select OK.

Your BPEL process will look like this:

Select Save All. Next you create a BPEL Invoke activity to call the service and get the string. The service will return the data into a BPEL variable that you define.

Change the Component Palette to Process Activities.

Drag an Invoke activity directly below the receiveInput activity. The activity highlights in yellow when it is in the right place.

Wire the invoke activity to the StringReaderFileControl partner link by dragging the left arrow to the partner link.

The Invoke Properties dialog opens. The partner link and operation are filled in automatically. Enter Invoke_String for the name. In BPEL, the Invoke activity requires both input and output variables even if we are not actually passing in any input to the service. Select the Auto-Create Variable button on the right for the input variable. This creates a variable to send data to the service. It automatically creates the message type. The auto-generated name of this variable is descriptive and you can leave it as is. In the Create Variable dialog, select OK. Repeat the Auto-Create Variable for the output variable but change the variable name to fileContent. In the Invoke dialog, select OK.

Your process now reads the string from the file and returns it in the fileContent variable. Let's now copy the string to the outputvariable, so the process will return the string.

Drag an Assign activity to just below the Invoke activity in your BPEL process. Double-click to open the Assign dialog. Select C reate -> Copy Operation.

On the From side, expand the fileContent variable you created for the Invoke output variable and select the final element. On the Target side, expand the outputvariable variable and select the final element. This Assign operation copies the data from one element to the other. Later, during deployment, BPEL will warn you that these may be incompatible types. Since you know they are not incompatible (both are strings), you can ignore the warning.

Select the green check at the top of the BPEL process window to validate the process. You'll see the yellow warning flags disappear except for the one on Invoke_String. This flag warns that the input variable is not initialized, but since that variable is not used by our service that warning can be ignored.

Select Save All. Your process is now complete. When it is started, it will look in the specified input directory for the file and read it, returning the data that was in the file as a plain string. Let's give it a try.

Right-click on the project name and select Deploy -> IntServerConnection -> Deploy to default domain. Watch the Apache Ant log window until you see the green Build Successful message. Your project is now deployed

Place a copy of the input file into your input directory. Now we can run the process.

To run the process, we use the BPEL administration console. Open a browser and enter the URL http://localhost:8888/BPELConsole,replacing localhost with the name of the server where you deployed your service (if it is not your local machine) and replacing the port number with 9700 (if you are using the default WebLogic port for the BPEL Console). Login with the user oc4jadmin or weblogic and the password for your configuration.

The BPEL Console opens to the Dashboard, which shows all of the deployed BPEL processes. Select your GetFileContentAsString process to open the initiate page.

Select Post XML Message. The synchronous process starts, reads the file, copies the data to outputvariable, and returns the value to the browser window. You can see the string that was read from the file in the browser.

Check your input directory. The file is gone. Your service found the file and processed it. Let's go back to the BPEL Console to view the audit trail and see the details of our process instance.

Select the Instances tab. Here you see any running and completed instances. Your GetFileContentAsString process instance is listed here. Select the instance to view the audit trail. The audit trail opens in graphical mode on the Flow tab. Notice that it resembles the design view of your process. You can also view a textual audit trail using the Audit tab.

Select the Invoke_String activity to view the service data. You see your string in the output of the file adapter service call.

Try running the process again, this time with no file in the directory. In this case, an error is raised by the adapter service but it is not caught anywhere so the process faults. You can view the results in the BPEL audit trail.

We can change our process to catch the error and return a meaningful error message. We want to put a scope around the Invoke so that we can catch the error and continue after the defined scope. First, drag a Scope activity directly above the Invoke activity.

Expand the Scope activity by selecting the plus sign ( +), and then drag the Invoke and the Assign activities into the Scope.

Now let's add a fault catcher. Select the Add CatchAll Branch icon in the Scope frame. Expand the branch and drag an Assign activity into it. Double-click to open the Assign. Select Create -> Copy Operation. On the From side, select Expression as the type and enter " Error reading file". On the Target side, expand the outputvariable variable and select the final element.

Select Save all. Your process is complete and should look like this:

Your process now returns either the string from the file or an error message (if there is an error reading the file). Deploy your new version of the process. You are asked for a version number because there is a 1.0 version of this process has already been deployed. Enter 1.1 for this version to keep both versions available for review. Now run your new version. This time, if there is no input file in the directory, you'll see the error message immediately in the browser.

Your ReadStringFromFile process shows how to create a service to bring a string into a process and also how to handle any errors. You can extend your BPEL process to do operations on that string such as passing it to another service or sending it to a user with a human task or email notification.

Let's try the next use case now. Go back to JDeveloper and close any open files.

Receiving an XML, transforming to another schema and writing to a file using BPEL

In this use case, we call a BPEL process with some input data and transform it to our desired output schema and write it to a file. First, we need a project. Right-click on your application and select New Project. Select BPEL Process Project under General/Projects for the project type. Enter TranslateStockProcess for the process name. Select Synchronous BPEL Process for the template type, then select Next.

The request and reply schemas are defaulted to a simple string so let's change them to be the input stock and output partner stock schemas. Select the button to the right of the Input Schema Element box and browse to your sample files directory. Select stocks.xsd as the xsd to import.

Then open the xsd and select the stocks element.

For the Output Schema Element, you first see the Type Chooser window since a schema has already been imported. Select the Import Schema button at the upper right.

Browse to and select STOCKS_PARTNER.xsd.

Then select the STOCKS element.

Select Finish. The project is created.

Because this process uses the synchronous template, Receive and Reply activities and a client service reference have already been created. We need to add the file adapter service to write the data.

Drag a file adapter to the Services pane on the right side of the BPEL design screen. Select Next to go to step 1.

Enter writePartnerSchema for the service name and select Next.

Select Write File for the operation type and select Next.

Enter the directory to which the file will be written. This directory should be accessible by the server running your SOA Suite. It should be in the Windows or Linux path syntax, as appropriate. For the File Naming Convention, enter partnerStocks%SEQ%.xml_. The special string %SEQ% is replaced by the next number in the sequence when the file is written. In this way, you can run your process multiple times and not overwrite your output file. Leave the remaining values as defaulted and select Next.

The last step is to set the format for the data being written. This time, we are writing the data in xml format, so browse to select the schema which has already been imported.

Select the STOCKS_PARTNER.xsd and the STOCKS element. Select Next and then Finish.

The adapter service is now configured and you see the dialog for Create Partner Link. Select OK.

It does not matter which side you choose to place your service references, but by convention, we usually use the right side for references the process invokes and the left side for references the process receives. You can switch the side easily by right-clicking on the partnerlink icon and selecting Display->Move to opposite swim lane.

Now let's invoke our new service.

Drag an Invoke activity to the BPEL process between the Receive and Reply activities.

Enter Invoke_WriteStock for the name, select the Automatically Create Input Variable button to the right of the Input Variable box. Change the input variable name to stocks. Select OK. Select OK to set the invoke properties.

The last step is to copy the input data to the input variable for the service. We can do this using a BPEL Transform activity. Drag a Transform activity directly above the Invoke activity. Set the source to inputvariable. This variable was created automatically for you when the project was created. It is defined to be the element type you set for input when you created the BPEL process. Set the target to stocks variable. Set the file name to TransformStock and select the Create button.

Wire the source stock to the target STOCKS and select OK on the auto-select dialog. The transform tool wires the fields that it can match by name (a dictionary could be added to match up commonly used field names if desired). Wire any remaining fields. Then, because we can have multiple rows of source data, we add the xslt for-each construct. Drag that from the Component Palette XLST Constructs palette to the target STOCKS element. Then wire the source stocks element to the for-each construct.

One last step is to set the output variable to the partner stocks value as well. This is not strictly necessary because we are writing the results to a file, but it makes it easy to see the result when we test the process in the BPEL Console.

Drag an Assign activity below the Invoke activity. Double-click to open it. On the General tab, set the name to Assign_Output. On the Copy Operation tab, select Copy Operation from the Create menu.

You will notice two warning flags on the Invoke and Assign activities. JDeveloper is warning you that the variable you are using has not been initialized. In fact, the transform does initialize the Invoke_Write_Input, but JDeveloper does not recognize it. The warnings can be ignored. Right-click on the project name and select Deploy -> IntServerConnection -> Deploy to default domain. Watch the Apache Ant log window until you see the green Build Successful message. Your project is now deployed.

Open a browser and enter the URL http://localhost:8888/BPELConsole, replacing localhost with the name of the server where you deployed your service if it is not your local machine and 9700 for the port if you are using the default WebLogic port. Login with the user oc4jadmin or weblogic and password for your configuration.

On the dashboard, you see your new process, TranslateStockProcess. Select the process to go to the initiate page for this process. You will see the HTML form for the input schema. Enter some data. You can select the green plus sign to enter another row of data. Select P ost XML Message.

The process is initiated with the input data. Since it is a synchronous process, the reply is sent immediately back to the browser window. You can also select the Visual Flow icon to view the graphical audit trail.

The file was written to the output directory. Locate the file and view the contents. The output is in xml format according to the STOCKS_PARTNER schema.

In this use case you learned how to write a file with the data in the BPEL process. You transformed the data into the format expected by the file adapter service. You also learned how to use the BPEL Console to test your service by initiating the process and entering the input data manually. You can extend your BPEL process to manipulate the data in other ways or even call your BPEL process from another service and pass in the data that way.

Let's move on to the last use case. Go back to JDeveloper and close any open files.