Document Center
edit-icon download-icon

Initialization

Last Updated: Aug 08, 2018

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

Create OSSClient

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

Use an OSS domain to create OSSClient

Use the following code to create OSSClient with a domain assigned by OSS:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  7. // Create an OSSClient instance.
  8. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  10. // Close your OSSClient.
  11. ossClient.shutdown();

One or more OSSClients can be used for your project. In other words, OSSClients can be used simultaneously.

Use a user-defined domain (CNAME) to create OSSClient

Use the following code to create OSSClient with CNAME:

  1. String endpoint = "<yourEndpoint>";
  2. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  3. String accessKeyId = "<yourAccessKeyId>";
  4. String accessKeySecret = "<yourAccessKeySecret>";
  6. // Create a ClientConfiguration instance. Modify parameters as required.
  7. ClientConfiguration conf = new ClientConfiguration();
  8. // Set SupportCname to true.
  9. conf.setSupportCname(true);
  11. // Create an OSSClient instance.
  12. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);
  14. // Close your OSSClient.
  15. ossClient.shutdown();

Note: ossClient.listBuckets is not available when CNAME is used.

Create OSSClient for Apsara Cloud or Private Region

Use the following code to create OSSClient for Apsara Cloud or Private Region:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  7. // Create a ClientConfiguration instance. Modify parameters as required.
  8. ClientConfiguration conf = new ClientConfiguration();
  9. // Disable CNAME.
  10. conf.setSupportCname(false);
  12. // Create an OSSClient instance.
  13. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);
  15. // Close your OSSClient.
  16. ossClient.shutdown();

Use an IP address to create OSSClient

Use the following code to create OSSClient with an IP address:

  1. // In some special cases such as in Private Region, use the IP address as an endpoint. Specify the actual IP address based on your requirements.
  2. String endpoint = "http://10.10.10.10";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  7. // Create ClientConfiguration.
  8. ClientConfiguration conf = new ClientConfiguration();
  9. // Enable OSS access with the level-2 domain. Access with the level-2 domain is disabled by default. You need to configure this function for OSS Java SDK versions 2.1.2 or earlier, because IP addresses are automatically detected in versions later than OSS Java SDK 2.1.2.
  10. conf.setSLDEnabled(true);
  12. // Create an OSSClient instance.
  13. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);
  15. // Close your OSSClient.
  16. ossClient.shutdown();

Use STS to create OSSClient

Use the following code to create OSSClient with Security Token Service (STS):

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. String securityToken = "<yourSecurityToken>";
  8. // Create an OSSClient instance.
  9. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, securityToken);
  11. // Close your OSSClient.
  12. ossClient.shutdown();

For more information, see What is RAM and STS and Authorized access.

Configure OSSClient

Use the following code to configure parameters for OSSClient with ClientConfiguration:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  7. // Create ClientConfiguration. ClientConfiguration is a configuration class of OSSClient. ClientConfiguration is used to configure parameters such as user agents, host proxies, connection timeout, and maximum connections.
  8. ClientConfiguration conf = new ClientConfiguration();
  10. // Configure the maximum HTTP connections allowed by OSSClient. The default value is 1024.
  11. conf.setMaxConnections(200);
  12. // Configure the timeout time (milliseconds) of data transmission for Secure Socket Layer (SSL). The default value is 50,000.
  13. conf.setSocketTimeout(10000);
  14. // Configure the timeout time (milliseconds) for establishing connections. The default value is 50,000.
  15. conf.setConnectionTimeout(10000);
  16. // Configure the timeout time (milliseconds) for retrieving connections from the connection pool. This function is disabled by default.
  17. conf.setConnectionRequestTimeout(1000);
  18. // Configure idle connection timeout. If the idle connection time (milliseconds) exceeds the specified value, the connection is closed. The default value is 60,000.
  19. conf.setIdleConnectionTime(10000);
  20. // Configure the maximum number of retry attempts in the case of a request error. The default value is 3.
  21. conf.setMaxErrorRetry(5);
  22. // Check whether CNAME can be used as an endpoint. By default, CNAME can be used by an endpoint.
  23. conf.setSupportCname(true);
  24. // Check whether level-2 domain access is enabled. Level-2 domain access is disabled by default.
  25. conf.setSLDEnabled(true);
  26. // Configure the protocol (HTTP or HTTPS) used to connect to OSS. HTTP is used by default.
  27. conf.setProtocol(Protocol.HTTP);
  28. // Configure the user agent (User-Agent in the HTTP header). The default value is aliyun-sdk-java.
  29. conf.setUserAgent("aliyun-sdk-java");
  30. // Configure the port for the proxy host.
  31. conf.setProxyHost("<yourProxyHost>");
  32. // Configure the username for proxy host verification.
  33. conf.setProxyUsername("<yourProxyUserName>");
  34. // Configure the password for proxy host verification.
  35. conf.setProxyPassword("<yourProxyPassword>");
  37. // Create an OSSClient instance.
  38. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret, conf);
  40. // Close your OSSClient.
  41. ossClient.shutdown();

For more information, see Alibaba Cloud OSS Java SDK Timeout Configurations.

Thank you! We've received your feedback.
Free Trial Free Trial