Using the File JCA adapter to read a file

Using the File JCA adapter to read a file

within the message flow

If there is a need to read the contents of a file inside a message flow of an already active proxy

service, then neither the File Transport nor the FTP transport can be of any help. Reading a

file with the File or FTP Transport is always only available inbound, implemented as a polling

operation and starting a new message flow/proxy service upon detecting a new file.

This recipe will show how we can use the File JCA adapter to read a file at runtime, for

example, to enrich data at runtime or to retrieve some configuration information. The JCA

adapters are available since OSB 11g and are the same ones we know from the SOA Suite.

We will create a business service wrapping the artifacts created by the JCA adapter wizard in

JDeveloper. By that the business service is just as any other business service seen so far and

can be invoked from a proxy service using a Routing or Service Callout action as shown in

this recipe.

The scenario shown can be helpful if you need to retrieve some configuration data or you'll

have to enrich the message, and the data is already available as a file.

Getting ready

Import the base OSB project containing the folder structure and the nested JDeveloper

project as shown in recipe Setting up OSB project to work with JCA adapters into Eclipse

from \chapter-6\getting-ready\reading-a-file-within-a-message-flow.

How to do it...

First, we will use JDeveloper to create the File adapter, using the nested SOA project inside the

adapter folder of the Eclipse OEPE project. In JDeveloper, perform the following steps:

1. Open the AdapterSOAProject.jpr file inside the adapter folder of the OSB

project, by selecting File | Open.

2. In the SOA project, double-click on the composite.xml file to open the

SCA composite.

3. To be able to create the File adapter, we need a XML Schema defining the data we

will read. Copy the prepared XML Schema file from \chapter-6\getting-ready\

reading-a-file-within-a-message-flow\Properties.xsd and paste it

into the xsd folder inside the SOA project:

4. On the SOA Composite view, drag a new File Adapter from the Component Palette

and drop it on the External References swim lane on the right-hand side.

5. Click Next.

6. Enter FileReadingService into the Service Name field and click Next.

7. Select the Define from operation and schema (specified later) option and

click Next.

8. Select Synchronous Read File for the Operation Type option.

9. Leave SynchRead in the Operation Name field and click Next.

10. Select Physical Path for the Directory names are specified as option.

11. Enter C:\work\files\in into the Directory for Incoming Files field.

12. The option Delete files after successful retrieval is enabled but grayed out and

cannot by changed (reason for that not known). This is probably not we want here,

because we want the file to stay. We will later see the possibility to change the flag

when creating/configuring the business service.

13. Click Next.

14. Enter Properties.xml into the File Name field and click Next.

15. Deselect the Native format translation is not required option.

16. Enter xsd/Properties.xsd into the URL field.

17. Select properties in the Schema Element drop-down listbox.

18. Click Next and then click Finish.

19. Save the SOA project in JDeveloper.

This is all we have to do in JDeveloper to get the necessary artifacts describing the File

adapter service. We can now go back to Eclipse OEPE and generate a business service

based on the JCA metadata.

In Eclipse OEPE, perform the following steps:

20. Refresh the adapter folder inside the OSB project.

21. Right-click on the FileReadingService_file.jca file and select Oracle Service

Bus | Generate Service to generate a business service based on the JCA

adapter definition.

22. Select the business folder in the Select the location for the WSDL and Service

tree.

23. Enter FileReadingService into the Service name and WSDL name field and

click OK.

The business service is generated. We could already use it like that. But we have to configure

the adapter to not remove the file after reading it. In Eclipse OEPE, perform the following steps

to configure the business service:

24. Open the generated FileReadingService business service and navigate to the

JCA Transport tab.

25. Expand the Advanced Settings at the bottom of the window.

26. Disable Always use configuration from JCA file and set the Delete File field value

to false.

Next we will create the proxy service, which will invoke the business service generated

previously, through a Service Callout action.

27. Inside the proxy folder, create a new proxy service and name it FileReader.

28. Select Any XML Service for the Service Type option.

29. Navigate to the Transport tab.

30. Select http for the protocol drop-down listbox.

31. Navigate to the Message Flow tab.

32. Insert a Pipeline Pair action and name it ReadFilePipelinePair.

33. Insert a Stage node into the Request Pipeline, and name it FileReadStage.

34. In the FileReadStage stage, insert a Service Callout action.

35. Navigate to the Properties tab of the Service Callout action, click Browse and select

the FileReadingService business service.

36. Select the SynchRead operation for the Invoking drop-down listbox.

37. Select the Configure Payload Document option.

38. Enter fileRequest into the Request Variable field and fileResponse into the

Response Variable field:

39. Deploy the project to the OSB server.

40. Copy the file \chapter-6\getting-ready\reading-a-file-within-amessage-

flow\misc\Properties.xml into the c:\temp\in\files folder.

Now we're ready to test the service. On the Service Bus console perform the following steps:

41. In the Project Explorer navigate to the FileReader proxy service inside the

proxy folder.

42. Click on the Launch Test Console icon and click Execute.

43. Check the Invocation trace to see that the content of the file is available in the

fileResponse variable.

How it works...

In this recipe, we have used the File JCA adapter for reading files from the local filesystem

(local to the OSB server) from within a message flow of a proxy service. With the File

Transport, reading a file can only be used in a polling scenario, where a proxy service together

with the File Transport constantly polls for new files to arrive and a new message flow is

started for each file. So the file itself is the trigger when using the File Transport. When using

the File JCA adapter, the operation on the file (write or read) is exposed as a service and being

wrapped by an OSB business service it can be invoked as any other service. The JCA adapter

actually creates a WSDL, which acts as the contract for the service, although behind the

scenes, JCA is used as the protocol and not SOAP or HTTP.

We have used the Service Callout action to invoke the File adapter service, but we could have

used a Routing action as well. Reading a file is typically only one of the (preparing) steps in a

proxy flow and a Service Callout action needs to be used, as no further (request) actions can

follow a Routing action in a message flow.

There's more...

In this section, we show how to set file/folder names dynamically at runtime and how to read

a file through an XQuery script, as an alternative to the File JCA adapter.

Setting the filename and folder name dynamically at runtime

When going through the File adapter in JDeveloper, we have specified the file and directory

name to be used for reading the file. These settings are used at runtime, if not overwritten by

the invoker. To overwrite them, we can use the Transport Header action inside the Service

Callout and specify some JCA-specific transport header properties.

In Eclipse OEPE, open the FileReader proxy service and perform the following steps:

1. In the Request Pipeline of the Service Callout action, insert a Transport

Header activity.

2. On the Properties tab of the Transport Header action, click Add Header twice.

3. Set the Defined drop-down list to jca and select the jca.file.FileName property

with the following Set Header to expression: data($body/configuration/

location[1]/filename).

4. Set the Defined drop-down list for the second header again to jca and select the jca.

file.Directory property with the following Set Header to expression: data($body/

configuration/location[1]/directory).

5. Deploy the project to the OSB server.

6. Copy the file \chapter-6\getting-ready\reading-a-file-within-amessage-

flow\misc\OtherProperties.xml into the c:\temp\in\files

folder.

Now, let's test the change. In Service Bus console, perform the following steps:

7. In the Project Explorer navigate to the FileReader proxy service inside the

proxy folder.

8. Click on the Launch Test Console icon.

9. Set the Payload field to the following value:

<configuration>

<location>

<directory>c:\work\files\in</directory>

<filename>OtherProperties.xml</filename>

</location>

</configuration>

10. Check the Invocation trace to see that the content of the file is available in the

fileResponse variable.