Configuring Java CAPS JBI Components for GlassFish Clustering

Configuring the File Binding Component for Clustering

When the File BC is implemented in a cluster, files are distributed evenly across instances in inbound mode and each file is delivered to only one instance if a file locking mechanism is in place. In on-demand read mode, each file is available to read either from all the instances (configuration mode) or from only one instance (payload mode). In outbound mode, all instances write to either one file (append mode) or to independent files, depending on how the BC is configured.

You do need to configure the File WSDL file to ensure that outbound files are not overwritten by simultaneous threads and that inbound files are picked up only once by only one inbound thread. Name the output files using a pattern that includes either a UUID or sequence number in the filename to prevent the files from being overwritten. For inbound files, you need to configure the locking mechanism of the File BC to prevent the files from being picked up by more than one instance. For on-demand read files, there is a new property named deleteFileOnRead that allows you to specify that a file be removed from the directory when it is read. You should also configure the BC to archive files if you have them removed. These steps are described under Configuring the File BC WSDL File for Clustering.

Adding the File Binding Component to the Cluster

The File BC is dependent on the following shared library:

Sun Encoder Library

To Add the File Binding Component to the Cluster

Add the following shared library to the cluster as described in To Add a Shared Library to a Cluster:
- sun-encoder-library

Add the File BC to the cluster as described in To Add a Java CAPS JBI Component to a Cluster.

The name of the File BC node is sun-file-binding.

Before you click OK on the Manage Targets page, enter the number of threads for the outbound processor.

Note –
If you need to modify the number of outbound threads once the File BC is deployed to a cluster, you need to make the changes using the GlassFish Admin Console and you need to update the property for each instance in the cluster.

Configuring the File BC WSDL File for Clustering

The File BC has no runtime configuration requirements for clustering, but there are a few requirements and options for configuring the properties in any File BC WSDL documents deployed to the cluster. These options assist with concurrency issues, load balancing, and failover.

In a clustered environment, you need to ensure that inbound files are picked up only once by one instance and that outbound files are not overwritten by simultaneous threads. For outbound files, you can specify a pattern for the output message name using either %u or %seq_name to keep all file names unique (note that %d is not sufficient here). To ensure that inbound messages are not processed by more than one instance, use the File BC's file locking mechanism. This mechanism uses a thread lock (T_LOCK) and a file lock (F_LOCK) to protect the messages from concurrent polling. The File BC processes messages as follows using the locking mechanism:

Acquire the file lock.
If the file lock is acquired, continue processing; otherwise release the thread lock.
List the files under the directory specified by file:message/@fileDirectory that match the file name or pattern.
Move each of the files to a working directory with the specified pattern appended to the file name.
Place the file names in the working directory into a queue.
Release the file lock.

For more information about the properties discussed below, see the following topics in Using the File Binding Component:

To Configure the File BC WSDL File for Clustering

For outbound messages, do the following:
1. In the File BC WSDL document, scroll to the input message definition under Bindings (named file:message, by default).
2. Select file:message.
  
  The Properties panel displays the properties for the message.
3. In the FileName property, enter a name for the output file using either %u to assign a unique UUID number to each output file or %{seq_name} for persisted sequence number creation. For example, output%u.txt.
  
  Note –
  Do not use %d in the file name. It does not ensure a unique file name and files might be overwritten.
4. In the fileNameIsPattern property, enter true.
5. Save and close the WSDL file.

For on-demand, read-only messages, you can configure any of the following options:
1. In the File BC WSDL document, scroll to the input message under Bindings (named file:message, by default).
2. Select file:message.
  
  The Properties panel displays the properties for the message.
3. Do one of the following:
  - To allow multiple instances and processes to access the input file, set the value of the deleteFileOnRead property to false.
  - To ensure only one thread and one process accesses the file, set the value of the deleteFileOnRead property to true.
    
    This deletes inbound on-demand messages once they are read.
4. If deleteFileOnRead is set to true, do one of the following:
  - To retain a copy of the deleted files, set the value of the archive property to true and specify an archive directory.
    
    The files are removed from the input directory and are copied to the archive directory with a UUID appended to the name to ensure it is unique. This retains a history of the files that have been processed.
  - To simply delete the files once they are read, set the value of the archive property to false.

For inbound messages, use the file locking mechanism of the File BC to ensure that each inbound file is picked up only once by one instance in the cluster.

Use the following attributes to implement the locking mechanism:
- file:address/@lockName - The file name used for the F_LOCK.
- file:address/@workArea - The name of the working directory.
- file:address/@seqName - The name of the directory where all sequence numbers are saved.
- file:address/@persistenceBaseLoc - The name of the directory where the lock files are stored.
For more information, see Configuring File BC WSDL Attributes in Using the File Binding Component in a Project (under File Address Element) and Inbound Message Processing in Using the File Binding Component in a Project.