BPEL SOA Suite Essentials for WLI Users

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

In this article:

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

Introduction

One of the most basic things in IT today is a file. Files are everywhere! From mobile devices to corporate servers, passing through your personal computer, you will always find a file.

When integrating, especially with external or legacy applications, you will certainly find the requirement to read, write or manipulate files at some time.

Manipulating files can become an error-prone (leave a file open every time you read it and you will see) and repetitive task (the steps are basically the same, no matter what you are doing). To make it easier to work with files, integration tools have created solutions that add a level of indirection and remove from the developer some of the cumbersome tasks when dealing with files.

The purpose of this article is to show how both Oracle WebLogic Integration (WLI) and Oracle SOA Suite, specifically BPEL Process Manager (BPEL PM) deal with files and make file manipulation easier for you. This article is comprised of two introductory sections that provide an overview of the technology employed by both products regarding file manipulation. For WLI, we deep-dive into the concept of a File Control, which is the component responsible for synchronously manipulating files. We do the same for BPEL PM, explaining its File Adapter and the surrounding concepts.

Then, after this theoretical explanation, we move to some practice, where we implement three use cases using both tools. Please see Oracle BPEL Process Manager for more information about BPEL PM.

WLI File Control

Understanding the control and its role in the WLI Architecture

A control is a component whose main purpose it is to simplify access to resources and do it in a uniform way. You customize a control and use it inside your WLI process through an interface which extends the base control's interface. This way, a custom version of a control is made available in the form of a Java interface with the implementation created behind the scenes for you.

The instantiation of the control is another interesting point. Since you do not have access to the control's implementation class, it does not make sense to have to instantiate the control through it. That is why the control's instantiation is made through dependency injection, reducing the coupling between your process and control's implementation.

A control is exposed as a plain old Java interface and it makes its functionality available through standard Java methods. When the methods aren't customized by the developer, they are simply inherited from the parent interface. Otherwise, they are generated based on the configurations you make when creating the control file. To use a method, you simply drag it from the file control's list of available methods and drop it in the position where you want it to be executed in your process. You may then configure the required sent or received values that the method expects or returns, respectively.

The following image shows a Process where a read method was dragged from a control and dropped into the process. The green checkbox means that the method is completely configured.

process.png

Manipulating files through a control

As you may guess, file manipulation is available in WLI in the form of a control: the File Control. When you create the File Control you customize the following information:

  • Directory
  • File name or File name filter
  • Type of Data
  • Encoding (available when dealing with String or XML as the Type of Data)

When dealing with large files, you can specify some delimiters, so the file won't be loaded entirely in memory at once. The image below shows the screen which allows you to enter these parameters when creating a File Control.

control_config3.png

