> Using Integration Controls > File Control

Using Integration Controls

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

File Control

Note: The File control is available in BEA Workshop for WebLogic Platform only if you are licensed to use WebLogic Integration.

A File control makes it easy to read, write, or append to a file in a file system. The topics in this section describe how to work with the File control. For information on how to add control instances to business processes, see Using Controls in Business Processes.

 

Topics Included in This Section

Overview: File Control

Provides an overview of the File control.

Creating a New File Control

Describes how to create a new File control using the BEA Workshop for WebLogic Platform graphical design interface.

Using a File Control

Describes how to use a File control in your business processes. Describes the default methods and the methods you can customize.

Example: File Control

Provides an example of a File control in the context of a business process.

Overview: File Control

A File control makes it easy to read, write, or append to a file in a file system. The files can be one of the following types: XmlObject, RawData (binary), or String. When creating a File control, select the file type that matches the files present in the specified directory.

In addition, the File control supports file manipulation operations such as copy, rename, and delete. You can also retrieve a list of the files stored in the specified directory.

Creating a New File Control

A File control performs an operation on a file. Each File control is customized to perform certain operations.

This topic describes how to create a new File control and provides an example of the File control's declaration in the java file.

For information on how to add control instances to business processes, see Using Controls in Business Processes.

Creating a New File Control

You can create a new File control and add it to your business process. To define a new File control:

  1. In the Package Explorer pane, double-click the business process (Process.java file) to which you want to add the File control. The business process is displayed in the Design view.
  2. Click on the Data Palette and from the drop-down list choose Integration Controls to display the list of controls used for integrating applications.
    3. Note: If the Data Palette view is not visible in BEA Workshop for WebLogic Platform, click WindowArrow symbolShowArrow symbolViewArrow symbolData Palette from the menu bar.
  3. Select File.

    4. The Insert control: File dialog box appears.

  4. In the Insert control: File dialog box enter the following details:
    • In the Field Name, type the variable name used to access the new File control instance from your business process. The name you enter must be a valid Java identifier.
    • In the Insertion point: from the drop-down list select the point where you want the field name to be inserted in the process file.
    • Decide whether you want to make this a control factory and select or clear the Make this a control factory that can create multiple instances at runtime check box. For more information about control factories, see Control Factories: Managing Collections of Controls.
    • Click Next.

      • The Create Control dialog-box appears.

  5. In the Create Control dialog box enter the following details:
    • In the Name field, type the name of your new control extension file.
    • Decide whether you want to add comments as configured in the properties of the current project and select or clear the Generate comments check box.
    • Click Next.

      • The Insert control- File dialog-box appears.

  6. In the Insert control- File dialog-box enter the following.
    • In the Directory Name field, enter the name of the directory where the File control looks for files. Alternatively, you can click the Browse button to locate a directory on your hard disk.

      • A directory name is the absolute path name for the directory; it includes the drive specification as well as the path specification. For example, the following are valid directory names: 

      C:\directory (Windows)
      /directory (Unix)
      \\servername\sharename\directory (Win32 UNC)

      You can also enter a period (.), which specifies the current working directory. When you enter a forward slash (/) in the Directory Name field, it is interpreted as follows:

      • UNIX systems—the root directory
      • Windows systems—the root of the user directory (for example, C: if the user directory is C:\bea).

        • The Directory Name field is required. Leaving the Directory Name field empty results in an error.

        Note: When writing files locally, if the specified directory does not already exist, it is created and the file is written into the new directory.
    • In the File name filter field, enter the file name filter, either a file name or file mask. Use file names for read, write and append operations. If the file name field contains a wild-card character, such as an asterisk (*), it is treated as a file mask. A wild-card character is specified to get the list of files in a directory. Wild-card characters are not valid for any other operation.

      • The File name filter field is optional when inserting a control, but this property must then be set dynamically before performing a file operation.

    • Select the type of data contained in the file using the Type of Data menu. The file type indicates the type of files present in the directory specified in the Directory Name field. Based on this type, appropriate methods (such as write(String data) or write(XmlObject data) or write(RawData data)) are generated for the File control. For example, if the directory contains XML documents, the type should be set to XmlObject so that read/write methods generated for the control will accept XmlObject variables. The same is true for RawData and String types.
    • If you are operating on a file of type String or XmlObject, you can optionally specify the character set encoding by entering the character set code in the Encoding field. This option can not be used with the large files option.
  7. If the specified directory contains files you want to read one line at a time, select the button labeled The directory contains large files to be processed. The resulting readLine() method is created with support for large files.

    8. You can define a line by specifying either its record size or a delimiter string:

    • If you enter a record size in the Record Size field, the file is read that number of bytes at a time.
    • If you are operating on a file of type String and you enter characters in the Delimiter string field, the file is read by record with each record defined as being terminated by that delimiter. Click Read file content including delimiter string to include the delimiter in the record.
      • WARNING: If the specified delimiter string does not exist in a file being processed, application behavior is unpredictable.

      If no record size or string delimiter is specified, the file is processed one line at a time. A line is considered to be terminated by any one of a line feed ('\n'), a carriage return ('\r'), or a carriage return followed immediately by a linefeed. This style of file processing can be used with any size file.

      Note: You cannot define a line by specifying both a record size and a string delimiter.
  8. Click Finish.

