File protocol
This protocol allows the application to read or write a file on the local filing system.
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
filenameprotocol 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 may 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.getResponse();
} catch (Exception e) {
// Handle exceptions here
}
See Using the Connection API
for more information about using the Connection API.
Request and response format
GET and HEAD operations
Request headers
| Request header name | Comments |
|---|---|
Content-Type |
Optional file contents MIME type and charset. |
If a Content-Type header is supplied, the value will be associated with the response.
By supplying a Content-Type value containing a charset parameter, you can control the character
encoding the connection infrastructure will use if it is necessary to convert the response body from binary to character
data.
If Content-Type has multiple values, the first value will be used.
If no charset value is available, the system character encoding will be 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 (e.g. 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
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, the first value will be used.
If no Content-Type was specified the system character encoding will be 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 (e.g. Thu, 14 Feb 2008 13:14:11 GMT) |
Response body
No response body.
DELETE operation
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.
