Getting connected with WebSphere Integration Developer adapters : Part 2, An introduction to the WebSphere Adapter for Flat Files

Document options Document options requiring JavaScript are not displayed Sample code Rate this page Help us improve this content

Level: Intermediate

Mandy Habinski (Mandy_Habinski@ca.ibm.com), Software Tester, WebSphere Integration Developer Test, IBM
Tanya Ruppell (truppell@ca.ibm.com), Team Lead, WebSphere Integration Developer Test, IBM
Artur Ruszczynski (Artur_Ruszczynski@ca.ibm.com), Software Developer, WebSphere Integration Developer, IBM
Richard Gregory (gregoryr@ca.ibm.com), Staff Software Developer, IBM
Greg Adams (Greg_Adams@ca.ibm.com), Distinguished Engineer, IBM

09 May 2007

This is the second article in a series that explores how to use resource adapters with IBM® WebSphere® Integration Developer. The first article described resource adapters and how they fit in with service-oriented development. This article examines how you can read data from a flat file, use that data in a WebSphere Integration Developer application, and then send data back to the file system.

From IBM WebSphere Developer Technical Journal.

Introduction

In the first article in this series, Getting connected – An introduction to connecting with adapters you learned the basics about using each type of resource adapter with WebSphere Integration Developer, including the difference between inbound and outbound processing and how resource adapters fit into your WebSphere Integration Developer application. In this article, we will look at how an application can read from (inbound processing) and write to (outbound processing) a file system using the IBM WebSphere Adapter for Flat Files. We will also show how to create a module using WebSphere Integration Developer that uses the WebSphere Adapter for Flat Files to read and write data files.

What is a flat file?

The term flatfile refers to any file stored on a file system, as opposed to a more complex set of files, such as those in a structured database. The data records in a flat file are typically stored sequentially and without any metadata, such as the indices, keys, and relationships that you would find in database storage. You can use the adapter for flat files to read and write any type of file. However, you typically use the adapter for flat files to read and write text files that store records in a flat file format such as XML or Comma-Separated Values (CSV) records. Figure 1 shows example records in each format.

What is the WebSphere Adapter for Flat Files?

Enterprise Service Discovery wizard: A tool that you use to generate business objects, interfaces, and WebSphere Integration Developer components to access an external system from a WebSphere application.

You might have an EIS that outputs sets of files to a directory. An example might be an order processing system that produces files containing order information so that the orders can be processed in batch during off-peak hours. These files might store business information sequentially, not structured as business information would be in a relational database. The same or another information system might use sets of files in a directory as input to programs. You would use the WebSphere Adapter for Flat Files Version 6.0.2 to integrate this type of EIS into an application because it connects file systems and applications that run on an application server such as WebSphere Process Server or WebSphere Enterprise Service Bus.

Any WebSphere application can use the adapter for flat files to create and manage files or to monitor a directory and read files from this directory. Using the Enterprise Service Discovery wizard, you specify the directories that the WebSphere Adapter for Flat Files reads from and writes to, and the format of the data in those directories. The Enterprise Service Discovery wizard also creates any additional artifacts required, such as imports, exports, and the corresponding interfaces and business objects.

What are inbound and outbound processing?

Endpoint: A component that interacts with the adapter through an export artifact. An endpoint receives events from the event store in the form of business graphs.

Inbound processing is the mode of operation in which the WebSphere Adapter for Flat Files monitors the file system, reads new files, and sends the data to the endpoint component.

Outbound processing is the mode of operation in which the WebSphere Adapter for Flat Files receives requests (from a component of a WebSphere application) to perform an operation on the enterprise information system and, when applicable, returns the results to the caller. Example operations include creating a file, writing to a file, or checking if a specific file exists.

Back to top

Inbound processing

During inbound processing, the adapter for flat files listens for events that are produced by an external EIS. An event is a record of what changes have occurred in the event directory. The directory that the adapter for flat files monitors for new files (the one that the EIS outputs its files to) is called the event directory.

Figure 2 shows the four steps that occur during inbound processing:

1. The EIS outputs its files to the event directory.

