JavaTM Platform, Enterprise Edition (Java EE) 5 Technologies
Project Open ESB Starter Kit
Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

File Binding Component Overview


Contents

The following topics describe the File Binding Component.

About the File Binding Component
File Binding Component Features
Installing the File Binding Component
Configuring the Design-Time Components
File Client Use Cases
WSDL Examples
File BC Limitations

About the File Binding Component

The File Binding Component (BC) is a JSR-208 compliant JBI runtime component that provides a comprehensive solution to interact with a file system within a JBI environment.

The design time component of File Binding component is a NetbeansTM module that provides plug-in to NetBean's project system and thus defines how File binding can be used. The runtime component implements all required component interfaces in JBI specification and provides functionality for this component to assume roles either as a service consumer (inbound) or service provider (outbound).

File BC as a Service Provider

In the case of outbound message flow, where the File Binding Component is being “invoked” by other components, the File Binding Component acts as an external File service provider. In this role, the File Binding Component converts a normalized message--that it receives as part of the message exchange from other components--to a File type message. After the File type message is created as a result of the message conversion, the File type message is written to a file system.

File BC as a Proxy Consumer

In the case of inbound message flow, where the File Binding Component consumes the services of other components, the File Binding Component acts as an external File proxy consumer. In this role, the File Binding Component converts the File type message, that it receives from the file system, to a normalized message. The normalized message is then sent, as part of the message exchange, to another component as a service request.

top

File Binding Component Features

Features of the File Binding Component include:

  • Reading from and writing to a particular file, or file name pattern
  • Copying an input or output file to a user-defined file, file name pattern
  • Processing multiple records per file
  • Adding and removing end-of-line characters to the file
  • Maximum bytes per record processing
  • Request-Reply Message Exchange Pattern
  • In-Only Message Exchange Pattern

Installing the File Binding Component

The bundled packages include a runtime component, and a design-time component. Installation of these run-time and design-time components is not covered in this topic. For more information, please refer to the following:

Design-Time Installation

Refer to the following document for instruction on installing the design-time portion of the File BC.

http://caps.red.iplanet.com/pubs/shasta/JBIAddOns/JBI_AddOns.html

Run-Time Installation

Refer to the following document for instruction on installing the run-time portion of the File BC.

Configuring the Design-Time Components

Configuring the File BC design-time components means configuring the WSDL extensibility elements. File WSDL extensibility elements are used to specify File binding specific configurations for the file system format.

In WSDL, the term binding refers to the process associating protocol or data format information with an abstract entity like a message, operation, or portType. In the case of the File BC, the abstract portion of the WSDL could be used to either "read" or "write" to a file, while the concrete portion of the WSDL contains the extensibility elements that describe the actual attributes of the message.

WSDL points of extensibility, called extensibility elements, reside under various WSDL defined elements. The File Binding Component includes two extensibility elements called file:read and file:write to add clarity to the concrete portion of the WSDL.

The file directory to read from or to write to is specified in the file:address element. For One-Way type of operations, the fileDirectory attribute allows you to specify the file folder to interact with. For Request-Response type of operations, this attribute specifies the directory for both read and write.

You can configure two extensibility element groups for the File Binding Component:

Service Level File Extensibility Elements

The File address extensibility element allows users to specify the "connectivity" information to a file system.

File address element attributes include the following:

Element Name Description Mandatory Example
fileDirectory Defines the directory path in the file system to read from or write to. Yes /home/joe/data
relativePath Specifies whether the directory is a relative path. No true
pathRelativeTo Defines what the fileDirectory is relative to. The root path is a standard Java system property that can be read from runtime JVM settings. No User Home

The following is a sample usage of the File address extensibility element defined for a service port:

<service name="SomeService">
  <port binding="tns:someBinding" name="fileEndpoint">
    <file:address fileDirectory="/home/joe/test"/>
  </port>
</service>

Binding Level File Extensibility Elements

File extensibility elements at the binding level define file transport specific details for operations and messages. These extensibility elements allow specification of File specific details for each port.

File binding extensibility element

The file:binding extensibility element allows the association of a binding to be File protocol specific. Following is a sample usage: 

<binding name="someBinding" type="tns:somePortType">
  <file:binding/>
</binding>

File operation extensibility element

The file:operation extensibility element allows the association of an abstract operation to a File operation. Following is a sample usage: 

<binding name="someBinding" type="tns:somePortType">
  <file:binding/>
  <operation name="someOp">
    <file:operation/>
</binding>

File operation extensibility element

The file:read extensibility elements allow users to specify the element features for reading a file.

File read element attributes include the following:

