OSSClient serves as the Java client to manage OSS resources such as buckets and objects. To use OSS SDK for Java to initiate a request, you must initialize an OSSClient instance and modify the default configuration items of ClientConfiguration.

Create an OSSClient instance

To create an OSSClient instance, you must specify an endpoint. For more information about endpoints, see Regions and endpoints and Bind a custom domain name.

  • Create the OSSClient instance based on an OSS endpoint

    The following code provides an example on how to create an OSSClient instance based on an OSS endpoint:

    // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
    String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
    
    // Shut down the OSSClient instance.
    ossClient.shutdown();
                        

    You can use one or more OSSClient instances for your project. In other words, you can use multiple OSSClient instances simultaneously.

  • Create an OSSClient instance based on a custom domain name

    The following code provides an example on how to create an OSSClient instance based on a custom domain name:

    String endpoint = "<yourEndpoint>";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create a ClientConfiguration instance and modify the default parameters.
    ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
    // Configure whether CNAME is enabled. If CNAME is enabled, a custom domain name can be bound to a bucket.
    conf.setSupportCname(true);
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);
    
    // Shut down the OSSClient instance.
    ossClient.shutdown();
                        
    Note ossClient.listBuckets is unavailable when a custom domain name is used.
  • Create an OSSClient instance based on Apsara Stack or a private region

    The following code provides an example on how to create an OSSClient instance based on Apsara Stack or a private region:

    // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
    String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create a ClientConfiguration instance and modify the default parameters.
    ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
    // Disable CNAME.
    conf.setSupportCname(false);
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);
    
    // Shut down the OSSClient instance.
    ossClient.shutdown();
                        
  • Create an OSSClient instance based on an IP address

    The following code provides an example on how to create an OSSClient instance based on an IP address:

    // In some special cases, such as a private region, the IP address is used as the endpoint. In such cases, specify the actual IP address.
    String endpoint = "http://10.10.10.10";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    
    // Create a ClientConfiguration instance.
    ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
    // By default, access from a second-level domain is disabled. Enable OSS access from a second-level domain. You must configure this parameter for OSS SDK for Java V2.1.2 or earlier, because versions later than 2.1.2 automatically detect IP addresses.
    conf.setSLDEnabled(true);
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);
    
    // Shut down the OSSClient instance.
    ossClient.shutdown();
                        
  • Create an OSSClient instance based on STS

    The following code provides an example on how to create an OSSClient instance based on Security Token Service (STS):

    // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
    String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
    String accessKeyId = "<yourAccessKeyId>";
    String accessKeySecret = "<yourAccessKeySecret>";
    String securityToken = "<yourSecurityToken>";
    
    // Create an OSSClient instance.
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, securityToken);
    
    // Shut down the OSSClient instance.
    ossClient.shutdown();
                        

For more information, see Access OSS with a temporary access credential provided by STSand Authorized access.

Configure an OSSClient instance

ClientConfiguration is a configuration class of OSSClient. You can use ClientConfiguration to configure parameters such as host proxies, connection timeout periods, and the maximum number of connections. The following table describes the parameters.

