Config URI format

Since v2.2.4, a mechanism exists that allows users to specify the complete ECS S3 client configuration in a single string by using a Config URI. A Config URI follows the standard URI spec:

<protocol>://<host>[:<port>][/path][?<param-key>=<param-value>][&<param-key>=<param-value>][...]

To convert a config URI to an S3Config object and back, use the following code:

ConfigUri<S3Config> s3ConfigUri = new ConfigUri<S3Config>(S3Config.class);
S3Config s3Config = s3ConfigUri.parseUri(uri); // convert a config URI to S3Config instance
uri = s3ConfigUri.generateUri(s3Config); // convert an S3Config instance to a config URI

Here are some examples.

• A simple S3 client config URI for ECS Test Drive.

    https://object.ecstestdrive.com?smartClient=false&useVHost=true&identity=<access-key>&secretKey=<secret-key>
  

• A standard S3 client config URI for a local ECS deployment using the smart-client and unencrypted traffic.

    http://10.1.83.51:9020?identity=<access-key>&secretKey=<secret-key>
  

• A standard S3 client config URI for a 3-VDC deployment using encrypted traffic and geo-pinning.

    https://10.1.100.11:9021?vdcs=10.1.100.11,10.1.100.12&vdcs=10.2.100.11,10.2.100.12&vdcs=10.3.100.11,10.3.100.12&geoPinningEnabled=true&geoReadRetryFailover=true&identity=<access-key>&secretKey=<secret-key>
  

The ECS S3 client config URI has the following available parameters.

• checksumEnabled - true or false, defaults to true.
• chunkedEncodingSize - integer number of bytes, defaults to 2MB.
• faultInjectionRate - long integer, defaults to 0.0f (no fault injection).
• geoPinningEnabled - true or false, defaults to false.
• geoReadRetryFailover - true or false, defaults to false.
• identity - any string, no default.
• initialRetryDelay - integer number of milliseconds, defaults to 1000.
• namespace - any string, no default.
• port - integer, defaults to 9020 for HTTP and 9021 for HTTPS protocols, -1 otherwise. Must be specified following URI syntax, not in the query.
• protocol - HTTP or HTTPS, case insensitive. Must be specified following URI syntax, not in the query.
• retryBufferSize - integer number of bytes, defaults to 2MB.
• retryEnabled - true or false, defaults to true.
• retryLimit - integer, defaults to 3.
• rootContext - any string. Must be set following URI syntax (as the path), not in the query.
• secretKey - any string, no default.
• serverClockSkew - long integer number of milliseconds, defaults to 0.
• signMetadataSearch - true or false, defaults to true.
• signNamespace - true or false, defaults to true.
• smartClient - true or false, defaults to true.
• userAgent - any string, defaults to ECS Java SDK plus version numbers and operating system information.
• useVHost - true or false (default false).
• vdcs - each instance is a single vdc, represented as a comma-separated list of hosts, with the first used as the name. Multiple instances are allowed. NOTE: You can also specify a single host in the URI, before the query, and that will be used as a single one-node VDC if no vdcs are specified in the query.
• Custom config properties - passed to the HTTP client implementation, set in the query as properties.<name>=<value>. Example: to set Jersey's socket connect timeout to 50 secs: properties.com.sun.jersey.client.property.connectTimeout=50000.