Skip to content

Commit

Permalink
Issue #428: update api and readme doc, including examples (#429)
Browse files Browse the repository at this point in the history
  • Loading branch information
nl5887 authored and harshavardhana committed Jul 24, 2016
1 parent a51f8e2 commit fecd1f9
Show file tree
Hide file tree
Showing 4 changed files with 198 additions and 0 deletions.
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,8 @@ The full API Reference is available here.
* [`removeBucket`](https://docs.minio.io/docs/java-client-api-reference#removeBucket)
* [`listObjects`](https://docs.minio.io/docs/java-client-api-reference#listObjects)
* [`listIncompleteUploads`](https://docs.minio.io/docs/java-client-api-reference#listIncompleteUploads)
* [`getBucketPolicy`](https://docs.minio.io/docs/java-client-api-reference#getBucketPolicy)
* [`setBucketPolicy`](https://docs.minio.io/docs/java-client-api-reference#setBucketPolicy)

### API Reference : Object Operations

Expand Down Expand Up @@ -163,6 +165,8 @@ The full API Reference is available here.

* [PutObject.java](https://github.com/minio/minio-java/tree/master/examples/PutObject.java)
* [GetObject.Java](https://github.com/minio/minio-java/tree/master/examples/GetObject.java)
* [PutBucketPolicy.java](https://github.com/minio/minio-java/tree/master/examples/PutBucketPolicy.java)
* [GetBucketPolicy.Java](https://github.com/minio/minio-java/tree/master/examples/GetBucketPolicy.java)
* [GetPartialObject.java](https://github.com/minio/minio-java/tree/master/examples/GetPartialObject.java)
* [RemoveObject.java](https://github.com/minio/minio-java/tree/master/examples/RemoveObject.java)
* [StatObject.java](https://github.com/minio/minio-java/tree/master/examples/StatObject.java)
Expand Down
111 changes: 111 additions & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ MinioClient s3Client = new MinioClient("https://s3.amazonaws.com", "YOUR-ACCESSK
| [`removeBucket`](#removeBucket) | [`removeObject`](#removeObject) | |
| [`listObjects`](#listObjects) | [`removeIncompleteUpload`](#removeIncompleteUpload) | |
|[`listIncompleteUploads`](#listIncompleteUploads) | |
| [`getBucketPolicy`](#getBucketPolicy) | |
| [`setBucketPolicy`](#setBucketPolicy) | |

## 1. Constructors

Expand Down Expand Up @@ -588,6 +590,115 @@ try {

```

<a name="getBucketPolicy"></a>
### getBucketPolicy(String bucketName, String objectPrefix)
`public BucketPolicy getBucketPolicy(String bucketName, String objectPrefix)`

Get bucket policy at given objectPrefix.

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

__Parameters__

|Param | Type | Description |
|:--- |:--- |:--- |
| ``bucketName`` | *String* | Name of the bucket. |
| ``objectPrefix`` | *String* | Policy applies to objects with prefix. |

<table>
<thead>
<tr>
<th>Return Type </th>
<th>Exceptions</th>
</tr>
</thead>
<tbody>
<tr>
<td> <code>BucketPolicy</code>: The current bucket policy for given bucket and objectPrefix.
</td>
<td>
<ul>
<li><code>InvalidBucketNameException</code> : upon invalid bucket name.</li>
<li><code>InvalidObjectPrefixException</code> : upon invalid object prefix.</li>
<li> <code>NoSuchAlgorithmException</code> : upon requested algorithm was not found during signature calculation.</li>
<li> <code>InsufficientDataException</code> : Thrown to indicate that reading given InputStream gets EOFException before reading given length..</li>
<li><code>IOException : upon connection error.</li>
<li> <code>InvalidKeyException</code> : upon an invalid access key or secret key.</li>
<li> <code>NoResponseException</code> : upon no response from server.</li>
<li><code>org.xmlpull.v1.XmlPullParserException</code> : upon parsing response XML.</li>
<li><code>ErrorResponseException</code> : upon unsuccessful execution.</li>
<li><code>InternalException</code> : upon internal library error.</li>
</ul>
</td>
</tr>
</tbody>
</table>

__Example__

```java
try {
System.out.println("Current policy: " + minioClient.getBucketPolicy("myBucket", "downloads"));
} catch (MinioException e) {
System.out.println("Error occured: " + e);
}
```

<a name="setBucketPolicy"></a>
### setBucketPolicy(String bucketName, String objectPrefix, BucketPolicy bucketPolicy)
`public void setBucketPolicy(String bucketName, String objectPrefix, BucketPolicy bucketPolicy)`

Set policy on bucket and object prefix.

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

__Parameters__

|Param | Type | Description |
|:--- |:--- |:--- |
| ``bucketName`` | *String* | Name of the bucket. |
| ``objectPrefix`` | *String* | Policy applies to objects with prefix. |
| ``bucketPolicy`` | *BucketPolicy* | Policy to apply. |

<table>
<thead>
<tr>
<th>Return Type </th>
<th>Exceptions</th>
</tr>
</thead>
<tbody>
<tr>
<td> None
</td>
<td>
<ul>
<li><code>InvalidBucketNameException</code> : upon invalid bucket name.</li>
<li><code>InvalidObjectPrefixException</code> : upon invalid object prefix.</li>
<li> <code>NoSuchAlgorithmException</code> : upon requested algorithm was not found during signature calculation.</li>
<li> <code>InsufficientDataException</code> : Thrown to indicate that reading given InputStream gets EOFException before reading given length..</li>
<li><code>IOException : upon connection error.</li>
<li> <code>InvalidKeyException</code> : upon an invalid access key or secret key.</li>
<li> <code>NoResponseException</code> : upon no response from server.</li>
<li><code>org.xmlpull.v1.XmlPullParserException</code> : upon parsing response XML.</li>
<li><code>ErrorResponseException</code> : upon unsuccessful execution.</li>
<li><code>InternalException</code> : upon internal library error.</li>
<li><code>NoSuchBucketPolicyException</code>: Thrown to indicate that given bucket has no bucket policy set.
</ul>
</td>
</tr>
</tbody>
</table>

__Example__

```java
try {
minioClient.setBucketPolicy("myBucket", "uploads", BucketPolicy.WriteOnly);
} catch (MinioException e) {
System.out.println("Error occured: " + e);
}
```

## 3. Object operations

Expand Down
42 changes: 42 additions & 0 deletions examples/GetBucketPolicy.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
/*
* Minio Java Library for Amazon S3 Compatible Cloud Storage, (C) 2015 Minio, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

import java.io.IOException;
import java.security.NoSuchAlgorithmException;
import java.security.InvalidKeyException;

import org.xmlpull.v1.XmlPullParserException;

import io.minio.MinioClient;
import io.minio.BucketPolicy;
import io.minio.errors.MinioException;

public class GetBucketPolicy {
public static void main(String[] args)
throws IOException, NoSuchAlgorithmException, InvalidKeyException, XmlPullParserException {
// Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are
// dummy values, please replace them with original values.
// For Amazon S3 endpoint, region is calculated automatically
try {
MinioClient minioClient = new MinioClient("https://play.minio.io:9000", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY");

BucketPolicy policy = minioClient.getBucketPolicy("my-bucketname", "downloads");
System.out.println("Current policy: " + policy.toString());
} catch (MinioException e) {
System.out.println("Error occured: " + e);
}
}
}
41 changes: 41 additions & 0 deletions examples/SetBucketPolicy.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
/*
* Minio Java Library for Amazon S3 Compatible Cloud Storage, (C) 2015 Minio, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

import java.io.IOException;
import java.security.NoSuchAlgorithmException;
import java.security.InvalidKeyException;

import org.xmlpull.v1.XmlPullParserException;

import io.minio.MinioClient;
import io.minio.BucketPolicy;
import io.minio.errors.MinioException;

public class SetBucketPolicy {
public static void main(String[] args)
throws IOException, NoSuchAlgorithmException, InvalidKeyException, XmlPullParserException {
// Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are
// dummy values, please replace them with original values.
// For Amazon S3 endpoint, region is calculated automatically
try {
MinioClient minioClient = new MinioClient("https://play.minio.io:9000", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY");

minioClient.setBucketPolicy("my-bucketname", "downloads", BucketPolicy.ReadOnly);
} catch (MinioException e) {
System.out.println("Error occured: " + e);
}
}
}

0 comments on commit fecd1f9

Please sign in to comment.