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 an 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:

  // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
  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 your RAM user, log on to https://ram.console.aliyun.com.
  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 your RAM user, log on to https://ram.console.aliyun.com.
  String accessKeyId = "<yourAccessKeyId>";
  String accessKeySecret = "<yourAccessKeySecret>";
  
  // Create a ClientConfiguration instance and modify the default parameters based on your requirements.
  ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
  // Enable CNAME. 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 not available 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:

  // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
  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 your RAM user, log on to https://ram.console.aliyun.com.
  String accessKeyId = "<yourAccessKeyId>";
  String accessKeySecret = "<yourAccessKeySecret>";
  
  // Create a ClientConfiguration instance and modify the default parameters based on your requirements.
  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 based on your requirements.
  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 your RAM user, log on to https://ram.console.aliyun.com.
  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 Java SDK versions 2.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):

  // This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
  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 your RAM user, log on to https://ram.console.aliyun.com.
  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 What are RAM and STS and 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 timeouts, 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 with ClientConfiguration:

// This example uses the endpoint of the China (Hangzhou) region. Specify the actual endpoint based on your requirements.
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 your RAM user, log on to https://ram.console.aliyun.com.
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 by 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 parameter is not configured.
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>");

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

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