File protocol

This protocol allows the application to read or write a file on the local filing system.

Protocol summary

Name
file
Description
Reads or writes the contents of a file on the local filing system.
Resource name
Can contain the local file name or URL, or can be overridden using filename protocol configuration parameter.
Operations
GET - read file contents and attributes.
HEAD - read file attributes.
PUT - create or replace file contents.
POST - create or append to file contents.
DELETE - delete file.

The file name can be specified as either a file: URL or a local file path. Remote filing systems are not supported. Specifying ~ as the first path segment name signifies a path relative to the application root. For example, the path file:///~/images/image.gif indicates the file named images/image.gif relative to the application root directory.

Example usage

The following example uses the Connection API to GET the contents of a file using the system character encoding:

try {
    String resposeBody =
        Connection.doGET("file:///C:/documents/myDocument.txt").getResponseBodyAsString();
    // Read document is now in responseBody
} catch (Exception e) {
    // Handle exceptions here
}

The PUT operation can be used to replace the contents of a file. The following example replaces the contents of a file within the application, using the system character encoding:

try {
    Connection.doPUT("file:///~/myFile.txt", "This is the new contents of the file.");
} catch (Exception e) {
    // Handle exceptions here
}

The POST operation can be used to append to the contents of a file. The following example appends to a file and uses a Content-Type header to control the chararacter encoding:

try {
    Connection conn = new Connection("file:///~/myFile.txt", Connection.Operation.POST);
    conn.addRequestHeader("Content-Type", "text/plain; charset=\"UTF-8\"");
    conn.setRequestBody("This is the new contents of the file.");
    conn.send();
} catch (Exception e) {
    // Handle exceptions here
}

See Using the Connection API for more information about using the Connection API.

Request and response format

This section details the headers and body types for the requests and responses of the supported operations.

GET and HEAD operations

The GET operation reads the attributes and contents of a file on the local filing system. The file is locked during the read operation. The HEAD operation only returns the file attributes.

Request headers

Request header name Comments
Content-Type Optional file contents MIME type and charset.

If a Content-Type header is supplied, the value is associated with the response. By supplying a Content-Type value containing a charset parameter, you can control the character encoding the connection infrastructure uses if it is necessary to convert the response body from binary to character data. If Content-Type has multiple values then the first value is used. If no charset value is available then the system character encoding is assumed.

Request body

No request body.

Response headers

Response header name Comments
Content-Type Value specified in request header, if supplied.
Content-Length Length of file.
Last-Modified Last modified time, in RFC 1123 format. For example, Thu, 14 Feb 2008 13:14:11 GMT.

Response body

For the GET operation, the response body is an InputStream containing contents of file. There is no response body for the HEAD operation.

PUT and POST operations

The PUT operation creates or replaces the contents of a file. The POST operation creates or appends to the contents of a file. The file is placed on the local filing system and is locked during the write operation.

Request headers

Request header name Comments
Content-Type Optional file contents MIME type and charset.

Request body

Request body type Comments
String or Reader Converted to binary data according to charset encoding in Content-Type header. If Content-Type has multiple values then the first value is used. If no Content-Type was specified then the system character encoding is used.
byte[] or InputStream Binary data written to file, without conversion.
Other types Converted to String using toString() and processed as above.

The file protocol also supports applications using Connection.getRequestOutputStream() without additional buffering of the request body.

Response headers

Response header name Comments
Content-Type Value specified in request header, if supplied.
Content-Length Length of file.
Last-Modified Last modified time, in RFC 1123 format. For example, Thu, 14 Feb 2008 13:14:11 GMT.

Response body

No response body.

DELETE operation

The DELETE operation deletes a file on the local filing system.

Request headers

No request headers.

Request body

No request body.

Response headers

No response headers.

Response body

No response body.

Configuration

Parameter Description Default
filename Can be used to override the name of the file to be operated on. Request target resource name.
writeTimeout Time out period when waiting for write lock, in seconds. 5
readTimeout Time out period when waiting for read lock, in seconds. 5

Protocol configuration can be applied to the connection request using various mechanism, as described in Configuring protocols.

Version 1.1.31300