|
| 1 | +English | [中文](README.md) |
| 2 | + |
| 3 | +<h1 align="center"><img src="https://iam.volccdn.com/obj/volcengine-public/pic/volcengine-icon.png"></h1> |
| 4 | +<h1 align="center">Volcengine SDK for Java</h1> |
| 5 | + |
| 6 | +Welcome to Volcengine SDK for Java. This document explains how to obtain and use the SDK. |
| 7 | + |
| 8 | +## Prerequisites |
| 9 | + |
| 10 | +### Enable the service |
| 11 | + |
| 12 | +Make sure the service you want to access is enabled. Go to the [Volcengine Console](https://console.volcengine.com/), select the service from the left navigation (or search it from the top bar), and complete the activation process in the service console. |
| 13 | + |
| 14 | +### Obtain security credentials |
| 15 | + |
| 16 | +Access Key is the credential used to access Volcengine services. It consists of Access Key ID (AK) and Secret Access Key (SK). |
| 17 | + |
| 18 | +Log in to the [Volcengine Console](https://console.volcengine.com/), then go to [IAM](https://console.volcengine.com/iam) -> [Access Keys](https://console.volcengine.com/iam/keymanage/) to create and manage your Access Keys. For more information, see the [Access Key documentation](https://www.volcengine.com/docs/6291/65568). |
| 19 | + |
| 20 | +## Install |
| 21 | + |
| 22 | +We recommend using Maven dependencies to integrate Volcengine SDK for Java. |
| 23 | + |
| 24 | +[](https://search.maven.org/artifact/com.volcengine/volc-sdk-java) |
| 25 | + |
| 26 | +```xml |
| 27 | +<dependency> |
| 28 | + <groupId>com.volcengine</groupId> |
| 29 | + <artifactId>volc-sdk-java</artifactId> |
| 30 | + <version>latest</version> |
| 31 | +</dependency> |
| 32 | +``` |
| 33 | + |
| 34 | +If your Java version is **Java 9 or later**, add `javax.annotation-api` because it was removed from JDK 9+. |
| 35 | + |
| 36 | +```xml |
| 37 | +<dependency> |
| 38 | + <groupId>javax.annotation</groupId> |
| 39 | + <artifactId>javax.annotation-api</artifactId> |
| 40 | + <version>1.3.2</version> |
| 41 | +</dependency> |
| 42 | +``` |
| 43 | + |
| 44 | +### SNAPSHOT release notes |
| 45 | + |
| 46 | +[Version: 2.0.1-SNAPSHOT](https://oss.sonatype.org/content/repositories/snapshots/com/volcengine/volc-sdk-java) |
| 47 | + |
| 48 | +*Note: SNAPSHOT versions may have potential issues. The source branch is `2.0.0-SNAPSHOT`. If you need support, please submit a [ticket](https://console.volcengine.com/workorder/create) and select the corresponding product.* |
| 49 | + |
| 50 | +#### Changes |
| 51 | + |
| 52 | +1. Use OkHttp as the underlying HTTP component (Android compatible) |
| 53 | +2. Fix potential thread leaks when using many credentials |
| 54 | +3. Abstract some network-related models to avoid conflicts |
| 55 | +4. Business packages are mostly unaffected, so migration should be smooth |
| 56 | + |
| 57 | +How to use the SNAPSHOT version: |
| 58 | + |
| 59 | +1. Add the SNAPSHOT Maven repository (SNAPSHOT policy settings are up to you) |
| 60 | + |
| 61 | +```xml |
| 62 | +<repository> |
| 63 | + <id>snapshots-repo</id> |
| 64 | + <url>https://oss.sonatype.org/content/repositories/snapshots/</url> |
| 65 | +</repository> |
| 66 | +``` |
| 67 | + |
| 68 | +2. Add dependency |
| 69 | + |
| 70 | +```xml |
| 71 | +<dependency> |
| 72 | + <groupId>com.volcengine</groupId> |
| 73 | + <artifactId>volc-sdk-java</artifactId> |
| 74 | + <version>2.0.1-SNAPSHOT</version> |
| 75 | +</dependency> |
| 76 | +``` |
| 77 | + |
| 78 | +## Configuration |
| 79 | + |
| 80 | +### Credential configuration |
| 81 | + |
| 82 | +Volcengine SDK for Java supports the following credential loading methods. |
| 83 | + |
| 84 | +*Note: Replace `Your AK` and `Your SK` in the code with your actual AK and SK.* |
| 85 | + |
| 86 | +**Method 1**: Specify AK/SK explicitly on the client **(recommended)** |
| 87 | + |
| 88 | +```java |
| 89 | +iamService.setAccessKey("Your AK"); |
| 90 | +iamService.setSecretKey("Your SK"); |
| 91 | +``` |
| 92 | + |
| 93 | +**Method 2**: Load AK/SK from environment variables |
| 94 | + |
| 95 | +```bash |
| 96 | +VOLC_ACCESSKEY="Your AK" |
| 97 | +VOLC_SECRETKEY="Your SK" |
| 98 | +``` |
| 99 | + |
| 100 | +**Method 3**: Load AK/SK from a file under HOME |
| 101 | + |
| 102 | +Add the following content to `~/.volc/config`: |
| 103 | + |
| 104 | +```json |
| 105 | +{ |
| 106 | + "ak": "Your AK", |
| 107 | + "sk": "Your SK" |
| 108 | +} |
| 109 | +``` |
| 110 | + |
| 111 | +### Release resources |
| 112 | + |
| 113 | +After calling APIs, explicitly call `destroy()` to release daemon threads. |
| 114 | + |
| 115 | +```java |
| 116 | +iamService.destroy() |
| 117 | +``` |
| 118 | + |
| 119 | +## Other resources |
| 120 | + |
| 121 | +Examples are available under [example](./example) |
0 commit comments