Initialization

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.

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();