Attribute Description
pollingMillis Defines the polling interval for detecting input files in milliseconds.
fileNameIsPattern Indicates whether or not the fileName attribute designates a Java regular expression based pattern.
fileName Defines the file name relative to the specified directory to read from. If fileNameIsPattern is true, this attribute specifies the Java regular expression based pattern used for filtering input files from the directory path; otherwise, this attribute specifies the actual file name from which to read the operation input.
encoderType Defines the encoder type to be used decode the raw input data. If used, this attribute is tightly coupled with the message part type definition and will be validated to ensure a match.
removeEOL Defines whether end-of-line characters should be removed before processing.
part Defines the reference to the abstract message part and its type in the WSDL to apply the input message.
maxBytesPerRecord Defines the maximum number of bytes per record.
multipleRecordsPerFile Defines whether the file to read from the file system contains multiple records or should be considered a single payload.

File operation extensibility element

The file:write extensibility elements allow users to specify the element features for writing a file.

File write element attributes include the following:

Attribute Description
fileNameIsPattern Indicates whether or not the file name to write to contains a file name pattern.
fileName Defines the file name relative to directory to write to. If fileNameIsPattern is true, the value of this attribute will be ignored.
filePrefix Defines the file name prefix to create a file name to write to. Note that if fileNameIsPattern is true, this attribute is required to create a valid file name to write to.

fileExtension Defines the file name extension to create a file name to write to. Note that if fileNameIsPattern is true, this attribute is required to create a valid file name to write to. A one-up sequence number will be used to denote the file name to write to. The starting index of the sequence number will be 0. For example, if filePrefix is "output" and fileExtension is "txt", the initial file name to write to will be "output0.txt".
encoderType Defines the encoder type to be used encode the output data. If used, this attribute is tightly coupled with the message part type definition and will be validated to ensure a match.
part Defines the reference to the abstract message part and its type in the WSDL to apply the output message to.
addEOL Defines whether end-of-line characters should be added.
multipleRecordsPerFile Defines whether the file to write to the file system contains multiple records or should be considered a single payload. If the value of this attribute is true, subsequent calls to the operation will result in appends to the same file

top


File Client Use Cases

Use Cases provide scenarios that convey how components interact with external systems to achieve a specific business goal.

The following use cases describe how to read a file and how to write to a file. The File Binding Component offers communications in two directions: outbound, invoking external service providers, and inbound, where external clients invoke services provided by the binding component.

Use Case 1: Read a File and Submit Contents to the NMR

In this example, a folder corresponding to an endpoint is polled periodically. All the files that satisfy the content conditions are read and the contents converted to a normalize message, which is then submitted to the NMR. The normalized message is created depending on whether the file conforms to the supported message type.

Results

The status of the message exchange is recorded in the log file. The file is moved to the processed folder once the message exchange is completed.

Main Scenario

  1. Folder that has been configured as the input directory is polled. Folders corresponding to each operation are checked for files. All the folders corresponding to the one endpoint are polled one by one, this way there is no starvation. Files picked up from folders corresponding to the operation names are targeted for that operation. If files are present in the input directory then the default operation and its characteristic will be considered. The default operation will be the first operation that is configured.

  2. All the files present in this folder have to be sent to the service that is configured for this endpoint and the operation, depending on which sub folder it was picked up from.

  3. If it is a supported message type, then the file is parsed and the contents set on the source of the Normalized message.

    The File Binding Component does not validate the schema or contents of the file being read. For example, with XML files if the contents of a message do not contain well-formed XML, an error is reported. Otherwise, no validation of the contents occurs.

  4. The message is wrapped according to the JBI specification.

  5. A message exchange is initiated with the respective service. The moves to the processed folder only after a complete status is received from the invoked service.

  6. If a response is expected, depending on the Message Exchange Pattern, then a response is written out into a file. The pattern of the output file and the folder name is specified as per the file type used. In one-way exchanges, a completed file is created. After creating the output file, the input file is moved from the input directory to a processed directory. There is only one processed folder per endpoint.

Use Case 2: Write the Contents of a Normalized Message to a File

In this example, the File Binding Component accepts requests for provider endpoints. The contents of these requests are written to files in the corresponding write folders. One-way (robust and non-robust) cases are only supported. Request-response is not supported because there is no way to identify a response corresponding to a request.

Results

The message content is written to a file in a specified folder in the deployment file.

Main Scenario

  1. The binding component receives a message for a provider endpoint. The endpoint details are gathered from the endpoint cache.

  2. The message content is extracted and unwrapped, and a file is written out into the output folder corresponding to the endpoint.

  3. The message exchange finishes. In the case of an error, an appropriate error message is generated.

Note: The provider service can only support an operation of in-only. This is because the binding cannot return any message.

top

WSDL Examples

The following describes how to use the File Binding Component Extensibility Elements to:

  • Specify a file name to read from or write to
  • Specify a directory to read from or write to

