FileWriter

The FileWriter component writes the received data from its input port to the specified output file. The received data can either be plain text or binary data.

File Writer is capable of handling:

• Text files

Text content from input message is written to the configured file in text format.

• Binary Files

Binary content from the input message is written to the configured file in binary format.

File Writer uses core Java APIs to write the files.

Points to note

• The component runs on the Peer Server and therefore the file paths and directories mentioned in the CPS should be valid on the machine where the Peer Server is running. If the component fails over to another peer, ensure that the machine on which the secondary Peer Server is running does have the same path available.

• The received XML equivalent of the unstructured plain text needs to be transformed to its original format using the XML -> Flat component.

• FileWriter closes the file and moves it to the target directory on receiving a message having property COMPLETE whose value is set to true. This is useful even when you use Append if Exists output mode for the FileWriter component and you would like to close the file on the occurrence of this event.

• The FileWriter component uses the JMS Header filename to get the file name from the input message.

TOP

Configuration and Testing

Interaction Configurations

Business logic configuration details are configured in the second panel, Interaction Configurations. Figure 1 illustrates the panel with expert properties  view enabled.

Figure 1: Interaction Configurations.

TOP

Attributes

Is input Binary?

Specifies whether the input received on the input port is binary.

        ●  yes -

Writes the data as bytes into the target file.

        ●  no -

Writes text to the specified target file in an unstructured fashion.

Note: The Output message sent to the output port depends on the configuration provided here. When set to yes, it hides the property Output Mode.

Compute Paths relative to Directory

The path of the directory relative to which the paths of Target Directory, Working Directory, and Error Directory are computed. By default, this points to the FIORANO_HOME directory. If the paths specified for Target/Working/Error Directories are not absolute, their paths are calculated relative to the directory specified here.

Note: If the path specified for Target Directory/Working Directory/Error Directory is absolute, the path specified for Compute Paths relative to Directory will not be used in the computation of the directory paths.

Is Configured for Different Machine?

Specifies whether the Peer Server on which the component is to be launched and Fiorano Studio are running on the same machine or on different machines. This helps the component to determine the type of dialog to be shown while providing the paths of Source Directory, Working Directory, and Error Directory. When both the Peer Servers and the Fiorano Studio is running on the same machine, the paths to the above specified directories can be chosen from a file dialog with the directory structure of the current machine as shown in Figure 2. Otherwise, a text editor will be shown where the paths of Source/Working/Error directories need to be typed in as shown in Figure 3.

• yes -

If the Peer Server on which the component is to be launched and Fiorano Studio are running on different machines.

• no -

If the Peer Server and Fiorano Studio are on the same machine.

When this property is set to no, paths of directories can be chosen from the file dialog. When the property is set to yes, the paths of directories should be manually specified in the Text Editor as shown in Figure 2 and Figure 3.

Figure 2: Choosing directory path using File Dialog

Figure 3: Specifying directory path using Text Editor

File name

The name of the file to which the input data has to be written is specified here. If the file with this name does not exist, a new file is created.

Note:

• If the property Use file details from message headers is set to Yes, then this name would be used only if the FileName property is not present in the header of the incoming message.

• When no file name is specified both in the CPS and the message header, FileWriter throws an exception.

Use file details from message headers

Specify if the file details are to be taken from the header of the input message.

●  yes

The name of the target file would be the value of the header property FileName present on the input message and the target directory would be the value of the header property directory.

        ●  no -

When the property is set to no, the value specified for the CPS property File name is used.

Note: If Use file details from message headers is yes and if the property FileName is not found in the message headers, the File name from the CPS is used. Similarly, the directory specified in the CPS (Target Directory) is used as the target directory if the property directory is not found in the message headers.

Target Directory

The path of the directory where the target file (with the data received on the input port) is created. An absolute path of the target directory or a path relative to the directory specified in Compute Paths relative to Directory can be specified here. While specifying a directory as the Target Directory, make sure that you have permissions to create/modify files present in this directory.

If Is configured for different machine? is set to no, clicking the ellipses  button will open a file dialog, as shown in Figure 2, where the directory can be chosen from the file system. Otherwise a text editor pops up where the path of the directory needs to be typed in. Shown in Figure 3.

Note:

• If this folder does not exist, FileWriter creates it while processing the input message.

• If the property Use file details from message headers is set to yes, the directory specified here would be used only if the directory property is not present in the incoming message headers. FileWriter throws an exception if no directory is specified both in the CPS and in the message headers.

Append timestamp?

Specifies whether a timestamp is to be appended to the name of the target file.

Note: When Is input binary? is set to No, this property appears only when Output mode is set to New file for each message.

Timestamp format

Specify the format in which the timestamp is to be appended to the name of the target file. Figure 4 shows the descriptions for the symbols that could be used in the Timestamp format.

Figure 4: Symbols used in Timestamp format.

Example: If Test.txt is the filename to which the data is to be written, the target file created could be Test_02042008_183950765.txt when the default format (ddMMyyyy_HHmmssSSS) is used.

Note: This property is visible only when Append timestamp? is set to Yes.

