# jcoss-client-java-sdk

**Repository Path**: jiachengnet/jcoss-client-java-sdk

## Basic Information

- **Project Name**: jcoss-client-java-sdk
- **Description**: jcoss-client-java-sdk 是嘉诚分布式对象存储系统提供的客户端JAVA SDK，使用户能够以应用程序的方式访问对象存储系统。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2021-07-22
- **Last Updated**: 2022-02-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JCOSS Client JAVA SDK

## 介绍
JCOSS Client JAVA SDK 是嘉诚分布式对象存储系统提供的客户端JAVA SDK，使用户能够以应用程序的方式访问对象存储系统。


## SDK快速入门

本文介绍如何快速使用JCOSS Java SDK完成常见操作，如创建存储桶（Bucket）、上传文件（Object）、下载文件（Object）等。

环境要求
- Java 1.8
- Maven3

### 示例工程

JCOSS Java SDK提供了基于Maven的示例工程。您可以在本地设备上编译和运行示例工程，或者以示例工程为基础开发您的应用。

- [从gitee上下载maven示例工程](https://gitee.com/jiachengnet/jcoss-client-java-sdk-example)


### 安装SDK

本文基于 jdk1.8.0_144 版本编写。

对于在嘉诚公司内部部署的对象存储系统和客户自行安装的对象存储系统分别通过以下方式安装SDK：

- 嘉诚公司内部的对象存储系统使用如下方式安装SDK：

在Maven工程中使用JCOSS Java SDK，只需在pom.xml中加入相应依赖即可。以21.07.02-alpha版本为例，在pom文件中加入如下内容：

```xml
<dependencies>
    <dependency>
        <groupId>com.jc.bdp</groupId>
        <artifactId>jcoss-client-java-sdk</artifactId>
        <version>v21.07.02-alpha</version>
    </dependency>
    <dependency>
        <groupId>org.yaml</groupId>
        <artifactId>snakeyaml</artifactId>
        <version>1.17</version>
    </dependency>
    <dependency>
        <groupId>commons-lang</groupId>
        <artifactId>commons-lang</artifactId>
        <version>2.6</version>
    </dependency>
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-java-sdk-s3</artifactId>
        <version>1.12.13</version>
    </dependency>
    <dependency>
        <groupId>org.apache.tika</groupId>
        <artifactId>tika-core</artifactId>
        <version>1.18</version>
    </dependency>
</dependencies>
```

- 客户自行安装部署的对象存储系统使用如下方式安装SDK：

1. 从gitee克隆SDK源码

```java
git clone https://gitee.com/jiachengnet/jcoss-client-java-sdk.git
```

2. 使用IntelliJ IDEA 编译源码，生成jcoss-client-java-sdk.jar

3. 在IntelliJ IDEA中选择您的工程，右键选择File > Project Structure > Modules > Dependencies > + > JARs or directories，根据提示选择jcoss-client-java-sdk.jar即可



### 初始化

JCOSSClient是JCOSS的客户端，用于管理存储桶和对象等JCOSS资源。使用Java SDK发起JCOSS请求前，您需要在application.yml文件中完成配置项并初始化一个JCOSSClient实例。

秘钥获取请参考[如何获取秘钥](#如何获取秘钥)。

通过配置文件方式配置并初始化一个JCOSSClient实例

> 说明：    
> JCOSSClient初始化时会默认创建一个以accessKey为名称的存储桶，也可以在上传对象前指定上传到哪个存储桶（上传对象前需先创建存储桶）

1. JCOSSClient配置   
新建一个application.yml文件，将以下内容加入application.yml文件中并修改为您的endpoint、accesskey、secretkey所对应的配置信息

```yml
jcoss:
  endpoint: <JCOSS网关地址>
  accesskey: <yourAccessKey>
  secretkey: <yourSecretKey>
```

2. 初始化一个JCOSSClient实例  

```java
JCOSSClient jcossClient = JCOSS.buildClient();
```

### 如何获取秘钥

由对象存储系统管理员创建租户并分配秘钥，创建命令如下：
1. SSH登录到主控机，执行如下命令进入客户端，集群ID可从安装报告中获取；

```bash
cephadm shell --fsid <集群ID>
```

2. 执行如下命令创建租户；从返回的JSON中可以获取到 asscessKey 和 secretKey；

```bash
radosgw-admin user create --tenant 租户标识 --uid 用户ID --display-name 显示的用户名称
```

> 说明：本示例中的租户标识为tenanta，用户ID为test   

返回的JSON

```json
{
    "user_id": "tenanta$test",
    "display_name": "test",
    "email": "",
    "suspended": 0,
    "max_buckets": 1000,
    "subusers": [],
    "keys": [
        {
            "user": "tenanta$test",
            "access_key": "N9DAMR4RI4WWUQD4H0S3",
            "secret_key": "bfOvAy9ia4oHy3USSzk40ObxCAYRsy5VmKWQ2RZA"
        }
    ],
    ...
}
```



### 创建存储桶

存储桶是JCOSS的全局命名空间，相当于对象的容器，可以存储若干对象。对象必须隶属于某个存储桶，在上传对象之前必须创建存储桶。以下代码用于创建存储桶：

```java
// 创建一个JCOSSClient对象实例
JcossClient jcossClient = Jcoss.buildClient();

// 创建存储桶                
Bucket bucket = jcossClient.createBucket(testBucketName);

// 关闭JcossClient并释放资源
jcossClient.shutdown();
```

### 上传对象

上传对象前，您可以自定义文件元信息，也可以通过进度条功能查看上传进度。
如何查看上传进度请参考[SDK使用手册-上传对象-进度条](SDK使用手册.html#进度条)

```java
// 创建一个JCOSSClient对象实例
JcossClient jcossClient = Jcoss.buildClient();

// 待上传的文件，包含文件后缀在内的完整路径，例如d:\\abc\\efg\\mypic.jpg               
File file = new File("d:\\abc\\efg\\mypic.jpg");

// 设置对象元信息
// 创建对象元数据实例
ObjectMetadata objectMetadata = new ObjectMetadata();
// 设置对象名称，用于下载时自动生成文件名，为必须参数
objectMetadata.addUserMetadata(ObjectEnum.NAME.name(),"mypic.jpg");
// 设置内容长度，为必须参数
objectMetadata.setContentLength(file.length());
// 设置内容类型，如果不设置，默认为application/octect-stream，非必须参数
objectMetadata.setContentType("image/jpeg");

// 开始上传
UploadObjectResult uploadResult = jcossClient.putObject(bucketName, file, objectMetadata);

// 关闭JcossClient并释放资源
jcossClient.shutdown();
```

> 说明：    
> JCOSSClient 在初始化时默认创建了一个存储桶，存储桶名称为accessKey。      
> 使用默认的存储桶请参考 putObject(File file, ObjectMetadata objectMetadata) 方法。


### 下载对象

```java
// 创建一个JCOSSClient对象实例
JcossClient jcossClient = Jcoss.buildClient();

// 存储桶名称
String bucketName = "mybucket";
// 对象的key，由上传对象后生成
String objectKey = "";
// 包含文件后缀在内的完整路径，例如d:\\abc\\efg\\mypic.jpg
String downloadFile = "d:\\abc\\efg\\mypic.jpg";

// 开始下载
jcossClient.getObject(bucketName, objectKey, downloadFile);

// 关闭JcossClient并释放资源
jcossClient.shutdown();
```