2. The adapter for flat files polls for files from the event directory and converts the data from those files into events. The adapter can be configured to poll for only certain types of files, or for files created during a certain time period.

3. Events are temporarily placed in an event store database. This database enables data persistence so that events will not be lost before your application can process them if the server goes down after an event is created, for example. When all events are stored in the database, the original file is deleted from the event directory.

Event store: A table created by the adapter in a database where inbound events are stored for security or recovery purposes. (Not used in outbound mode.)

4. The adapter for flat files retrieves the events from the event store and passes each event in the form of a business object through an exported inbound interface, which the Enterprise Service Discovery wizard created.

Data Transformation Framework (DTF): A framework that enables the adapter for flat files to convert data during outbound processing from business objects into serialized data formats (such as XML and CSV), and from these formats back into business objects during inbound processing. Pass-through A mode of operation in which the data is not converted into user-defined business objects but is passed through the application as unstructured content instead. Non-pass-through: A mode of operation that uses the Data Transformation Framework.

If the application does not know the format of the data files, you can configure the adapter for flat files to run in pass-through mode, operating on unstructured data. In that case, it would not transform an event into a business object.

File splitting

When you have one record per file, you don't need file splitting. You use file-splitting when the files you want to retrieve are large or they each contain more than one record. You can split files into smaller chunks based on a delimiter or on a fixed-size value, which allows parts of the file to be processed in parallel. Each chunk is considered a separate event and is individually sent to the endpoint component through the exported inbound interface.

Record delimiters

Delimiter: One or more characters that indicate the end of record in a file.

Typically, input is stored as a single record per file. However, when the input file contains more than one record, you often separate the records in the file with a delimiter, which can be any text string and is usually a combination of characters followed by \n (platform dependent new line character). The adapter can both read and write files that contain a delimiter.

Using our examples from Figure 1, we have the string #### followed by a new line as the delimiter in the XML file (shown in Figure 3), and we have only a new line as the delimiter in the CSV file.

In this case, the adapter splits the input file into two chunks corresponding to two records. It sends the records to the event store one by one, and from there to the endpoint component as separate business objects.

Split by size

The split-by-size feature is similar to splitting by delimiter because you use it to divide a file into smaller chunks and transfer them to the endpoint component one by one. However, use this feature with unstructured data in a pass-though scenario because it is not going to be put into business objects. You specify the split criterion in the adapter as a number of bytes. The adapter reads the file as chunks (events) of that byte size. Each chunk will be the size defined by split criteria, except the last one, which might be smaller.

Custom data binding

Data in flat files can come in many different formats, such as the previously discussed XML and CSV formats. Others formats include name and value pairs, tab-separated, and fixed-width formats. Data binding is a method of mapping from the format in the data files to the attributes of a business object.

Using the adapter for flat files default data binding, you can convert files to and from XML format. In other formats, you have to use custom data bindings that define the mapping between the file format and a business object. To implement a custom binding, create a Java class that converts the data for the specific format and enter this class in the Enterprise Service Discovery wizard when you configure the adapter.

For more information about creating a custom data binding, visit Creating custom data bindings in the WebSphere Adapters documentation.

Back to top

Outbound processing

To write or modify files, the application uses the operations defined in the outbound interface, which you create using the Enterprise Service Discovery wizard. The following list shows the operations it creates to work with unstructured data (in pass-through mode):

• createFlatFile – stores data to a new file or creates an empty file
• appendFlatFile – appends data to an existing file
• overwriteFlatFile – overwrites an existing file with a new data
• deleteFlatFile – deletes an existing file
• retrieveFlatFile – reads content from a file (binary only)
• listFlatFile – lists files in a directory
• existsFlatFile – checks if a specific file exists

However, if you setup the adapter to work with structured data (in non-pass-through mode or DTF) the Enterprise Service Discovery wizard creates all of the operations and an additional set of seven outbound interface operations that support your specific business objects.

Back to top

Using the adapter for flat files in an application

Imagine that you want to create an application that monitors a certain directory in a file system so that you can collect customer record information. When a file is created, the adapter calls the export with the data that is stored in a business object. The export is wired to a business process component that separates the data from the file into individual records that are each placed into their own file in an output directory. This scenario is shown in Figure 4:

