Docs

Torch Object Storage

Java

Initialize the client (Java SDK)

TosClient provides a set of interfaces to interact with TOS services, managing resources such as buckets and objects on TOS. TosClient can be initialized using AccessKey/SecretKey, STS (Security Token Service), and other methods. During initialization, you can set optional parameters such as connection timeout, retry attempts on timeout, and maximum idle connections. This article explains how to initialize the TOS Java SDK.

Prerequisites

Install the SDK

Obtain AKSK information

Configure long-term access credentials

Before initializing the SDK, configure the long-term access credentials first. This chapter explains the steps to configure long-term access credentials on different operating systems.

macOS

Linux

Windows

Open the terminal and run the following command to open the file.

Add AKSK information at the end of the file.

Save the file and exit.

Run the following command to apply the configuration.

Run the following command to verify the configuration.

If the configuration succeeds, the following example will be returned:

Create TosClient

Initialize with required parameters

The following code shows how to initialize TosClient using required parameters such as the TOS domain name, including AccessKey, SecretKey, Endpoint, and Region.

tip

Endpoint is the publicly accessible domain name for TOS. For the supported Endpoint information in TOS, see Access domain Endpoint.

AKSK information can be obtained from environment variables. For configuration, see Configure access credentials.

Initialize with optional parameters

The TOS Java SDK provides several optional parameters for custom configuration of TosClient, such as configuring STS, HTTP request timeouts, and retry policies. The following code shows how to customize the HTTP connection timeout for TosClient. For specific configuration scenarios, see Configure timeout mechanisms.

Common configuration scenarios

Configure STS

You can issue temporary access credentials to other users via the STS service. During the credential validity period, users can access your TOS resources without exposing your long-term keys, ensuring the security of your TOS resources.

tip

You can obtain temporary access credentials through the AssumeRole interface of the STS service. These credentials include security keys (AccessKeyId, SecretAccessKey) and a security token (SessionToken). You can then use this information to access TOS services. For basic operations on setting up the STS service, refer to Using STS temporary AK/SK+Token to access Volcano Engine TOS.

The following code shows how to initialize TosClient using STS.

Configure timeout mechanisms

You can configure the network request timeout by adding optional parameters when initializing TosClient. The current TOS Java SDK provides the following timeout parameters for configuring HTTP request timeouts:

readTimeoutMills: HTTP read request timeout in milliseconds, default is 30000, which is 30 seconds.

writeTimeoutMills: HTTP write request timeout in milliseconds, default is 30000, which equals 30 seconds.

connectTimeoutMills: HTTP connection timeout in milliseconds, default is 10000, which equals 10 seconds.

The following code demonstrates how to configure timeout settings when initializing TosClient.

Configure retry strategy

Network fluctuations or short-term TOS service failures (returning HTTP 500 status code) may cause requests to the TOS service to fail. To address this, the Java SDK includes an internal retry mechanism. Idempotent interface operations use an exponential backoff strategy to retry on failure, while non-idempotent interfaces throw the corresponding exception immediately. You can add optional parameters to configure the number of retries when initializing TosClient.

Retry scenarios

The following SDK interfaces retry when the client request times out or the server returns 5xx or 429 errors.

All GET/HEAD type interfaces, such as getObject, headObject, headBucket.

Some PUT/DELETE type interfaces, such as putObjectACL, deleteObject.

For putObject/uploadPart interfaces, if the uploaded content (InputStream type) supports markSupported(), it is considered idempotent. For example, if content is a string, local file, or memory array ByteArrayInputStream.

putObjectFromFile/uploadPartFromFile/setObjectMeta interfaces.

Except for appendObject, all POST type HTTP interfaces retry only when the server returns 5xx or 429 errors; client timeout does not trigger retries.

tip

getObject does not retry if a read exception occurs after returning the data stream to download, such as java.io.IOException: unexpected end of stream.

Retry strategy

The Java SDK performs exponential backoff retries based on the set retry count, with a default of 3 retries.

Example code

The following code shows how to set the SDK retry count.

Configure data validation