File Control Methods

To learn about the methods available on the File control, see the Interface FileControl.

Example: File Control Declaration

When you create a new File control, its declaration appears in the java file. The following code snippet is an example of what the declaration looks like when you choose the The directory contains large files to be processed option: 

package requestquote;
import com.bea.control.FileControl;
import org.apache.beehive.controls.api.bean.ControlExtension;
import com.bea.wli.control.dynamicProperties.FileControlPropertiesDocument;
/*
 * A custom File control.  
 */
@ControlExtension
@FileControl.FileInfo(directoryName = "C:/bea/")
public interface FileCntrl extends com.bea.control.FileControl {
	@FileControl.IOOperation(ioType = FileIOType.READLINE, delimiterString = "")
	String readline();
	static final long serialVersionUID = 1L;
	public FileCntrl create();
}

The actual attributes that are present on the @jc:file and @jc:file-operation annotations depend on the values you entered in the Insert Control dialog.

The @FileControlannotation controls the behavior of the File control. All of the attributes of the @FileControl annotation are optional and have default values.

To learn more, see FileControl Annotation.

The File control, named TaxControlFile in the example above, is declared as an extension of FileControl. The @FileControl.Operation annotations indicate that the file operation is readline (read tax_file.txt record by record) and specifies the record size.

Using a File Control

A File control performs operations on a file such as reading a file, writing a file, and appending data to a file. You can also use the File control to copy, rename, and delete files.

You usually configure a separate File control for each file you want to manipulate. You can specify settings for a File control in several different ways. One way is to set the File control's properties in Design view. Another way is to call the setProperties method of the FileControl interface. You can change File control configuration properties dynamically. To get the current property settings, use the getProperties() method.

You can also use the Interface ControlContext for access to a control's properties at run time and for handling control events. Property values set by a developer who is using the control are stored as annotations on the control's declaration in a JWS, JSP, or Process.java file, or as annotations on its interface, callback, or method declarations in a control file.

The following sections describe how to configure the File control.

Setting Default File Control Behavior

You can specify the behavior of a File control in Design View by setting the control's properties in the Properties pane. These properties correspond to attributes of the @FileControl and @FileControl.Operation annotations, which identify the File control in your code. The following attributes specify class- and method-level configuration attributes for the File control.

Table 7-1 Configuration
Annotation
Attribute
Description
@FileControl
directory-name
The absolute path name for the directory. (When writing files locally, if the specified directory does not already exist, it is created and the file is written into the new directory.)
file-mask
Either a file name or a file mask.
suffix-name
Suffix to be used with a timestamp or incrementing index for creating file names.
suffix-type
Specifies whether a timestamp or an incrementing index should be used as a suffix for file names.
@FileControl
continued
create-mode
Specifies whether a file is overwritten or renamed when a new file of the same name is created.

Note: When you use create-mode="rename=old" to rename a file, make sure that you mention the suffix-name and the suffix-type attributes for the new file name. If the suffix attributes are not indicated, then the File control overwrites the old file, instead of renaming it.
ftp-host-name
Name of the FTP host, for example, ftp://ftp.bea.com.
ftp-user-name
Name of the FTP user.
ftp-password
FTP user's password. If you specify this attribute, you cannot specify the ftp-password-alias attribute.
ftp-password-
alias
Alias for a user's password. The alias is used to look up a password in a password store. If you specify this attribute, you cannot specify the ftp-password attribute.
ftp-local-
directory
Directory used for transferring files between the remote file system and the local file system. When reading a remote file, the file is copied from the remote system to the local directory and then read. Similarly, when writing to a remote file system, the file is written to the local directory and then copied to the remote system.

Note: This is a temporary working directory for the File control. It should not be treated as a user-archive directory. The contents of ftp-local-directory are deleted after the FTP operation is performed.
@FileControl.Operation
io-type
Type of file operation (read, readline, write, or append).
file-content
Contents of the identified variable which will be written to the file.
record-size
Size of an individual record (in bytes) within a file to be processed record by record.
encoding
Character set encoding of the file.