Append Counter?

        ●  yes -

Appends a counter to the name of each file processed by the FileWriter in addition to the timestamp. The name of the file would look like <filename>_<time stamp>_<counter>. Appending counter to file names ensures that no two files created can have same name.

        ●  no -

No counter is appended to the target file processed by the component FileWriter.

Example: If Test.txt is the filename to which the data is to be written, the target file created could be Test_02042008_183950765_0.txt when Append Counter? is set to yes.

Note: This property is visible only when Append timestamp? is set to  yes.

Output Mode

Specify the way in which the output is to be created with the received data. Figure 5 shows the output modes that can be used.

Note: This property is visible only when Is input Binary? is set to No.

Figure 5: Output Mode

• New file for each message

This option tells the FileWriter to create a new file for each input message that has been processed. When this output mode is being used, timestamp and counter can be appended to the filename using the properties Append timestamp? and Append counter?. The Append timestamp? option will be visible only when this option is selected as the Output Mode.

Note: If the same File name is specified for two different input messages and no time stamp or counter is appended, the existing file is overwritten.

• Append and close on timeout

This output mode is used for appending the content of all messages received till timeout, to a single file. During this time interval, the file is present in Working directory. When the timeout occurs, the file is closed and is moved to Target directory. Selecting this option will show the property File Timeout (min) which can be used to set the timeout. The property File Timeout is visible only when Output Mode is set to Append and close on timeout.

        Note:

• Only one file holds the content of all messages received during the configured time interval. The name of this file would be the value specified for the Header property FileName on the first message received in this time interval, if Use file details from message header? is set to yes. If not, the file name would be the value of the property File Name specified in CPS.

• If, for any reason, the component is stopped/relaunched before the specified timeout, further messages will be processed into a new file.

• Append and close on event

This output mode is used for appending the content of all received messages to a single file until CLOSE_EVENT occurs. When a message with the header property CLOSE_EVENT set to true is received, the content of this message is appended to the file, the file is closed and is moved from Working directory to Target directory.

Note:

• The file will continue to be in the working directory till it receives a closing event.

• Only one file holds the content of all messages received until CLOSE_EVENT occurs. The name of this file would be the value specified for the Header property FileName on the first message received, if Use file details from message header? is set to yes. Otherwise, the file name would be the value of File Name specified in CPS.

• Do not write to file but send to output

The received data is sent to the output port instead of writing into a file. Figure 6 and Figure 7 show the snapshots of the text and binary data sent to output port.

Note: If Is Input Binary? has to be set to yes for treating the input as binary.

Figure 6: Text data received on output port.

Figure 7: Binary data received on output port.

Note: Selecting Do not write to file but send to output will hide the property Return data on Output? Since, the output will definitely be sent to the output.

• Append if exists

If the file to which the data is to be written already exists, data is appended to the content in the existing file. The file being processed will be moved to the Working directory and content received in the input message will be appended to the existing file until FileWriter receives a message with a property COMPLETE set to true. (JMS function setStringProperty() can be used to set the value of a JMS property on a message).

Note: Until FileWriter receives a message with this property COMPLETE set to true, it keeps the file in Working directory.

File Timeout (min)

The time for which the component has to wait before closing and moving the file from Working directory to the Target directory is specified using this property. This is visible only when Append and close on timeout is selected as the Output Mode.

Note: File timeout cannot be a fraction. Hence, the minimum timeout that can be specified is 1 minute.

File Encoding

The encoding to be used while writing the file. The following encodings can be used. Figure 8 shows all the encodings that can be used.

Figure 8: Different types of File Encoding

• SCII -

A coding standard used to represent plain text. It is based on the order of English Alphabet

• Cp1252 -

 This is a character encoding of the Latin alphabet.

• UTF8 -

 A variable-length character encoding for Unicode.

• UTF-16 -

 This is a variable-length character encoding for Unicode. The encoding form maps each character to a sequence of 16-bit words.

• ISO8859_1 -

ISO 8859-1, more formally cited as ISO/IEC 8859-1 is part 1 of ISO/IEC 8859, a standard character encoding of the Latin alphabet.

• EUC_KR

• EUC_JP

• EUC_CN

• EUC_TW

EUC_KR, EUC_JP, EUC_CN, EUC_TW are multi-byte character encoding systems used for Korean, Japanese, Simplified Chinese, and Traditional Chinese languages respectively.

Working directory

The path of the directory which should hold the files during intermediate processing. Either an absolute path or a path relative to the directory specified in the Compute Paths relative to Directory can be provided.

If Is configured for different machine? is set to no, clicking the ellipses  button will open a file dialog, as shown in Figure 2, where the directory can be chosen from the file system. Otherwise, a text editor pops up where the path of the directory needs to be typed in. Shown in Figure 3.

Note:

• When Output mode is Append and close on timeout or Append and close on event, Working directory holds the files until the timeout or CLOSE_EVENT occurs.

• If this directory does not exist, FileWriter creates it while processing the input message.

• FileWriter requires write permissions on Working and Error directories.

Error directory