During object upload and download, the TOS server returns the object's CRC value. The SDK also calculates the object's CRC value and verifies whether it matches the CRC value returned by the TOS server, thus checking the integrity of the uploaded and downloaded data. To ensure data integrity during upload and download, the SDK enables CRC data validation by default. You can add an optional parameter to disable CRC validation when initializing TosClient.

danger

It is strongly recommended not to disable CRC data validation. If this feature is disabled, TOS does not guarantee data integrity during upload and download.

Configure DNS cache

The TOS service domain name may experience delays or unresolvable issues in public network environments. The Java SDK addresses this issue by providing a DNS cache mechanism that caches the IP addresses resolved from domain names within the SDK, avoiding DNS resolution for every request.

The SDK's DNS cache mechanism is disabled by default. The following code demonstrates how to configure DNS cache time, with the default unit in minutes.

Configure proxy server

The TOS Java SDK supports accessing TOS services by configuring a proxy server. You can add optional parameters to configure the proxy server when initializing TosClient.

The following code demonstrates how to configure a proxy server.

Configure connection pool

The Java SDK provides the following parameters for configuring the SDK HTTP connection pool.

idleConnectionTimeMills: the idle time for connections in the HTTP connection pool. Connections exceeding this time are closed. The unit is milliseconds, with a default value of 60000, which equals 60 seconds.

maxConnections: the maximum number of connections in the HTTP connection pool. The default value is 1024.

The following code demonstrates how to set the above parameters.

Configure User-Agent Extension Information (V2.8.1)

TOS Java SDK supports customers configuring custom business information into the User-Agent. You can add optional parameters to configure User-Agent extension information when initializing TosClient.

User-Agent extension information specifications are as follows:

The following code shows how to configure User-Agent extension information.

Associating a custom domain

TOS Java SDK supports setting custom domains. You can pass a custom domain as the Host when initializing TosClient. After specifying a custom domain, there is no need to pass Bucket in SDK interfaces.

tip

You need to configure the custom domain on the server before using a custom domain. For details, see Associating a custom domain.

In the SDK, you can use isCustomDomain to mark the current domain as a custom domain.

initialize parameter list

Parameter	Type	Required	Example value	Note
accessKey	String	Yes	AKTPYmI1Z****	Access Key ID, the key ID, default is null.
secretKey	String	Yes	T1dJM01UU****	SecretAccess Key, the private access key, default is null.
endpoint	String	No, defaults to region parameter when empty	tos-cn-beijing.volces.com	access domain name, default is null.
region	String	Yes	cn-beijing	TOS server region, default is null.
securityToken	String	No	STSkeyJBY2NvdW50SW************	security token in temporary access credentials, default is null.
writeTimeoutMills	int	No	30000	HTTP write request timeout, in milliseconds, default value is 30000.
connectTimeoutMills	int	No	10000	connection timeout in milliseconds, default is 10000.
idleConnectionTimeMills	int	No	60000	If idle HTTP connection time in the connection pool exceeds this value, the HTTP connection will be closed. Unit: milliseconds. Default value is 60000.
maxConnections	int	No	1024	maximum number of HTTP connection pool connections, default is 1024.
maxRetryCount	int	No	3	maximum retry attempts on request failure, default is 3.
dnsCacheTimeMinutes	int	No	0	DNS cache validity period in minutes. A value less than or equal to 0 disables DNS caching. The default value is 0.
proxyHost	String	no	"localhost"	Host address of the proxy server; only HTTP protocol is supported currently, default value is null.
proxyPort	int	No	8080	Proxy server port number, default value is 0.
proxyUserName	String	No	"Alice"	Username for connecting to the proxy server, default value is null.
proxyPassword	String	No	"pwd123"	User password for connecting to the proxy server, default is null.
enableVerifySSL	boolean	no	true	Enable SSL certificate verification, default is true.
enableCrc	boolean	No	true	Enable CRC check, default is true.
clientAutoRecognizeContentType	boolean	No	true	Enable Content-Type recognition based on object name extension; the default value is true.
isCustomDomain	boolean	No	false	Whether to append the bucket name before the Endpoint to access TOS via virtual host domain. The options are as follows: true: do not concatenate. false: concatenate. The default value is false. tip When accessing TOS via a custom domain, set isCustomDomain to true.

Last updated: 2025.09.29 10:29:02