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 log on with the AccessKey pair of an Alibaba Cloud account 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 log on with the AccessKey pair of an Alibaba Cloud account 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. CNAME is used to bind the custom domain name to the 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 log on with the AccessKey pair of an Alibaba Cloud account 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 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 scenarios such as a private region, an IP address is used as the endpoint. In such scenarios, specify the actual IP address based on your requirements.
  String endpoint = "https://10.10.10.10";
  // Security risks may arise if you log on with the AccessKey pair of an Alibaba Cloud account 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 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 log on with the AccessKey pair of an Alibaba Cloud account 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 Authorized access.

• Create an OSSClient instance by using STSAssumeRole

  The following code provides an example on how to use STSAssumeRole to create an OSSClient:

  // Specify the region that STSAssumeRole can access. The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
  String region = "cn-hangzhou";
  // Specify the AccessKey ID and AccessKey secret of the RAM user.
  String accessKeyId = "<yourAccessKeyId>";
  String accessKeySecret = "<yourAccessKeySecret>";
  // Specify the ARN of STSAssumeRole, which indicates the ID of the role.
  String roleArn = "<yourRoleArn>";   
  // Create an STSAssumeRoleSessionCredentialsProvider instance.
  STSAssumeRoleSessionCredentialsProvider provider = CredentialsProviderFactory.newSTSAssumeRoleSessionCredentialsProvider(
  region, accessKeyId, accessKeySecret, roleArn);
  
  // Use STSAssumeRole to access the endpoint of OSS. The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
  String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";  
  // Create a ClientConfiguration instance.
  ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
  
   
  // Create an OSSClient instance.
  OSS ossClient = new OSSClientBuilder().build(endpoint, provider, conf);
  
  // Shut down the OSSClient instance.
  ossClient.shutdown();

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

• Create an OSSClient instance by using EcsRamRole

  You can access OSS from an ECS instance by using a RAM role bound to the instance. You can bind a RAM role to an ECS instance to access OSS from the instance by using STS temporary credentials. STS temporary credentials are automatically generated and updated. Applications can obtain the STS temporary credentials by using the instance metadata URL.

  The following code provides an example on how to use EcsRamRole to create an OSSClient:

  // Use the EcsRamRole role to access OSS.
  // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
  String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";     
  
  // Use EcsRamRole to obtain the access credential. The following code shows how to obtain the access credential by using a role named ecs-ram-role.
  InstanceProfileCredentialsProvider provider = CredentialsProviderFactory.newInstanceProfileCredentialsProvider("ecs-ram-role");
  
  // Create an OSSClient instance.
   OSS ossClient = new OSSClientBuilder().build(endpoint, provider, new ClientBuilderConfiguration());
  
  // Shut down the OSSClient instance.
  ossClient.shutdown(); 

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 of this operation.

The following code provides an example on how to configure parameters for an OSSClient instance with 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 log on with the AccessKey pair of an Alibaba Cloud account 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 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 connection 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. Unit: milliseconds. Default value: 60000.
conf.setIdleConnectionTime(10000);
// Configure the maximum number of allowed retry attempts when a request error occurs. 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 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();