The interface generated when a File Control is added to a process will have the following methods inherited from the com.bea.control.FileControl (some are omitted but you can find all of them in the WLI Documentation and the corresponding javadoc.

  • copy(String fileName): Copies the current file to the specified file name.

  • delete(): Delete the current file.

  • rename(String fileName): Renames the current file to the specified file name.

  • FileControlFileListDocument getFiles(): Returns an iterator for the File objects matching the specified file mask in the current directory.

  • FileControlPropertiesDocument getProperties(): Gets the dynamic properties for the control

  • setProperties(FileControlPropertiesDocument xmlProp): Sets the dynamic properties for the control

As you may have noticed, the last two methods work with a concept of Properties. These properties are an instance of an XMLBeans class, generated from an XSD which packages with WLI. Through the use of the properties class, you can customize the behaviour of the control at runtime. For example, you will be able to change the directory where you want your files placed based on the value of an instance variable of your process. Based on the customization parameters you give when you create the control, especially the Type of Data, the following methods are created and added to your Java interface:

  • FileControlPropertiesDocument write(<Type of data>): write content to the file, based on the type of data you choose

  • <Type of data> read(): read content from the file, based on the type of data

  • append(<Type of data>): append content to the file, not available when the type of data is XML

At this point you already know that with a file control you can easily:

  1. Write, read and append data to a file
  2. Manipulate files: copy, rename and delete
  3. List the contents of a directory.

Among the type of data that can be written to and read from files, we have:

  • RawData (binary)
  • String
  • XML (by reading and writing XML, the file control handles the conversion of XML content to its Java representation and vice-versa using the XML Beans binding framework).

Files and directories can be accessed:

  • Locally in Windows and Unix systems;
  • Through the network in the form of an FTP, SFTP or UNC.
As you may have noticed, the file control is responsible for synchronously manipulating files. When you want to do some kind of file polling, you should refer to WLI Event Generators, which is a theme for another article in the SOA Suite Series.

Oracle File Adapter

Introduction to the Oracle Application Server File Adapter

There are three types of Oracle Application Server adapters: technology, packaged application, and legacy. Oracle Adapter for Files is a technology adapter. Technology adapters are based on J2EE Connector Architecture (J2CA) 1.5 standards and deployed as a resource adapter in the same J2EE container as BPEL Process Manager.

Adapters convert native APIs to standard XML and back based on the adapter metadata configured during design time. Adapters use design-time tools that provide a graphical user interface (GUI) to configure and administer adapters for fast implementation and deployment.

BPELAdapterArch_smaller.png

Inbound and Outbound Interactions

The file adapter exchanges files in the inbound and outbound directions. Based on the direction, the file adapter performs a different set of tasks.

Adapters support the event-notification service, which is an asynchronous communication paradigm. In J2CA terminology, this type of service is also known as inbound interaction. The J2CA inbound interaction is captured in a WSDL file during design time. For inbound files sent to Oracle BPEL Process Manager, the file adapter performs the following operations:

  1. Poll the file system looking for matches
  2. Read and translate the file content based on the native schema (NXSD) defined at the design time
  3. Publish the translated content as an XML message.

Adapters support the synchronous request-response service. In J2CA terminology, this type of service is also known as outbound interaction. BPEL Process Manager uses the WSIF technology to start the request-response service of the resource adapter. WSIF is used for calling web services and separating the abstract part of the web service definition from the physical binding (transport and protocol) to generate a Service-Oriented Architecture (SOA). For outbound files sent from Oracle BPEL Process Manager, the file adapter performs the following operations:

  1. Receive messages from BPEL PM
  2. Format the XML contents as specified at design time
  3. Produce output files. The output files can be created based on following criteria: time elapsed, file size, and number of messages. You can also specify a combination of these criteria for output files.

File Formats

The file adapter can read and write the following file formats and use the adapter translator component at both design time and run time:

  • XML (both XSD- and DTD-based)
  • Delimited
  • Fixed positional
  • Binary data
  • COBOL Copybook data
  • Binary (e.g., JPG)

The translator enables the file adapter to convert native data in various formats to XML. The native data can be simple (just a flat structure) or complex (with parent-child relationships).The translator can handle both XML as well as non-XML (native) format of data.

Adapter Statistics

In BPEL Process Manager 10.1.3 several Technology adapters, such as File, JMS and Database, gather and publish statistics for every message they process either inbound or outbound. The statistics are broken down into categories and individual tasks. The following is an example of how statistics are broken down in an outbound process:

  • Adapter Preprocessing
  • Preparing InteractionSpec
  • Adapter Processing
  • Setting up Callable Statement
  • Invoking Database
  • Parsing Result
  • Adapter Postprocessing

The adapter statistics can be viewed in the BPEL Console, from the same page where the BPEL engine statistics are available. The following are the steps to view the adapter statics in the BPEL Console:

  1. From the front BPEL PM Console page, follow the link Manage BPEL Domain.
  2. On the next page, click the link Adapter Statistics.

This shows a list of all currently active inbound and outbound adapter interactions, and the average execution time for the various steps each adapter performs.

To reset the statistics gathering, click the Clear Statistics link.

For more information, see the Oracle File Adapter User Guide.

Use Case Example

This use case example has three parts:

  1. Read the content of a file as string

  2. Create a process that receives Stock quotes using one XSD, transforms the data and writes the contents to a file as XML

  3. Create a process that reads from the file that was written in part 2 and transforms it to a CSV file, writing it to a FTP directory.

You will need CompareWLI_BPEL.zip for sample files required to implement these use cases (schema, input data, etc). This sample files folder is referenced throughout the article. This zip also contains the projects built using these instructions.

Implementing the use case in WLI

Reading a plain string from a file using WLI

Creating the Process Application

To be able to execute the WLI samples contained in this article, you will have to first create a process application and deploy it to a WLI domain. For the domain creation procedure, please see Using the Domain Configuration Wizard.

To create the Process Application, just follow the steps below:

  1. Access Oracle Workshop for WebLogic;
  2. Right-click an empty area of Package Explorer and select New | Project;
  3. In New Project screen, expand WebLogic Integration and select Process Application;
  4. Click Next.
  5. Enter the following:
    • EAR Project Name: FCTLApp
    • Web Project Name: FCTLAppWeb
    • Utility Project Name: FCTLAppUtil
    • Select the check-box " Add Weblogic Integration System and Control Schemas to Utility Project"
  6. Click Finish.

Reading the file content as string

In this first step, we will read file contents as a String and simply print it out to the standard output.

Make sure you are working inside the Process perspective. Expand FCTLAppWeb, src and right-click the process package. Select New, Process as shown below.

new_process.png

Enter GetFileContentAsString as the name of the process and complement the package with useCase01, making it processes.useCase01. Leave the other options as they are and click Finish. The screen to select the Start Event of the process, similar to the screen below, will be shown.

process_screen1.png

Double click the white square to select a start event for your recently created process. The screen below will be shown. Select " Invoked synchronously via a Client Request with Return" and click Close. Doing this will cause your process to be synchronous and force the return of information to the consumer.

select_start_event.png

The process flow will be updated. Right click the new group and select Open Return Builder. The following screen will be shown. Click the Select... button.

configure_return.png

You will now be able to configure the return settings for your process. In Parameter Name enter fileContent; this will be the name of the return parameter for this process. In Type Name we will select to return a String. You can click Browse to find the String class by yourself or click the Simple tab and select String at the end of the list. Click OK and you will be able to click " Send Data", where you will inform WLI what to send as the fileContent parameter you just created.

In the " Select variables to assign" field, select " Create new variable...," as illustrated in the image below. This will send the value stored in this variable as the response to the consumer of this process, so we will have to store some value in it during execution. You will soon see how to store value to this variable.

create_var_send_data.png

Name the variable fileContent and click OK. Click the Close button. A green checkbox will appear in the upper right of the " Client Request with Return" group, indicating that it is configured and error-free.

At this point, your process receives a request with no input data and returns the contents of a variable named fileContent in the form of a String. We should now proceed to reading the file and storing its contents in the fileContent variable, so it will be returned to the consumer.

On the D ata Palette (placed at the bottom right of the WorkSpace screen), click the arrow and select Integration Controls | File, as shown below.

add_file_control.png

An " Insert Control: File" screen is presented. Keep f ileControl the Field Name. (This will be the name of the property inside your java file representing the control instance.) Click Next.

You will be asked to enter the Java class name. This name will be given to the Java interface of your control. Name it StringReaderFileControl and click Next.

It's a good practice to place your controls inside the Utility project, so they will be shared and can be reused among projects. To make this tutorial less verbose, we decided to create it inside the web project.

A screen will be presented to you to specify the information regarding the file which will be accessed by the control. Enter the data as shown below and click Finish.

insert_control_file.png

Once the control is defined it becomes available inside the Data Palette, Controls section. You will see the fileControl element, which can be expanded and will look similar to the image below. Select a method from the list, drag it to your process and drop it where you want it to be executed.

control_methods.png

Select the " String read()" method from the list and place it inside the " Client request with return" group as shown below:

control_dnd.png

After that you'll see the read node with a grayed check-box at the top right. As already mentioned, this means the node still needs to be configured, so double click it.

On the screen shown, select Receive Data and in " Select variables to assign", select the variable fileContent from the drop-down. A green check-box will appear next to your process. Click Close. Your process will look like the following image:

process_finished.png