Parameter Description Configuration method
MaxConnections The maximum number of HTTP connections that are allowed. Default value: 1024. ClientConfiguration.setMaxConnections
SocketTimeout The timeout period for data transmission at the socket layer. Unit: milliseconds. Default value: 50000. ClientConfiguration.setSocketTimeout
ConnectionTimeout The timeout period to establish a connection. Unit: milliseconds. Default value: 50000. ClientConfiguration.setConnectionTimeout
ConnectionRequestTimeout The timeout period to obtain a connection from the connection pool. Unit: milliseconds. By default, this operation never times out. ClientConfiguration.setConnectionRequestTimeout
IdleConnectionTime The timeout period for idle connections. The connection is closed when the timeout period ends. Default value: 60000. ClientConfiguration.setIdleConnectionTime
MaxErrorRetry The maximum number of allowed retry attempts in the case of a request error. Default value: 3. ClientConfiguration.setMaxErrorRetry
SupportCname Specifies whether CNAME can be used as an endpoint. By default, CNAME can be used as an endpoint. ClientConfiguration.setSupportCname
SLDEnabled Specifies whether access from second-level domains is enabled. By default, access from second-level domains is disabled. ClientConfiguration.setSLDEnabled
Protocol The protocol used to connect to OSS. Valid values: HTTP and HTTPS. Default value: HTTP. ClientConfiguration.setProtocol
UserAgent The user agent (the User-Agent field in the HTTP header). Default value: aliyun-sdk-java. ClientConfiguration.setUserAgent
ProxyHost The IP address to access the proxy host. ClientConfiguration.setProxyHost
ProxyPort The port for the proxy host. ClientConfiguration.setProxyPort
ProxyUsername The username verified by the proxy host. ClientConfiguration.setProxyUsername
ProxyPassword The password verified by the proxy host. ClientConfiguration.setProxyPassword
RedirectEnable Specifies whether HTTP redirection is enabled.
Note You can configure whether HTTP redirection is enabled for OSS SDK for Java V3.10.1 or later. By default, HTTP redirection is enabled for OSS SDK for Java V3.10.1 or later.
ClientConfiguration.setRedirectEnable
VerifySSLEnable Specifies whether SSL-based authentication is enabled.
Note You can configure whether SSL-based authentication or later is enabled for OSS SDK for Java V3.10.1. By default, SSL-based authentication is enabled for OSS SDK for Java V3.10.1 or later.
ClientConfiguration.setVerifySSLEnable

The following code provides an example on how to configure parameters for an OSSClient instance by using ClientConfiguration:

// The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";

// Create a ClientConfiguration instance. ClientConfiguration is a configuration class of OSSClient. You can use ClientConfiguration to configure parameters such as host proxies, connection timeouts, and the maximum number of connections.
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();

// Configure the maximum number of HTTP connections allowed for an OSSClient instance. Default value: 1024.
conf.setMaxConnections(200);
// Configure the timeout period for data transmission at the socket layer. Unit: milliseconds. Default value: 50000.
conf.setSocketTimeout(10000);
// Configure the timeout period for establishing a connection. Unit: milliseconds. Default value: 50000.
conf.setConnectionTimeout(10000);
// Configure the timeout period for obtaining a connection from the connections pool. Unit: milliseconds. By default, this operation never times out.
conf.setConnectionRequestTimeout(1000);
// Configure the timeout period for idle connections. The connection is closed when the timeout period expires. Default value: 60000.
conf.setIdleConnectionTime(10000);
// Configure the maximum number of allowed retry attempts in the case of a request error. Default value: 3.
conf.setMaxErrorRetry(5);
// Configure whether CNAME can be used as an endpoint. By default, CNAME can be used as an endpoint.
conf.setSupportCname(true);
// Configure whether access from second-level domains is enabled. By default, access from second-level domains is disabled.
conf.setSLDEnabled(true);
// Configure the protocol used to connect to OSS. Valid values: HTTP and HTTPS. Default value: HTTP.
conf.setProtocol(Protocol.HTTP);
// Configure the user agent (the User-Agent field in the HTTP header). Default value: aliyun-sdk-java.
conf.setUserAgent("aliyun-sdk-java");
// Configure the port for the proxy host.
conf.setProxyHost("<yourProxyHost>");
// Configure the username verified by the proxy host.
conf.setProxyUsername("<yourProxyUserName>");
// Configure the password verified by the proxy host.
conf.setProxyPassword("<yourProxyPassword>");
// Configure whether HTTP redirection is enabled. By default, HTTP redirection is enabled.
conf.setRedirectEnable(true);
// Configure whether SSL-based authentication is enabled. By default, SSL-based authentication is enabled.
conf.setVerifySSLEnable(true);

// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);

// Shut down the OSSClient instance.
ossClient.shutdown();