Path of the directory which should hold the files for which the processing has not been successful.

Note:

• Either an absolute path or a path relative to the directory specified in the Compute Paths relative to Directory can be provided.

• If this directory does not exist, FileWriter creates it while processing the input message.

• For any file, when the processing is successfully finished, FileWriter moves the file from Working directory to Target directory. If the processing is not successful, the file gets retained in the Working directory itself. When FileWriter receives data which is to be written to the file that already exists in the Working directory, FileWriter moves the existing file in the Working directory to Error directory and then creates a new file with the input data. Every file that moves to the Error directory will have appended to its name, the time (in milliseconds) at which it is moved to the Error directory.

• FileWriter requires write permissions on Working and Error Directories.

PostProcessing Command

Script or a Command that is to be executed after the file processing is finished. A command can be specified by simply typing it in the text area provided against this property. To provide a script file, the file dialog which is shown by clicking the ellipses  button can be used.

By default, the component appends the absolute path of the target file to this script/command that is. the absolute path of the target file would be the first argument to this script/command. More arguments for this command could be specified using the property PostProcessing Arguments. The final command formed by the FileWriter would be <PostProcessing Command> + <Absolute path of the target file> + <PostProcessing Arguments>.

PostProcessing Arguments

Arguments that are passed to postprocessing script or command.

Using Named Configurations

Changes are done in eStudio wrt to Named Configurations.With the implementation of Named Configurations, Interaction Configurations panel is changed as shown in Figure:9.

Figure 9:Modified Interaction Configurations panel

Some properties are grouped as one property in the modified configuration panel. Is configured for different machine , Compute Paths relative to Directory, File Name, Target Directory, Working Directory and Error Directory which were present previously in the Interaction Configurations panel are grouped under the name File Writer Configuration.

Figure 10:File Writer Configuration panel

TOP

Sample scenario

Copying all the files present in Error directory to a backup location after the file is processed.

Solution:

A batch file copyerrors.bat with content copy C:\FileWriter\ErrorDir %2 is written and is placed in C:\. The path of this batch file is specified for the property PostProcessing Command. The backup location (C:\ProcessingFailures) is specified as the value for PostProcessing Arguments.

Let C:\FileWriter\TargetDir\test.txt be the target file. With this configuration, the command formed by FileReader would be C:\copyerrors.bat C:\FileWriter\TargetDir\test.txt C:\ProcessingFailures. The copy command executed finally would be copy C:\FileWriter\ErrorDir C:\ProcessingFailures which moves all the files in C:\FileWriter\ErrorDir to the backup location C:\ProcessingFailures.

Return data on Output?

Determines if the data written to the file is to be sent onto the output port instead of sending out an XML message containing the details of the file to which the content has been written. Figure 6 and Figure 7 show sample views of the text and binary data sent on the output port. As shown in the figures, setting this property to Yes will send the data in the output message. However, the file details can still be fetched from the message headers of the output message. Refer Table 1 for the description of header properties.

Note: This property is not visible when Output mode is set to Dont write to file but send to output.

Header Properties

Table 1 shows the descriptions of header properties set by the component on the output message when binary/flat content is processed.

Table 1: Header Properties

TOP

Input and Output

Input

No schema is set on the input port. If any XML message has to be written into a file then the XML message is directly sent as input message.

Output

When a file is written successfully, FileWriter sends out the file information onto the output port. Figure 11 shows the schema of the output XML message. Table 2 shows the description of the schema elements.

Figure 11: Schema on the output port

Table 2: Description of Output schema elements

TOP

Testing the Interaction Configurations

Interaction configurations can be tested from the CPS by clicking the Test button. Figure 12 and Figure 13 shows the sample input and the corresponding output message respectively.

Figure 12: Sample input

Figure 13: Output generated for input shown in Figure 12.

TOP

Functional Demonstration

Scenario 1

Writing the input message into to a file and displaying the response contents.

Configure the FileWriter as shown in Figure 13.

Figure 14: Sample Configuration of FileWriter

Use feeder and display component to send sample input and check the response.

Figure 15: Demonstrating scenario 1 with sample input and output

Input Message

Input Text

Output Message

<?xml version="1.0" encoding="UTF-8"?>

<ns1:Result xmlns:ns1="http://www.fiorano.com/fesb/activity/FileWriter1">

   <ns1:FileInfo>

      <FullName>/home/geetha/backup/Target/out_10032009_142102262_0.txt</FullName>

      <FileName>out_10032009_142102262_0.txt</FileName>

      <FilePath>/home/geetha/backup/Target</FilePath>

      <Type>File</Type>

      <ReadAccess>true</ReadAccess>

      <WriteAccess>true</WriteAccess>

      <Size>10</Size>

   </ns1:FileInfo>

</ns1:Result>

TOP

Use Case Scenario

In a revenue control packet scenario if an error occurs while parsing the transaction data, error message is written to file.

Figure 16: Revenue Control Packet Scenario.

The Event Process demonstrating this scenario is bundled with the installer.

Documentation of the scenario and instructions to run the flow can be found in the Help tab of flow when open in Studio.

TOP