When files that contain customer records are in the inbound events directory, the resource adapter retrieves them, creates a customer business object, and calls an export in the module, which initiates a business process. The process generates a new file name based on the number of existing files, and specifies the output directory. Then, the business process writes the customer business object data to a separate XML file in the output directory of the file system.

Back to top

Building the application

Linux users: These instructions assume you are running WebSphere Integration Developer on a Windows operating system. If you are running WebSphere Integration Developer on Linux, you need to replace the file paths listed with an appropriate file path on your system.

To create an application that uses the adapter follow these basic steps, which are detailed in the following sections:

1. Set up the event store database.
2. Import the resource adapter.
3. Use the Enterprise Service Discovery wizard to create the inbound flat file service.
4. Use the Enterprise Service Discovery wizard to create the outbound flat file service.
5. Implement the business logic.

Back to top

Creating the event store

To use the inbound adapter, you first need to set up the event store, which is where inbound data is temporarily stored. You can use any type of database as the event store, but in this example you will use the Cloudscape database that ships with WebSphere Integration Developer. When a component such as a resource adapter on WebSphere Process Server needs database access, it uses a server data source.

To set up the event store:

1. Create a database.
2. Create a data source on the server that uses that database.

To use the inbound adapter, you have to create the Cloudscape database using the Cview application:

1. Run the following command: <WIDInstalldir>\runtimes\bi_v6\cloudscape\bin\embedded\cview.bat .
2. When the Cview window opens, select File - New - Database, and then enter FlatFilesDB in the Name field.
3. Click OK, and then close the Cview application.

Now you need to create a link from WebSphere Process Server to the new database:

1. If you haven't started WebSphere Integration Developer yet, do so now and switch to the Business Integration perspective.
2. To start the server, go to the Servers view, right-click WebSphere Process Server v6.0, and then select Start.
3. When the server has started, right-click the server again and select Run administrative console.
4. Log into the administrative console using any user ID.
5. In the administrative console, expand Resources on the left pane, and then click the JDBC Providers link.
6. Click the Cloudscape JDBC Provider(XA) link and then, on the next page, click the Data sources link.
7. Click New to create a new data source.

To link a server data source with the database that you created in the first part of this section:

1. On the next page (shown in Figure 5), enter jdbc/FlatFilesDB in the JNDI name field and then, at the bottom of the page, enter FlatFilesDB in the Database name field.

   
   
   Figure 5: The Cloudscape data source
   
   
   

2. Click OK, click the save link, and then click Save.
3. Check the new data source (JNDI name jdbc/FlatFilesDB) and click Test Connection. You should see a "Test connection successful" message.
4. Log out and close the administrative console.

Back to top

Creating the inbound service

In this section, you create a module with an export that is called by the inbound adapter (detailed in the following sections):

1. Import the resource adapter and create an adapter project.
2. Create a module that will contain, at a minimum, the export and the component it will be wired to.
3. Use the wizard to discover services and create the export.

As a shortcut, you could use the Enterprise Service Discovery wizard because it lets you create the resource adapter project and the module, but for clarity we will show these three steps individually.

Import the resource adapter

To import the resource adapter into a project:

1. In the Business Integration view, right-click and select Import.
2. In the Import dialog box that opens, select RAR file, and then click Next.
3. Next to Connector file, click Browse and then browse to <WIDInstallDIR>/Resource Adapters/FlatFile/deploy.
4. Select the file CWYFF_FlatFile.rar, click Open, and then click Finish. If a dialog box opens asking you whether you want to switch to J2EE perspective, click No, because you are going to continue working in the Business Integration view.

There is now a resource adapter project in your workspace. Note that it is not in the Business Integration view; so don't be worried if can't find it. It will appear in the Enterprise Service Discovery wizard in the next steps.

Discover the flat file service

Next, you will create a new module and then use the Enterprise Service Discovery wizard to create a flat file export in the module.

