Skip to content

Commit

Permalink
Docs and examples added for Object Lock (#800)
Browse files Browse the repository at this point in the history
  • Loading branch information
@sinhaashish @kannappanr
sinhaashish authored and kannappanr committed Oct 8, 2019
1 parent 4aa5765 commit 5c28a02
Show file tree
Hide file tree
Showing 4 changed files with 387 additions and 10 deletions.
14 changes: 4 additions & 10 deletions api/src/main/java/io/minio/MinioClient.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3513,8 +3513,6 @@ public void makeBucket(String bucketName, String region, boolean objectLock)
* @param bucketName Bucket name.
*
* @throws InvalidBucketNameException upon invalid bucket name is given
* @throws RegionConflictException upon passed region conflicts with the one
* previously specified.
* @throws NoSuchAlgorithmException
* upon requested algorithm was not found during signature calculation
* @throws IOException upon connection error
Expand All @@ -3529,7 +3527,7 @@ public void makeBucket(String bucketName, String region, boolean objectLock)
* @throws InvalidResponseException upon a non-xml response from serve
*/
public void enableVersioning(String bucketName)
throws InvalidBucketNameException, RegionConflictException, NoSuchAlgorithmException, InsufficientDataException,
throws InvalidBucketNameException, NoSuchAlgorithmException, InsufficientDataException,
IOException, InvalidKeyException, NoResponseException, XmlPullParserException, ErrorResponseException,
InternalException, InvalidResponseException {
Map<String, String> queryParamMap = new HashMap<>();
Expand All @@ -3551,8 +3549,6 @@ public void enableVersioning(String bucketName)
* @param bucketName Bucket name.
*
* @throws InvalidBucketNameException upon invalid bucket name is given
* @throws RegionConflictException upon passed region conflicts with the one
* previously specified.
* @throws NoSuchAlgorithmException
* upon requested algorithm was not found during signature calculation
* @throws IOException upon connection error
Expand All @@ -3567,7 +3563,7 @@ public void enableVersioning(String bucketName)
* @throws InvalidResponseException upon a non-xml response from serve
*/
public void disableVersioning(String bucketName)
throws InvalidBucketNameException, RegionConflictException, NoSuchAlgorithmException, InsufficientDataException,
throws InvalidBucketNameException, NoSuchAlgorithmException, InsufficientDataException,
IOException, InvalidKeyException, NoResponseException, XmlPullParserException, ErrorResponseException,
InternalException, InvalidResponseException {
Map<String, String> queryParamMap = new HashMap<>();
Expand Down Expand Up @@ -3601,13 +3597,12 @@ public void disableVersioning(String bucketName)
* @throws XmlPullParserException upon parsing response xml
* @throws ErrorResponseException upon unsuccessful execution
* @throws InternalException upon internal library error
* @throws InvalidArgumentException upon invalid value is passed to a method.
* @throws InvalidResponseException upon a non-xml response from server
*/
public void setDefaultRetention(String bucketName, ObjectLockConfiguration config)
throws InvalidBucketNameException, NoSuchAlgorithmException, InsufficientDataException, IOException,
InvalidKeyException, NoResponseException, XmlPullParserException, ErrorResponseException,
InternalException, InvalidArgumentException, InvalidResponseException {
InternalException, InvalidResponseException {
Map<String, String> queryParamMap = new HashMap<>();
queryParamMap.put("object-lock", "");

Expand Down Expand Up @@ -3636,13 +3631,12 @@ public void setDefaultRetention(String bucketName, ObjectLockConfiguration confi
* @throws XmlPullParserException upon parsing response xml
* @throws ErrorResponseException upon unsuccessful execution
* @throws InternalException upon internal library error
* @throws InvalidArgumentException upon invalid value is passed to a method.
* @throws InvalidResponseException upon a non-xml response from server
*/
public ObjectLockConfiguration getDefaultRetention(String bucketName)
throws InvalidBucketNameException, NoSuchAlgorithmException, InsufficientDataException, IOException,
InvalidKeyException, NoResponseException, XmlPullParserException, ErrorResponseException,
InternalException, InvalidArgumentException, InvalidResponseException {
InternalException, InvalidResponseException {
Map<String, String> queryParamMap = new HashMap<>();
queryParamMap.put("object-lock", "");

Expand Down
264 changes: 264 additions & 0 deletions docs/API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ MinioClient s3Client = new MinioClient("https://s3.amazonaws.com", "YOUR-ACCESSK
| [`listenBucketNotification`](#listenBucketNotification) | | | |
| [`setBucketNotification`](#setBucketNotification) | | | |
| [`getBucketNotification`](#getBucketNotification) | | | |
| [`enableVersioning`](#enableVersioning) | | | |
| [`disableVersioning`](#disableVersioning) | | | |
| [`setDefaultRetention`](#setDefaultRetention) | | | |
| [`getDefaultRetention`](#getDefaultRetention) | | | |

## 1. Constructors

Expand Down Expand Up @@ -323,6 +327,59 @@ try {
}
```

<a name="makeBucket"></a>
### makeBucket(String bucketName, String region, boolean objectLock)
`public void makeBucket(String bucketName, String region, boolean objectLock)`

Creates a new bucket with object lock functionality enabled.

[View Javadoc](http://minio.github.io/minio-java/io/minio/MinioClient.html#makeBucket-java.lang.String-java.lang.String-boolean-)

__Parameters__

|Param | Type | Description |
|:--- |:--- |:--- |
| ``bucketName`` | _String_ | Name of the bucket. |
| ``region`` | _String_ | Region in which the bucket will be created. |
| ``objectLock`` | _bool_ | When true, enables object lock functionality |


| Return Type | Exceptions |
|:--- |:--- |
| ``None`` | Listed Exceptions: |
| | ``InvalidBucketNameException`` : upon invalid bucket name. |
| | ``RegionConflictException`` : upon passed region conflicts with the one previously specified. |
| | ``NoSuchAlgorithmException`` : upon requested algorithm was not found during signature calculation. |
| | ``InsufficientDataException`` : Thrown to indicate that reading given InputStream gets EOFException before reading given length. |
| | ``IOException`` : upon connection error. |
| | ``InvalidKeyException`` : upon an invalid access key or secret key. |
| | ``NoResponseException`` : upon no response from server. |
| | ``org.xmlpull.v1.XmlPullParserException`` : upon parsing response XML. |
| | ``ErrorResponseException`` : upon unsuccessful execution. |
| | ``InternalException`` : upon internal library error. |
| | ``InvalidResponseException`` : upon a non-xml response from server. |



__Example__


```java
try {
// Create bucket if it doesn't exist.
boolean found = minioClient.bucketExists("mybucket");
if (found) {
System.out.println("mybucket already exists");
} else {
// Create bucket 'my-bucketname' with object lock functionality enabled
minioClient.makeBucket("mybucket","us-east-1", true);
System.out.println("mybucket is created successfully with object lock functionality enabled.");
}
} catch (MinioException e) {
System.out.println("Error occurred: " + e);
}
```

<a name="listBuckets"></a>
### listBuckets()

Expand Down Expand Up @@ -951,6 +1008,213 @@ __Example__
}
```

<a name="enableVersioning"></a>
### enableVersioning(String bucketName)
`public void enableVersioning(String bucketName)`

Object versioning is enabled in bucketName.

[View Javadoc](http://minio.github.io/minio-java/io/minio/MinioClient.html#enableVersioning-java.lang.String-)

__Parameters__

|Param | Type | Description |
|:--- |:--- |:--- |
| ``bucketName`` | _String_ | Name of the bucket. |


| Return Type | Exceptions |
|:--- |:--- |
| ``None`` | Listed Exceptions: |
| | ``InvalidBucketNameException`` : upon invalid bucket name. |
| | ``NoSuchAlgorithmException`` : upon requested algorithm was not found during signature calculation. |
| | ``InsufficientDataException`` : Thrown to indicate that reading given InputStream gets EOFException before reading given length. |
| | ``IOException`` : upon connection error. |
| | ``InvalidKeyException`` : upon an invalid access key or secret key. |
| | ``NoResponseException`` : upon no response from server. |
| | ``org.xmlpull.v1.XmlPullParserException`` : upon parsing response XML. |
| | ``ErrorResponseException`` : upon unsuccessful execution. |
| | ``InternalException`` : upon internal library error. |
| | ``InvalidResponseException`` : upon a non-xml response from server. |

__Example__


```java
try {
// Object versioning is enabled in my-bucketname
minioClient.enableVersioning("my-bucketname");
System.out.println("Object versioning is enabled in my-bucketname.");
}
} catch (MinioException e) {
System.out.println("Error occurred: " + e);
}
```


<a name="disableVersioning"></a>
### disableVersioning(String bucketName)
`public void disableVersioning(String bucketName)`

Object versioning is disabled in bucketName.

[View Javadoc](http://minio.github.io/minio-java/io/minio/MinioClient.html#disableVersioning-java.lang.String-)

__Parameters__

|Param | Type | Description |
|:--- |:--- |:--- |
| ``bucketName`` | _String_ | Name of the bucket. |


| Return Type | Exceptions |
|:--- |:--- |
| ``None`` | Listed Exceptions: |
| | ``InvalidBucketNameException`` : upon invalid bucket name. |
| | ``NoSuchAlgorithmException`` : upon requested algorithm was not found during signature calculation. |
| | ``InsufficientDataException`` : Thrown to indicate that reading given InputStream gets EOFException before reading given length. |
| | ``IOException`` : upon connection error. |
| | ``InvalidKeyException`` : upon an invalid access key or secret key. |
| | ``NoResponseException`` : upon no response from server. |
| | ``org.xmlpull.v1.XmlPullParserException`` : upon parsing response XML. |
| | ``ErrorResponseException`` : upon unsuccessful execution. |
| | ``InternalException`` : upon internal library error. |
| | ``InvalidResponseException`` : upon a non-xml response from server. |

__Example__


```java
try {
// Object versioning is disabled in my-bucketname
minioClient.disableVersioning("my-bucketname");
System.out.println("Object versioning is disabled in my-bucketname.");
}
} catch (MinioException e) {
System.out.println("Error occurred: " + e);
}
```

<a name="setDefaultRetention"></a>
### setDefaultRetention(String bucketName, ObjectLockConfiguration config)
`public void setDefaultRetention(String bucketName, ObjectLockConfiguration config)`

Set default retention on bucket.

[View Javadoc](http://minio.github.io/minio-java/io/minio/MinioClient.html#setDefaultRetention-java.lang.String-io.minio.messages.ObjectLockConfiguration- )

__Parameters__

|Param | Type | Description |
|:--- |:--- |:--- |
| ``bucketName`` | _String_ | Name of the bucket. |
| ``config`` | _ObjectLockConfiguration_ | Object lock Configuration |


| Return Type | Exceptions |
|:--- |:--- |
| ``None`` | Listed Exceptions: |
| | ``InvalidBucketNameException`` : upon invalid bucket name. |
| | ``NoSuchAlgorithmException`` : upon requested algorithm was not found during signature calculation. |
| | ``InsufficientDataException`` : Thrown to indicate that reading given InputStream gets EOFException before reading given length. |
| | ``IOException`` : upon connection error. |
| | ``InvalidKeyException`` : upon an invalid access key or secret key. |
| | ``NoResponseException`` : upon no response from server. |
| | ``org.xmlpull.v1.XmlPullParserException`` : upon parsing response XML. |
| | ``ErrorResponseException`` : upon unsuccessful execution. |
| | ``InternalException`` : upon internal library error. |
| | ``InvalidResponseException`` : upon a non-xml response from server. |

__Example__


```java
try {
// Create bucket if it doesn't exist.
boolean found = s3Client.bucketExists("my-bucketname");
if (found) {
System.out.println("my-bucketname already exists");
} else {
// Create bucket 'my-bucketname' with object lock functionality enabled
s3Client.makeBucket("my-bucketname", null, true);
System.out.println("my-bucketname is created successfully with object lock functionality enabled.");
}

// Declaring config with Retention mode as Compliance and
// duration as 100 days
ObjectLockConfiguration setConfig = new ObjectLockConfiguration(RetentionMode.COMPLIANCE,100 , DurationUnit.DAYS);

// Set object lock configuration
s3Client.setDefaultRetention("my-bucketname",config);

} catch (MinioException e) {
System.out.println("Error occurred: " + e);
}
```


<a name="getDefaultRetention"></a>
### getDefaultRetention(String bucketName)
`public void getDefaultRetention(String bucketName)`

Get default retention of bucket.

[View Javadoc](http://minio.github.io/minio-java/io/minio/MinioClient.html#getDefaultRetention-java.lang.String- )

__Parameters__

|Param | Type | Description |
|:--- |:--- |:--- |
| ``bucketName`` | _String_ | Name of the bucket. |



| Return Type | Exceptions |
|:--- |:--- |
| ``None`` | Listed Exceptions: |
| | ``InvalidBucketNameException`` : upon invalid bucket name. |
| | ``NoSuchAlgorithmException`` : upon requested algorithm was not found during signature calculation. |
| | ``InsufficientDataException`` : Thrown to indicate that reading given InputStream gets EOFException before reading given length. |
| | ``IOException`` : upon connection error. |
| | ``InvalidKeyException`` : upon an invalid access key or secret key. |
| | ``NoResponseException`` : upon no response from server. |
| | ``org.xmlpull.v1.XmlPullParserException`` : upon parsing response XML. |
| | ``ErrorResponseException`` : upon unsuccessful execution. |
| | ``InternalException`` : upon internal library error. |
| | ``InvalidResponseException`` : upon a non-xml response from server. |

__Example__


```java
try {
// Create bucket if it doesn't exist.
boolean found = s3Client.bucketExists("my-bucketname");
if (found) {
System.out.println("my-bucketname already exists");
} else {
// Create bucket 'my-bucketname' with object lock functionality enabled
s3Client.makeBucket("my-bucketname", null, true);
System.out.println("my-bucketname is created successfully with object lock functionality enabled.");
}

// Declaring config with Retention mode as Compliance and
// duration as 100 days
ObjectLockConfiguration setConfig = new ObjectLockConfiguration(RetentionMode.COMPLIANCE,100 , DurationUnit.DAYS);

// Set object lock configuration
s3Client.setDefaultRetention("my-bucketname",config);

// Get object lock configuration
ObjectLockConfiguration getConfig = s3Client.getDefaultRetention("my-bucketname");

System.out.println(" Lock Configuration : " + getConfig)

} catch (MinioException e) {
System.out.println("Error occurred: " + e);
}
```



<a name="listIncompleteUploads"></a>
Expand Down
Loading

0 comments on commit 5c28a02

Please sign in to comment.