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 ControlContext interface 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 JPD file, or as annotations on its interface, callback, or method declarations in a JCX 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 Property Editor. These properties correspond to attributes of the @jc:file and @jc:file-operation annotations, which identify the File control in your code. The following attributes specify class- and method-level configuration attributes for the File control.
Annotation
Attribute
Description

@jc:file

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.

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.

@jc:file-
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 @jc:file annotation, see @jc:file 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 FileControl Interface.

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

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.

Related Topics

FileControl Interface

@jc:file Annotation

Previous Document Next Document