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 JCX file.

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

Creating a New File Control

1. Click Add on the Controls tab to display a list of controls that represent the resources with which your business process can interact.

Note: If the Controls tab is not visible in WebLogic Workshop, click View —> Windows —> Data Palette from the menu bar.

2. Choose Integration Controls to display the list of controls used for integrating applications.
3. Choose File to display the Insert Control - File dialog box.
4. In the Variable name for this control field, enter the name of the new control. The name you enter must be a valid Java identifier.
5. Select Create a new File control to use and enter a name for the JCX file which will define the control in the New JCX name field.

You can use an existing control by selecting Use a File control already defined by a JCX file and entering a filename in the JCX file field.

6. Choose whether or not you want to make this a control factory by selecting or clearing the Make this a control factory that can create multiple instances at runtime checkbox. For more information about control factories, see Control Factories: Managing Collections of Controls.
7. 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.

8. In the file-mask 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-mask 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-mask field is optional when inserting a control, but this property must then be set dynamically before performing a file operation.

9. Select the type of data contained in the file using the file-type 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.
10. 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.
11. 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.

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.

12. Click Create.

File Control Methods

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

Example: File Control Declaration

When you create a new File control, its declaration appears in the JCX 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:

import weblogic.jws.*;
import com.bea.control.*;
import java.io.*;
import com.bea.data.RawData;
import com.bea.xml.XmlObject; 
 ... 
 /**
  * @jc:file directory-name="C:\directory"
  * file-mask="tax_file.txt"
  * 
  */
  public interface TaxFileControl extends
  FileControl,com.bea.control.ControlExtension
  { 
 /** 
  * @jc:file-operation io-type="readline"
  *  		  record-size="80"
  */
  RawData readLine();
  }  

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 @jc:file annotation controls the behavior of the File control. All of the attributes of the @jc:file annotation are optional and have default values.

To learn more, see @jc:file Annotation.

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

Related Topics

@jc:file Annotation