| 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
It's important to understand what we did in this step: dragging the read method to the process will cause the file specified for the File Control to be read. As the read method returns a String, we selected an already created variable to store the return, the fileContent variable. As we had already selected the variable fileContent as the variable to be returned by the process, we will be returning the file contents as we used this variable to store the contents read from the file.
Execute the process by right-clicking it and selecting Run As, Run On Server. You will see the Test Console displayed as shown below:
Using the test console you will be able to perform many tasks, from getting the WSDL of the process to visualizing the process graph, to going to testing pages which allow you to test your process quickly, among other tasks. We will use it to test our recently created process.
Create a file named stringContent.txt inside /tmp/repository directory. Enter the following text inside the file: I will be read by WLI File Control!
Execute the process by selecting the Test Form tab, then clicking the button clientRequestWithReturn. You will see in the Service Response section that the contents of the file were read and returned by your process as shown below:
Receiving an XML, transforming to another schema and writing to a file using WLI
In this sample you will receive an XML document compliant to a XSD schema, transform it to another schema representing the scenario where you have to translate a document to be compliant to the schema expected by some supplier or partner. At the end, we will write the transformed XML to a file using the WLI File Control.
Make sure you are working inside the Process perspective. Expand FCTLAppWeb, src and right-click the processes.useCase01 package and select New | Process.
Change the name of the package to processes.useCase02. Enter TranslateStockProcess as the name of the process, leave the other options as they are, and click Finish. The screen to select the Start Event of the process will be shown.
Select the start event as Invoked via Client Request as shown below.
From the sample files folder, copy the files stocks.xsd and STOCKS_PARTNER.xsd to the schemas folder of the FCTLAppWeb project. The schemas will be interpreted and compiled in the form of XMLBeans classes. The compiling should happen instantaneously and the resulting classes will be available in your project's classpath. We will use the stocks element defined in stocks.xsd file as the input document for this process.
Double click the Client Request node in order to add input parameters for your process. The screen below is shown.
Click " Add..." to add a new input parameter. The screen to select the name and type of the parameter is shown. In Parameter Name enter the name of your recently added parameter as stocks. For the type selection, you can choose it manually by clicking " Browse..." or select from the types found by WLI by selecting a value from the tabs Simple, XML or Non-XML. As the type we will select was derived from XML, click the corresponding tab.
Inside the XML tab, expand FCTLAppWeb | schemas | stocks.xsd and select the stocks element. This follows the structure of the XSD file you copied to the schemas folder.
The configuration of the input parameter should be identical to the image below. Click OK at the end.
Now it's time to store the value received as the input parameter in a variable to make it available for later usage. Click the Receive Data item, then in Select variables to assign:, select " Create new variable...." The following screen will be displayed.
Enter stocks as the variable name. The type will be inferred from the input parameter's type. Click OK.
We now have a process that receives an XML document as the input parameter named stocks and stores its content in a variable with the same name ( stocks). Now it's time to transform the XML document stored inside the stocks variable into a format compliant with our partner's XML Schema.
To perform that transformation, right-click the processes.useCase02 package and select New | Transformation as shown below.
Name the transformation StockTransformation and click Finish. The transformation will be created as a standard Java abstract class.
Right-click on the StockTransformation.java file and select Transform | Add XQuery Transformation Method as shown below.
This will expose an XQuery transformation as a standard Java method, which will be able to be called as part of the process flow.
Name the method transformStockToPartnerSchema and the XQuery File transformStockToPartnerSchema.xq as shown below. When finished, click Next.
Now it's time to select the Source Type. Expand FCTLAppWeb | schemas | stocks.xsd | stocks and click Add. The element will be moved to the Selected Source Types as shown below. Click Next.
As may be obvious, it's time now to select the Target Type. Expand FCTLAppWeb | schemas | STOCKS_PARTNER.xsd | STOCKS and click Add. The element will be moved to the Selected Target Types as shown below. Click Finish.
You should be taken to the XQuery Mapper as shown below.
Drag each item in the Source tab to its equivalent in the Target tab. TAhe result should resemble the image below. Don't forget to save your work after completing the mapping by clicking the Save button or hitting Ctrl+S.
The XQuery mapper is a utility tool that helps you to graphically create complex transformations. As shown, you will be able to create a transformation simply using drag-and-drop. The XQuery Mapper also supports more complex scenarios, such as joins and non-trivial transformations, while allowing you to maintain full control over the generated XQuery with source access through the Source tab. It's also very simple to test your query using the Test tab.
Now that your transformation is ready, drag the StockTransformation.java file to the Controls folder inside the Data Palette. This should look like the image below, and the method we added to the transformation should be available as a control's method.
Now drag the method transformStockToPartnerSchema to your process flow below the Client Request node. At this point your process should resemble the image below.
Double-click the transformStockToPartnerSchema to configure the information sent to and received from the transformation method. For the Send Data configuration in Select variables to assign, select the stocks variable.
Go to the Receive Data section, select Create new variable and enter partnerStocks as the new variable name. When finished, click Close to complete the transformation node configuration.
At this point we have the XML in the format our partner expects. We just need to write it to a file to finish the use case.
Now add a file control to your project. You have seen how to do it in the last section, so we will omit most of the details. Name the instance property xmlFileControl and click Next. Name the interface XmlFileControl and click Next. Configure the control as shown in the image below, paying attention to the Type of Data that should be XmlObject in order to force the control to work with XML. Click Finish when done.
Drag the write method from the xmlFileControl list of available methods. In Send Data, select the partnerStocks variable and in Receive Data, create a new variable named properties. Click Close when done.
Configuring the write method invocation, we selected the partnerStocks variable to be written to an XML file in /tmp/repository/partnerStocks.xml. The process is ready! Now it's time to test it!
To test the process, right-click it and select Run As | Run On Server. When the Test Console is displayed, select the Test SOAP Tab. We select the Test SOAP Tab because with this option the input XML payload will be automatically generated for you, as shown below:
Change the data in SOAP body section to make it look like the XML document below.
<clientRequest xmlns="http://www.openuri.org/" xmlns:stoc="http://www.oracle.com/WP/stock"> <stoc:stocks> <!--1 or more repetitions:--> <stoc:stock> <stoc:symbol>ORCL</stoc:symbol> <stoc:companyName>Oracle Corporation</stoc:companyName> <stoc:price>18.10</stoc:price> </stoc:stock> </stoc:stocks> </clientRequest>
Click the clientRequest button and you will see the test results. Click the refresh button until you see the process is finished, then go to the /tmp/repository directory and see if the file partnerStocks.xml was created. The contents of the file should look similar to the image below.
The sample is finished, and as you have seen, we received an XML document compliant to one schema (stocks.xsd), transformed it to another schema definition (STOCKS_PARTNER.xsd) simulating the requirement to send it to a partner and wrote it to a file using the XmlObject file writing capability of the file control. Doing that we were able to write XML content which was represented in the form of a Java object (actually, an instance of a class generated by XMLBeans compiler).
Receiving an XML, transforming to CSV and writing to a file using FTP in WLI
In this sample you will transform the XML file you wrote for use case 2 into a CSV file. After the transformation, you will see how to send it to an FTP server using the file control.
For the file format definition (CSV, in our case), we used the concept of MFL, which is "An XML language that describes the native representation and hierarchy of non-XML data. MFL is an XML description of non-XML data".
For the creation of the MFL file, we used the Format Builder tool, which is a GUI tool that helps in the creation of a representation of the non-XML data. You can find more info about the Format Builder here.
Create a new process called TransformXmlToRawDataAndWriteToFTP in package processes.useCase03.
Select the starting event as Invoked via Client Request.
Drag the XmlFileControl.java from the processes.useCase02 package and drop it into the Controls folder in the Data Palette.
At this point you will reuse the control you created in use case #2, but now you will use it to read the file you created. A best practice would be to place controls inside the utility project, so they could be shared and reused among different applications.
Drag the method read to your process, making it similar to the image below.
Double click the read node. Select the Receive Data item and select the option to create a new variable. Select the STOCKS element as you did in use case #2 and as is shown in the following image. Click OK and Close when done.
The step we just completed will create a cast from the result of the control's read operation (an instance of XMLObject) to the STOCKS class.
We created an MFL file to represent the CSV file format. Copy the MFL file from the sample files folder and copy it into the schemas project.
This will create the representation of the MFL in Java and its counterpart representation as an XMLObject class to represent it in XML. Now, it's time to create a transformation that will transform the partnerStocks variable, containing the contents read from the partnerStocks.xml file. We will create an ordinary transformation using the XQuery mapper and then instantiate the class representing the MFL file to make the data available in CSV format.
Create a new transformation named RawDataTransformation. Add a method to the transformation and name it transformPartnerStockToRawData and name the XQuery file as transformPartnerStockToRawData.xq.
For the Source Type, select the STOCKS as shown below.
For the Target Type, expand the stockquotes.mfl file, select the Stocks element and add it to the Selected Target Types as shown in the following image.
Map each field to its equivalent as shown below. Don't forget to save the transformation when finished.
Drag the RawDataTransformation.java file and drop it into the Controls folder in the Data Palette. Now, drag the method transformPartnerStockToRawData to the process, after the read node. As you may already know, you will be calling the transformation as part of your process flow.
Double click the transformPartnerStockToRawData node to configure it. For the Send Data section, select the partnerStocks variable. For the Receive Data, create a new variable named stocks. Click Close to finish the configuration. At this point, your process should resemble the following image.
At this time we have an object representing the MFL in the form of XML. With this object in hand, represented by the stocks variable, we will be able to instantiate another object which was created from the MFL file, called "MFL object". For this instantiation to happen, we just need to call the newInstance method and pass to it the stocks object as a parameter. We will do that next!
The first step in transforming the XML object into an MFL object is to create a variable that will represent the MFL object. To do that, click the arrow in the Data Palette and select " Add a Variable..." as shown below.
Name the variable stocksMflObject and select its type through the Non-XML tab, expanding FCTLAppWeb | schemas | stockquotes.mfl and selecting Stocks as shown below. Click OK when done.
Add a Perform node to your process and name it " Instantiate MFLObject".
Inside a Perform node, you can execute any kind of Java code. We will use it to instantiate the variable stocksMflObject that we just created.
Right click the recently added Perform node and click " View code". You will be redirected to the code editor inside a method called perform. Add the following line of code inside the method:
stocksMflObject = StocksMflObject.newInstance(stocks);
Now you have an object representation of your formatted file. It's time to write it out to an FTP server.
To setup a local FTP, download the ftpserver-1.0.0-M3.zip file and decompress it to the /tmp folder. From a command prompt in Windows or shell in Unix, go to the /tmp/ftpserver-1.0.0-M3/bin directory.
Run the following command in Windows:
Or the following in Unix (note that root privileges are required):
This will start an FTP server on your computer with a default user named admin with "admin" as the password. The image below shows the FTP server running.
Now add a new File Control to your application. Name it FtpFileControl and configure it as illustrated in the image below. Pay special attention to the Type of Data that indicates the File Control will be specific to working with raw data.
Click the ftpFileControl in the Data Palette. Its properties will be shown in the Properties view. Find the FileControl.Ftp property as shown below.
Configure the FileControl.Ftp properties as shown below. The only property that may not be obvious is localDirectory, which is the directory where the control will write the file before sending it through FTP, removing the file after that.
Pay special attention to the FileControl.FileInfo properties. Note that the directoryName property should be configured simply as /, not C:/.
Drag the write operation and drop it inside your process, as the last node.
Configure the write node to send the stocksMflObject variable and create a variable named properties to hold the result of the operation in the Receive Data section. Click Close and save the process.
You have just configured the File Control to send the data to FTP. Let's test it!
Right-click the process and select Run As | Run On Server.
If everything went fine during the process execution, there should be a CSV file inside /tmp/ftpserver-1.0.0-M3/res/home containing the stock quotes that were previously inside /tmp/repository/partnerStocks.xml.