In WSDL the term binding refers to the process associating protocol or data format information with an abstract entity like a message, operation, or portType. The following abstract portion of the WSDL could be used to either read a file, or write to a file. In this example, the input element specifies the abstract message format for an one-way “inbound” operation. 

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:file="http://schemas.stc.com/jbi/wsdl-extensions/file/" 
xmlns:slnk="http://schemas.xmlsoap.org/ws/2002/07/service-link/" 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="urn:FooBar3"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
name="FileHelloService1"
targetNamespace="urn:FooBar3">
<message name="HelloIF_sayHello">
  <part type="xsd:string" name="body"/>
</message>
<message name="HelloIF_sayHelloResponse">
  <part type="xsd:string" name="result"/>
</message>
<portType name="FileHelloIF">
  <operation name="sayHello">
    <input message="tns:HelloIF_sayHello"/>
  </operation>...

WSDL points of extensibility, called extensibility elements, reside under various WSDL defined elements. In the File Binding Component, extensibility elements are used to specify specific binding information for the file system format.

The File Binding Component includes two extensibility elements called file:read and file:write to add clarity to the concrete portion of the WSDL.

The file directory to read from or to write to is specified in the file:address element. For One-Way type of operations, the fileDirectory attribute allows you to specify the file folder to interact with. For Request-Response type of operations, this attribute specifies the directory for both read and write. The conceptual idea is that the File Binding Component's interaction with the file system is defined and limited by the address, which is similar to a SOAP URI.

If the abstract portion of the WSDL listed above describes an inbound consumer message, then the concrete portion of the message should appear as follows:

<binding name="HelloDocElem2DocElemIFBinding" 
type="tns:FileHelloIF">
<file:binding/>
  <operation name="sayHello">
  <file:operation/>
    <file:read use="literal" pollingMillis="3000" 
     fileName="Input.dat"/>
   </input>
  </operation>
</binding>
<service name="FileHelloService1">
<port binding="tns:HelloDocElem2DocElemIFBinding" name="HelloDocElem2DocElemIFPort">
<file:address fileDirectory="c:/test"/>
</port>
</service>

If the abstract portion of the WSDL listed above describes an outbound consumer message, then the concrete portion of the message should appear as follows:

<binding name="HelloDocElem2DocElemIFBinding" 
type="tns:FileHelloIF">
<file:binding/>
  <operation name="sayHello">
  <file:operation/>
    <input>
      <file:write use="literal" fileName="Output.dat"/>
    </input>
  </operation>
</binding>
<service name="FileHelloService1">
<port binding="tns:HelloDocElem2DocElemIFBinding" name="HelloDocElem2DocElemIFPort">
  <file:address fileDirectory="c:/test"/>
</port>
</service>

For request-response type of operations, the complete WSDL would appear as follows:

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" 
xmlns:file="http://schemas.stc.com/jbi/wsdl-extensions/file/" 
xmlns:slnk="http://schemas.xmlsoap.org/ws/2002/07/service-link/" 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
xmlns:tns="urn:FooBar3" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
name="FileHelloService1" 
targetNamespace="urn:FooBar3">
<message name="HelloIF_sayHello">
 <part type="xsd:string" name="body"/>
</message>
<message name="HelloIF_sayHelloResponse">
  <part type="xsd:string" name="result"/>
</message>
<portType name="FileHelloIF">
  <operation name="sayHello">
    <input message="tns:HelloIF_sayHello"/>
    <output message="tns:HelloIF_sayHelloResponse"/>
  </operation>
</portType>
<binding name="HelloDocElem2DocElemIFBinding" type="tns:FileHelloIF">
<file:binding/>
  <operation name="sayHello">
  <file:operation/>
    <input>
      <file:read use="literal" pollingMillis="6000" 
      fileName="Input.dat"/>
    </input>
  <output name="output">
    <file:write use="literal" fileName="Output.dat"/>
  </output>
  </operation>
</binding>
<service name="FileHelloService1">
<port binding="tns:HelloDocElem2DocElemIFBinding" name="HelloDocElem2DocElemIFPort">
<file:address fileDirectory="c:/test"/>
</port>
</service>
</definitions>

Note how the file:read and file:write attributes are specified for request-response type of operations.

top

File BC Limitations

The following limitations apply to the File Binding Component:
  • Solicit-Response and Notification types of operations are not supported.
  • Outbound Request-Response operations are not supported.
  • A request may arrive for a provider endpoint that is no longer hosted by the binding component, such as when the component is undeployed. In such cases, no entry exists in the endpoint cache, and so an error message is generated and the object is returned. This is possible only in cases where the deactivation of an endpoint failed.
  • If the output folder does not have the required permission or the required space, then an error message is generated.

top