1. In the Business Integration view, right-click and select New - Module to create a module, and name it SeparateCustomersModule.
2. To open the Enterprise Service Discovery wizard, click File - New - Enterprise Service Discovery.
3. Ensure that IBM WebSphere Adapter for Flat files (version 6.0.2) from the CWYFF_FlatFile Connector Project is selected (that is the project that you created in the previous steps), and then click Next. Notice that there is an Import Resource Adapter button. If you click this button, the Import dialog box that you saw in the previous steps opens.

You now need to tell the adapter which business objects you will use to store the inbound data so that the adapter can create the appropriate inbound interface operations. Recall that the adapter creates an interface that has a generic operation for reading unstructured data and an operation specific to the business object for reading structured data. In this example, the data is structured.

Because flat files do not contain metadata that describes the business data structure (unlike other EISs, such as enterprise resource planning or transaction processing systems, which often contain metadata describing their business data), the Enterprise Service Discovery wizard needs a hint to recognize the structure in the files. Therefore, the business objects must exist before the wizard runs. In this case, you use the customer business object that ships with WebSphere Integration Developer as a sample.

Tip: There are a lot of options for the character set. To quickly get to UTF-8 in the list, press U eight times.

1. Next to Folder Name, click Browse and then browse to <WIDInstallDIR>\Resource Adapters\FlatFile\samples.
2. In the Character Set list, select UTF-8, and in the Content Type list, select text/xml. The wizard should look like Figure 6.

   
   
   Figure 6: Connection configuration
   
   
   

   The following table explains what you just set in step 2:

   
   
   

   Property	Description
   Folder name	Folder name indicates where the business objects to be imported by the wizard are located.
   Content type	When you select text/xml, you indicate which data format the adapter expects when it reads or writes, and the associated DataBinding type, XMLBOSerializerDataBinding, populates the DataBinding type field.

   
   
   
3. Click Next.
4. On the Find and Discover Enterprise Services page, click Execute Query. You should see the Customer business object under Objects discovered by query.
5. Select Customer, and then click Add to import list.

Figure 7 shows the discovered Customer business object. With some EISs, the resource adapter queries the metadata on the backend to discover business objects. In this case the metadata was provided in the form of an XML schema definition file that described the data in the flat files.

Next, indicate which adapter type (inbound or outbound) you are creating and specify the parameters for this type of adapter and the particular file format of the input files.

1. Click Next.
2. On the Configure Objects page, select Inbound as the service type. Figure 8 shows setting the service type to inbound. The operations for the service are grayed out because they do not apply to an inbound operation. Click Next.

   
   
   Figure 8: Configure Objects page
   
   
   

3. On the Generate Artifacts page, ensure SeparateCustomersModule is selected as the module, and then set the values shown in the following table (you can leave the rest of the default values):

   
   
   

   Field	Value
   Event Directory	c:\flatfiles\inboundevents
   Archive Directory	c:\flatfiles\inboundarchive
   DataSource JNDI Name	jdbc/FlatFilesDB
   Event Table Name	FlatFilesDB
   Split Criteria	####;\n
   Splitting Function Class Name	com.ibm.j2ca.utils.filesplit.SplitByDelimiter
   Event Content Type	text/xml

   
   
   

4. Click Finish.

Figure 9 shows the wizard after filling in the values from the table.

The following table gives you information about the values that you can set for the adapter for flat files. For information on other configuration settings, refer to the adapter documentation.

Let's look a bit closer at the split criteria. By selecting ####;\n as the split criteria (the semicolon is needed to separate more than one delimiter), we assume that the records in our input XML file are separated by #### and a new line character like in the following example:

    … 
    <State>ON</State> 
</Customer>
#### 
<?xml version="1.0" encoding="UTF-8"?>
<Customer>
    <customerName>Matt</customerName>
    …

When you enter a delimiter for the split criteria, you also have to enter a value in the Splitting Function Class Name field so that the split criteria points to the following predefined class (for delimiters): com.ibm.j2ca.utils.filesplit.SplitByDelimiter.

By specifying a delimiter (or another file-splitting function such as chunk-size), you change the meaning of the poll quantity: from the maximum number of files polled from the events directory each time, to the maximum number of business objects retrieved during each poll. For example, imagine that you set the poll quantity to 10 and there are two files in the events directory. The first file contains nine records and the second file has only two records. When the poll cycle starts, all nine business objects are retrieved from the first file and only the first business object is retrieved from the second file. The remaining object from the second file is retrieved on the next poll cycle.

