| 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
In this article:
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.
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.
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:
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.
The interface generated when a File Control is added to a process will have the following methods inherited from the
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:
At this point you already know that with a file control you can easily:
Among the type of data that can be written to and read from files, we have:
Files and directories can be accessed:
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.
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.
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:
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:
The file adapter can read and write the following file formats and use the adapter translator component at both design time and run time:
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.
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:
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:
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.
This use case example has three parts:
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:
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.
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.
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.
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.
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.
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.
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.
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.
Select the " String read()" method from the list and place it inside the " Client request with return" group as shown below:
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: