Using File Parameters at Run Time

At run time you usually need to get only the name of the file. The file name is guaranteed to be an absolute path, and all parameter or root directory substitutions will already have been done. For an INPUT file parameter the file will exist and will already contain the data described by the Handler. For an OUTPUT file parameter the file will usually not exist but the directory for the file will exist.

ScalarVariable fileVar = 
  runEnv.getContext().getScalarParameter("myFile");
FileValueType fileValue = (FileValueType)fileVar.getValueObj();
String fileName = fileValue.getLocalFileName();

getLocalFile() is an alternative to getLocalFileName(). It returns a java.io.File instead of a String in case you want to call methods such as File.length() or File.canRead().

The component Executor can then open the file for reading for an INPUT parameter or writing for an OUTPUT parameter. Binary files should be accessed through a FileInputStream or FileOutputStream. Text files should be accessed using a FileReader or FileWriter to ensure that byte to character conversion is done correctly.

It is usually necessary to check for an IOException on the open. An IOException indicates the file does not exist or is unreadable and usually causes the component to fail.

FileInputStream fileStream;
try {
   fileStream = new FileInputStream(fileName);
}
catch (IOException ex) {
   throw new RtException(ex);
}

It is occasionally necessary to set the local file name for an OUTPUT file parameter at run time. You will have to set the local file name if the component runs an external program that writes a file with a name that cannot be determined at design time. The Component Executor determines where the file was written, usually by examining the output of the program, and sets the local name of an OUTPUT file parameter to the path to the file. Setting the local file name can be done for any output setting of the toOption—the file will be read and copied into the handler when the component finishes executing except for OUTPUT_OPTION_AUTO, where the path is passed on to the next component through parameter mapping.

String outPath = getPathFromProgramOutput();
fileValue.setLocalFileName(outPath);

outPath should be the absolute path to the file, although a relative path or file name will be interpreted as being relative to the Working directory. While the path may contain parameter substitutions, using them at run time is unlikely to be useful. Do not call setRawFileName at run time—it will not work correctly.

As a convenience in reading or writing a Text file that may have been configured with a specific file encoding, FileValueType has two methods: getLocalFileReader() and getLocalFileWriter(). These two methods return a Reader or Writer that access the local file using the Read/Write encoding configured into the File Parameter. These methods are valid only for a File parameter configured to be TYPE_TEXT.