Figure 10 shows the assembly diagram after the wizard steps are complete. The Appendix to this article contains instructions on splitting by size.

Business graph: A wrapper around a business object or a hierarchy of business objects to provide additional data to an enterprise information system.

You are finished creating an inbound service that uses the WebSphere Adapter for Flat Files. Let's look at the artifacts that now exist in your workspace.

Business objects that were created

The WebSphere Adapter for Flat Files defines and generates business objects based on data gathered using the Enterprise Service Discovery wizard. For both inbound and outbound processing, it generates the following artifacts:

• FlatFile
• FlatFileBG
• UnstructuredContent

FlatFile is a wrapper business object that contains the UnstructuredContent business object and file-specific data. FlatFileBG is a business graph that wraps the FlatFile business object, as Figure 11 shows. As we discussed in the first article of this series a business graph is a container for a business object that has a verb or instructions on what to do with the data. However, the adapter for flat files does not use the verb field of the business graph. The Enterprise Service Discovery wizard always creates business graphs, which are sometimes used as operation parameters for import and export interfaces.

In the previous steps, you configured the adapter to use structured data (DTF). So the Enterprise Sservice Discovery wizard generated two additional business objects, as shown in Figure 12. Because the folder name in the connection configuration contained the Customer business object (see Figure 7), the business object was imported into the module and the wizard created CustomerWrapper and CustomerWrapperBG as Figure 12 shows.

Customer BO stores data about a customer, which is the actual data record that comes from the input file. The business object has a attribute of type Customer and multiple other attributes used to store data that is specific to the adapter and the operation.

Back to top

Creating the outbound service

Next, let's create the outbound service:

