FTP protocol

This protocol allows the application to read or write a file using the file transfer protocol (ftp).

Protocol summary

Name
ftp
Description
Reads or writes a remote file using the file transfer protocol.
Resource name
Can contain the URL of remote resource, using ftp: protocol, or can be overridden using the protocol configuration parameters.
Operations
GET - read file contents.
PUT - create or replace file contents.

The ftp protocol implementation in zero.core uses java.net.URLConnection for ftp: URLs.

Example usage

The following example uses the Connection API to GET the contents of a file from an authenticated FTP server, using the system character encoding:

try {
    Connection conn = new Connection("ftp://ftp.projectzero.org/ftp/myFile.txt");
    Map<String, Object> parameters = new HashMap<String, Object>();
    parameters.put("userid", "user1");
    parameters.put("password", "password1");
    conn.setProtocolConfiguration("ftp", parameters);
    String resposeBody = conn.send().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 and uses a Content-Type header to control the chararacter encoding:

try {
    Connection conn = new Connection("ftp://ftp.projectzero.org/ftp/myFile.txt",
                                     Connection.Operation.PUT);
    Map<String, Object> parameters = new HashMap<String, Object>();
    parameters.put("userid", "user1");
    parameters.put("password", "password1");
    conn.setProtocolConfiguration("ftp", parameters);
    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 operation

The GET operation reads the contents of a file using FTP.

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.

Response body

The response body is an InputStream containing contents of file.

PUT operation

The PUT operation writes or replaces the contents of a file using FTP.

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.

Response body

No response body.

Configuration

Parameter Description Default
hostname Specifies the FTP server host name, overriding any ftp: URL value in the target resource name. Required if path is specified. Host name from target resource URL.
port If hostname is specified, then port specifies the network port for the FTP connection. Ignored if hostname is not specified. 21
path Specifies file path on FTP server. Required if hostname is specified. File path from target resource URL.
userid User ID for authentication with server. None.
password Password for authentication with server. (XOR strings are supported) None.
type File transfer type. binary

Values for the userid, password and type configuration parameters can be also included in target resource URLs following the standard form, ftp://userid:password@hostname:port/filePath@type=shortTypeValue . If any of these protocol configuration parameters is specified, it replaces any equivalent value in the resource URL.

The type configuration parameter can be set to the following values:

Type value Short value Description
binary i Binary transfer mode. This is the default type value.
text a Text transfer mode.

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

Version 1.1.30763