pub.file:getFile
WmPublic. Retrieves a specified file from the local file system.
If the file contains an XML document, you can use the services in the
XML Folder to convert it to an XML node.
Input Parameters
filename | String The absolute path name of the file in the local file system (for example c:\rubicon\document.xml). |
loadAs | String Optional. Form in which you want the getFile service to make the contents of the file available to subsequent services. Set to:  bytes to return the file as a byte array. Use this option if the contents of the file will be used as input to a service that operates on whole documents (for example,
pub.xml:queryXMLNode). This is the default. stream to return the file as an input stream. Use this option if the contents of the file will be used as input to a service that can process a document incrementally (for example,
pub.xml:getXMLNodeIterator). string to return the file as a string. reader to return the file as a reader. |
encoding | String Optional. Character set in which the file is encoded. Specify an IANA-registered character set (for example, ISO-8859-1). This information is required to correctly convert the String object to bytes when performing a get. If no value is specified or if the value is set to autoDetect, the service uses the default operating system encoding. If you specify an unsupported encoding, the system throws an exception. |
bufferSize | String Optional. Buffer size (in bytes) to use if you are loading an InputStream (that is, loadAs=stream). The default is 4096 bytes. |
Output Parameters
body | Document Document (IData object) containing the file as a byte[ ], InputStream, string, or reader. The body parameter will contain one of the following keys, depending on how the loadAs parameter was set: |
| Key | Description |
| bytes | byte[ ]Conditional. Returns file contents in a byte array if the loadAs parameter is set to bytes. |
| stream | java.io.InputStream Conditional. Returns file contents as an InputStream if the loadAs parameter is set to stream. |
| reader | java.io.Reader Conditional. Returns file contents as a reader if the loadAs parameter is set to reader. |
| string | String Conditional. Returns file contents as a string if the loadAs parameter is set to string. |
Usage Notes
The
getFile service
does not automatically generate an XML node from the contents of the file. To generate an XML node, the output from this service must be passed to the
pub.xml:xmlStringToXMLNode service.
The pub.file:getFile service first checks the value of the watt.security.pub.getFile.checkReadAllowed server configuration parameter to determine if the service must check the allowedReadPaths parameter in the fileAccessControl.cnf to retrieve the specified file.
If watt.security.pub.getFile.checkReadAllowed is set to true, the
pub.file:getFile service checks the contents of the allowedReadPaths parameter for the specified
filename. If the
filename appears in the allowedReadPaths list, the
pub.file:getFile service retrieves the file. If the specified
filename is not on the allowedReadPaths list, the service throws an exception.
If watt.security.pub.getFile.checkReadAllowed is set to false the
pub.file:getFile service retrieves the specified file without checking the allowedReadPaths parameter in the fileAccessControl.cnf.
For information about configuring the fileAccessControl.cnfe, refer to
File Access Control Configuration
for the pub.file Services.
See Also