1. Select File - New - Enterprise Service Discovery.
2. Ensure that IBM WebSphere Adapter for Flat files (version 6.0.2) from the CWYFF_FlatFile Connector Project is selected (that's the project that you created before you created the inbound service), and then click Next.
3. Next to Folder Name, click Browse and browse to <WIDInstallDIR>\Resource Adapters\FlatFile\samples.
4. In the Character Set list, select UTF-8, and in the Content Type list, select text/xml, and then click Next.
5. On the Find and Discover Enterprise Services page, click Execute Query, select Customer in the list, click Add to import list, and then click Next.
6. On the Configure Objects page, select Outbound as the Service Type, and then click Next.
7. On the Generate Artifacts page, ensure SeparateCustomersModule is the selected module, and then for the Output Directory enter c:\flatfiles\outputdir, and for the Staging Directory enter c:\flatfiles\stagingdir.
8. Click Finish.

You have finsihed creating an outbound service that uses the WebSphere Adapter for Flat Files. Figure 13 shows the outbound settings.

The following table explains the values that you set for the outbound connection properties.

Let's take a look at the new artifacts that exist in your workspace:

Business objects that were created

The interface operations that the Enterprise Service Discovery wizard generates for an outbound adapter require the following business object and business graph pairs to be generated as well:

• ExistsResponse/ExistsResponseBG holds the result of the existsFlatFile operation. If a specific file exists in a given directory, existsFlatFile returns true.
• ListResponse/ListResponseBG holds the result of the listFlatFile operation. Results are stored as an array of strings. Each string is the name of a file in the directory.
• RetrieveResponseWrapper/RetrieveResponseWrapperBG holds the result of the retrieveFlatFile operation. RetrieveResponseWrapper can contain an array of FileContent business objects. In general, retrieveFlatFile operation returns the content of a given file stored as an array of bytes in the FileContent business object.

For more information about business objects and business graphs, see the Business objects that were created in the Inbound section.

Back to top

Implementing the business logic

When you open the assembly diagram, you see both the export (called FlatFileInboundInterface) and import (called FlatFileOutboundInterface). Now you need to implement a component to process the data that was received from the export and sent to the import. In this section, you learn how to work with the data received from the flat-file export and how to work with data in flat files using the flat-file import.

The basic steps to add business logic that make use of both the inbound and outbound adapter for flat files are:

1. Create a business process component that is wired between the export and import.
2. Implement the logic in the business process.
3. Deploy and run the application.

Create the business process component

The following steps create a business process component and link it to both the inbound and outbound interfaces, which are the export and import, respectively:

1. Under SeparateCustomersModule, double-click AssemblyDiagram to open the assembly editor.
2. Right-click anywhere on the assembly diagram, select Add - Process, and then rename the new component to SeparateCustomers.
3. Move your mouse over the edge of the FlatFileInboundInterface component, and then drag the handle to the SeparateCustomers component, which adds a link from the export to the business process component.
4. When you are asked to add the interface of the export to the process component, click OK. FlatFileInboundInterface is added to the SeparateCustomers component.
5. In the same way, add a link from the SeparateCustomers component to the FlatFileOutboundInterface import, and click OK to add the matching reference. A reference with the FlatFileOutboundInterface is added to the SeparateCustomers component.
6. Save the assembly editor.

The assembly diagram on your screen should now look like the assembly diagram in Figure 14. If you want to learn more about creating business processes, read Business processes in a service-oriented world. Notice that there is an exclamation icon on the SeparateCustomers component to indicate that the component is not implemented. In the next section, you will fix that.

Implement the business process

Now, you need to create the business process implementation:

1. Double-click the SeparateCustomers component and, when asked to create the implementation, click Yes.
2. When the Generate Implementation dialog box opens, click OK so that the SeparateCustomersModule module contains the process implementation.
3. When the Process Operation dialog box opens, ensure the emitCustomerWrapper operation is selected, and then click OK.

When the business process editor opens, in the top right corner of the editor you see an emitCustomerWrapperInput variable with data type CustomerWrapperBG. The emitCustomerWrapperInput variable contains data from flat-file events. You need to add two more variables that will be used in the process:

1. Right-click Variables and select Add Variable.
2. With the new variable selected, open the Description tab in the Properties view and rename it EmitFlatFileInput.
3. On the Details tab, ensure Data Type is selected, click Browse, and then select FlatFileBG for the variable type.
4. In the same way, create a variable named ListResponseBG with the type ListResponseBG.

There are two operations in FlatFileInboundInterface; so the process must contain two corresponding receive activities. In fact, you might have noticed an error indicating that the process does not implement the emitFlatFile operation. In the next steps, you will fix that:

1. Delete the Receive activity and add a ReceiveChoice activity in its place by right-clicking the canvas and selecting Add - ReceiveChoice.
2. To avoid a correlation issue that results from having multiple operations defined in the interface, in the Details tab of the properties for this ReceiveChoice activity, select Create a new Process instance if one does not already exist.
3. Click the Receive element of the ReceiveChoice activity.
4. In the Properties view, on the Details tab, click Browse, select FlatFileInboundInterface from the list, select emitCustomerWrapper as the Operation, and then click the Input type selection button and choose EmitCustomerWrapperInput. The properties for the emitCustomerWrapper receive activity should now be set as in Figure 15.

   
   
   Figure 15: The emitCustomerWrapper receive activity properties
   
   
   

5. Right-click the ReceiveChoice activity and select Add Receive to add another receive element.
6. In the Properties view, rename the new receive element to emitFlatFile, set the partner to FlatFileInboundInterface, set the operation to emitFlatFile, and then set the input variable type to EmitFlatFileInput. The properties for the emitFlatFile receive activity should be set as in Figure 16.

   
   
   Figure 16: The emitFlatFile receive activity properties
   
   
   

7. In this example, you do not use the emitFlatFile operation (for unstructured data); so add an Empty Action under the emitFlatFile receive activity.

The variable EmitCustomerWrapperInput contains the data received from the emitCustomerWrapper operation. Because you will write the content of variable EmitCustomerWrapperInput to the output file, you need a snippet to reset the directory path (set as the inbound event directory during the inbound processing) to the output directory. When the directory path is an empty string, the outbound adapter for flat files uses the default output directory configured by the Enterprise Service Discovery wizard, which you set to c:\flatfiles\outputdir when you created the outbound service.

In the next steps, you will add a snippet, as shown in Figure 17, that sets the directoryPath field of EmitCustomerWrapperInput variable to an empty string

1. Under emitCustomerWrapper, add a snippet activity and rename it to ResetDirectoryPath.
2. In Properties view, on the Details tab, assign an empty string to variable EmitCustomerWrapperInput.CustomerWrapper.directoryPath by selecting Add - Expression and typing two double quotation marks in the expression node. Alternatively, you can drag EmitCustomerWrapperInput onto the canvas and use the menu to select the nested business objects and attributes.

Now you need an activity to check how many files are in the output directory so that you can add the appropriate sequence number in the output file name:

1. Under the ResetDirectoryPath snippet, add an Invoke activity and rename it to InvokeListResponse.
2. Set the details to those shown in Figure 18.

   
   
   Figure 18: The InvokeListResponse invoke activity properties
   
   
   

The content of ListResponseBG business graph in the InvokeListResponse properties is the list of files in the c:\flatfiles\outputdir directory. You will use this directory because the directoryPath field of the variable EmitCustomerWrapperInput is empty.

In the next steps, you create another snippet activity to create the file name for the output file. The file name will have the format <customerName><Sequence>.xml. (If you are familiar with creating snippets, you might find it easier to create the snippet using the information in Figure 19.)

1. Under InvokeListResponse, add a snippet activity and rename it to ResetFileName.
2. Add a node for the ListResponseBG.ListResponse.listOfFileNames variable.
3. Add a list size node by selecting Add - Standard - list size. The list size node indicates the number of file names stored in ListResponseBG.ListResponse.listOfFileNames.
4. Wire the ListResponseBG.ListResponse.listOfFileNames variable node to the list size node.
5. Add a to text node by selecting Add - Standard - Utility - to text. The to text node creates a string from the size integer that will be the sequence number in the file name.
6. Wire the list size node to the totext node.
7. Add a node for the EmitCustomerWrapperInput.CustomerWrapper.content.customerName variable.
8. Add an append text node by selecting Add - Standard - Text - append text, wire the node on the EmitCustomerWrapperInput.CustomerWrapper.content.customerName variable to the top input of the append text node, and then wire the to text node to the bottom input of the append text node.
9. Create a second append text node to add the string .xml to the output of the first append text node, and assign the output of the second append textnode, which is the entire file name string, to the EmitCustomerWrapperInput.CustomerWrapper.fileName variable.

The resulting snippet should look like Figure 19:

The outbound operation createCustomer creates a new file with the file name that you set in thefileName field of the EmitCustomerWrapperInput variable, and writes the file in the output directory that you set earlier using the empty string.The outbound operation is created in the output directory that you set earlier using the empty string, and writes the content of a Customer business object to a file using the adapter for flat files. In the few remaining steps, you create an activity to call that operation:

1. In the process editor, add an Invoke activity under ResetFileName and rename it to InvokeCreateCustomer.
2. Set the details to the information shown in Figure 20:

   
   
   Figure 20: The InvokeCreateCustomer invoke activity
   
   
   

3. Save the business process editor.

The final implementation of the component SeparateCustomers on your screen should look like Figure 21:

Figure 21: The SeparateCustomers business process

You have finished implementing the application. Before deploying it to the server and testing it, you just need to create the directories that you specified in the Enterprise Service Discovery wizard:

1. Create a c:\flatfiles folder, and create four subfolders in it:
1. c:\flatfiles\inboundevents
2. c:\flatfiles\inboundarchive
3. c:\flatfiles\outputdir
4. c:\flatfiles\stagingdir
2. Copy the input files from the input.zip file provided in the Downloads section into the c:\flatfiles\inboundevents folder.

Back to top

Testing the application

You are now ready to deploy and test the application!

1. Go to the Servers view, right-click WebSphere Process Server, and select Start.
2. Right-click WebSphere Process Server again and select Add and remove projects.
3. Select SeparateCustomersModuleApp, and then click Add.
4. Click Finish and wait for the server to start and for the module to deploy.

The inbound polling automatically starts after the application deploys. You should see the message "Polling has started." in the console view. Check the contents of the c:\flatfiles\inboundevents directory; the input files in this folder have been deleted.

For every event that the inbound portion of the adapter for flat files polled and processed, you see a "The event has been delivered" message in the Console view.

Check the c:\flatfiles\outputdir directory. You see a list of XML files with a filename matching <customerName><Sequence>.xml. The content of each file is a single customer data record.

Back to top

Conclusion

The IBM WebSphere Adapter for Flat Files enables your business components to interact with plain text files that were created or consumed by enterprise information. You have learned how to set up the resource adapter for flat files and use it in an application.

Back to top

Appendix

Split by size

If you want to split a file by size, do one of the following actions:

• Enter an integer value for the split criteria representing the maximum size of the event (in bytes)
• Set the Splitting Function Class Name to com.ibm.j2ca.utils.filesplit.SplitBySize

For more details, see the information about adapters in the resources section.

Sample input file

<?xml version="1.0" encoding="UTF-8"?>
<customer:Customer xmlns:customer=
       "http://www.ibm.com/xmlns/prod/websphere/j2ca/flatfile/customer">
  <customerName>John</customerName>
  <Address>83 Queens Street</Address>
  <City>Ottawa</City>
  <State>ON</State>
</customer:Customer>
####
<?xml version="1.0" encoding="UTF-8"?>
<customer:Customer xmlns:customer=
       "http://www.ibm.com/xmlns/prod/websphere/j2ca/flatfile/customer">
  <customerName>Matt</customerName>
  <Address>1435 Carling Ave.</Address>
  <City>Ottawa</City>
  <State>ON</State>
</customer:Customer>
####

Note that a RETURN has to be included at the end of the input file, to ensure the delimiter ####;\n is included correctly for the last Customer record.

Back to top

Downloads

Description	Name	Size	Download method
Sample input files	inputfiles.zip	1 KB	FTP|HTTP
Completed SeparateCustomers module	completedmodule.zip	1340 KB	FTP|HTTP

	Information about download methods

Resources

• Overview of all WebSphere adapters
  
  
• Introduction to creating business processes with WebSphere Integration Developer
  
  
• Enterprise Metadata Discovery
  
  
• WebSphere Adapter Development Redbook
  
  
• J2EE Connector Architecture 1.5 specification
  
  
• Adapter documentation
  
  
• A guided tour of WebSphere Integration Developer
  
  
• WebSphere Integration Developer product information
  
  
• developerWorks: WebSphere Process Server and WebSphere Integration Developer resources
  
  
• developerWorks: WebSphere Business Integration zone
  
  
• developerWorks: WebSphere development tools zone
  
  
• Meet the experts: WebSphere Integration Developer
  
  

• Download the WebSphere Business Modeler trial
  
  
• Download the Rational Application Developer trial

• WebSphere Integration Developer forum
  
  
• developerWorks blogs
  
  

About the authors

		Mandy Habinski is a software tester at the IBM Ottawa Lab on the WebSphere Integration Developer team. Her responsibilities include creating small scale applications for component and cross-component test, revising and executing Functional Verification Tests.

		Tanya Ruppell is a Team Lead at IBM Canada Ltd for the WebSphere Integration Developer Test Team. She and her team are responsible for automated GUI testing and cross-component testing of WebSphere Integration Developer and Message Broker Toolkit.

		Artur Ruszczynski is a software developer at the IBM Ottawa Lab on the WebSphere Integration Developer Testing team. His responsibilities include developing and executing automated cross-component tests.

		Richard Gregory is a software developer at the IBM Toronto Lab on the WebSphere Integration Developer team. His responsibilities include working on the evolution and delivery of test tools for WebSphere Integration Developer.

		Greg Adams was the lead architect for the user interface in the award-winning Eclipse platform, and more recently, has been the lead architect and development lead in the core WebSphere Business Integration Tools, including WebSphere Studio Application Developer Integration Edition and WebSphere Integration Developer. Greg led the delivery of IBM's first complete services oriented architecture (SOA) tools stack and the first BPEL4WS standards supporting Business Process Editor; both critical deliverables in support of IBM's On Demand strategy.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top