To learn more about specifying default File control behavior with attributes of the @FileControl annotation, see FileControl Annotation.

Using Methods of the FileControl Interface

Once you have declared and configured a File control, you can invoke its methods from within your application to perform file operations and to change its configuration. For complete information on each method, see the Interface FileControl.

Use the following methods of the FileControl interface to perform file operations and reconfigure the File control.

Table 7-2 Methods
Method
Description
setProperties
Sets the properties for the control
getProperties
Gets the properties for the control
getFiles
Returns the FileControlFileListDocument XML Beans document defined in DynamicProperties.xsd
rename
Renames the current file
delete
Deletes the current file
copy
Copies the current file to a different location
reset
Reset the control by closing any operations in progress, such as readLine, readRecord and append.

The File control does not provide callbacks to wait for a file to appear. If the business process needs to wait for a file to appear, use the File Event Generator functionality. The business process can use the Message Broker Subscribe control to subscribe to a channel if it is interested in processing the files in a given directory. A File Event Generator is then configured so that when a file appears in that directory, it publishes a message to the associated channel containing the contents of the file.

Error Handling When Reading Files

The File control invokes an error handler when exceptions are encountered in read() methods. (Exceptions can occur when the contents of the file are invalid.) The error handler moves the file to an error directory. However, if the error directory is not configured, the error handler throws the following exception: File or Directory does not exist. To ensure that useful information about the exception is available, the exception thrown by the error handler is logged and appears on the WebLogic Server Console and the original exception is rethrown.

Example: File Control

This section provides an example of a File control used in the context of a business process. In this case, the File control instance writes a file to a specified location, triggered by a user request. This example assumes that you have created a new business process containing a client request node.

The business process is shown in the following figure:

The business process starts with a client request node, File Request, representing a point in the process at which a client sends a request to a process. In this case, the client invokes the fileRequest() method on the process to write a file with information on a new customer to the file system.

Complete the following tasks to design your business process to write the requested file to your file system:

To Create an Instance of a File Control in Your Project

In this scenario, you add one instance of the File control to your business process.

  1. Click Add on the Data Palette Controls tab to display a list of controls that represent the resources with which your business process can interact.
  2. Click Integration Controls, then choose File. The Insert Control dialog box is displayed.
  3. In the Insert File Control dialog box do the following:
    1. Enter myFile as the variable name for this control.
    2. Ensure that the following option is selected: Create a new File control to use. Then, enter myFile in the New name field.
    3. Enter values in the following fields:

      4. directory-name—Enter the location in which you want the File control to write the file. You can use any location on your file system. In this case, the directory name is C:/temp/customers.

      file-mask—Enter a name for the file. For example, enter CustFile.xml.

      file-type—Select XmlObject from the drop-down list.

    4. Click Create to close the Insert Control dialog box.

      5. An instance of a File control, named myFile, is created in your project and displayed in the Controls tab.

  4. Select FileArrow symbolSave to save your work.
To Design a Control Send Node in Your Business Process to Interact With Your File Control
  1. Expand the myFile control instance in the Data Palette. Then click the following method:
    2. FileControlPropertiesDocument write(com.bea.xml.XmlObject someData)
  2. Drag the method from the Data Palette and drop it on your FileWrite business process in the Design view, placing it immediately after the File Request node. The node is named write by default.
  3. Rename the node, replacing write with Write CustFile.
  4. Double-click the Write CustFile node. Its node builder opens on the General Settings tab.
  5. Confirm that myFile is displayed in the Control field and that the following method is selected in the Method field:
    6. FileControlPropertiesDocument write(com.bea.xml.XmlObject someData)
  6. Click Send Data to open the second tab in the node builder. The Method Expects field is populated with the data type expected by the write() method: XmlObject someData.
  7. In the Select variables to assign field, click the arrow to display the list of variables in your project. Then choose requestCustFile(InputDocument). If the variable does not already exist, you can choose Create new variable... to create it now.
  8. Click Apply and Close.
  9. Double click on the client request node (File Request) to open the node builder.
  10. Click Receive Data to open the second tab on the node builder. The Method Expects field is populated with the data type expected, in this case InputDocument CustFile. In the Select variables to assign field, click the arrow to display the list of variables in your project. Then choose requestCustFile(InputDocument).
  11. Click Apply and Close.

This step completes the design of your File control node.

At run time, pass a variable of type XmlObject to the Client Request method. The customer document is written to your file system in the location specified.


  Back to Top       Previous  Next