Skip to content

Commit f201a7a

Browse files
mziccardmziccard
committed
Add snippets to Bucket's javadoc, BucketSnippets class and tests
1 parent 23eb620 commit f201a7a

3 files changed

Lines changed: 442 additions & 1 deletion

File tree

‎gcloud-java-examples/src/main/java/com/google/cloud/examples/storage/snippets/BucketSnippets.java‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
/*
2+
* Copyright 2016 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
/*
18+
* EDITING INSTRUCTIONS
19+
* This file is referenced in Bucket's javadoc. Any change to this file should be reflected in
20+
* Bucket's javadoc.
21+
*/
22+
23+
package com.google.cloud.examples.storage.snippets;
24+
25+
import static java.nio.charset.StandardCharsets.UTF_8;
26+
27+
import com.google.cloud.storage.Blob;
28+
import com.google.cloud.storage.Bucket;
29+
import com.google.cloud.storage.Bucket.BucketSourceOption;
30+
import com.google.cloud.storage.Storage.BlobGetOption;
31+
import com.google.cloud.storage.StorageException;
32+
33+
import java.io.ByteArrayInputStream;
34+
import java.io.InputStream;
35+
import java.util.Iterator;
36+
import java.util.LinkedList;
37+
import java.util.List;
38+
39+
/**
40+
* This class contains a number of snippets for the {@link Bucket} class.
41+
*/
42+
public class BucketSnippets {
43+
44+
private final Bucket bucket;
45+
46+
public BucketSnippets(Bucket bucket) {
47+
this.bucket = bucket;
48+
}
49+
50+
/**
51+
* Example of checking if the bucket exists.
52+
*/
53+
// [TARGET exists(BucketSourceOption...)]
54+
public boolean exists() {
55+
// [START exists]
56+
boolean exists = bucket.exists();
57+
if (exists) {
58+
// the bucket exists
59+
} else {
60+
// the bucket was not found
61+
}
62+
// [END exists]
63+
return exists;
64+
}
65+
66+
/**
67+
* Example of getting the bucket's latest information, if its generation does not match the
68+
* {@link Bucket#metageneration()} value, otherwise a {@link StorageException} is thrown.
69+
*/
70+
// [TARGET reload(BucketSourceOption...)]
71+
public Bucket reload() {
72+
// [START reload]
73+
Bucket latestBucket = bucket.reload(BucketSourceOption.metagenerationMatch());
74+
if (latestBucket == null) {
75+
// the bucket was not found
76+
}
77+
// [END reload]
78+
return bucket;
79+
}
80+
81+
/**
82+
* Example of updating the bucket's information.
83+
*/
84+
// [TARGET update(BucketTargetOption...)]
85+
public Bucket update() {
86+
// [START update]
87+
Bucket updatedBucket = bucket.toBuilder().versioningEnabled(true).build().update();
88+
// [END update]
89+
return updatedBucket;
90+
}
91+
92+
/**
93+
* Example of deleting the bucket, if its metageneration matches the
94+
* {@link Bucket#metageneration()} value, otherwise a {@link StorageException} is thrown.
95+
*/
96+
// [TARGET delete(BucketSourceOption...)]
97+
public boolean delete() {
98+
// [START delete]
99+
boolean deleted = bucket.delete(BucketSourceOption.metagenerationMatch());
100+
if (deleted) {
101+
// the bucket was deleted
102+
} else {
103+
// the bucket was not found
104+
}
105+
// [END delete]
106+
return deleted;
107+
}
108+
109+
/**
110+
* Example of listing the blobs in the bucket.
111+
*/
112+
// [TARGET list(BlobListOption...)]
113+
public Iterator<Blob> listBlobs() {
114+
// [START listBlobs]
115+
Iterator<Blob> blobIterator = bucket.list().iterateAll();
116+
while (blobIterator.hasNext()) {
117+
Blob blob = blobIterator.next();
118+
// do something with the blob
119+
}
120+
// [END listBlobs]
121+
return blobIterator;
122+
}
123+
124+
/**
125+
* Example of getting a blob in the bucket, only if its metageneration matches a value, otherwise
126+
* a {@link StorageException} is thrown.
127+
*/
128+
// [TARGET get(String, BlobGetOption...)]
129+
// [VARIABLE "my_blob_name"]
130+
// [VARIABLE 42]
131+
public Blob getBlob(String blobName, long generation) {
132+
// [START getBlob]
133+
Blob blob = bucket.get(blobName, BlobGetOption.generationMatch(generation));
134+
// [END getBlob]
135+
return blob;
136+
}
137+
138+
139+
/**
140+
* Example of getting some blobs in the bucket, using a batch request.
141+
*/
142+
// [TARGET get(String, String, String...)]
143+
// [VARIABLE "my_blob_name1"]
144+
// [VARIABLE "my_blob_name2"]
145+
public List<Blob> getBlobFromStrings(String blobName1, String blobName2) {
146+
// [START getBlobFromStrings]
147+
List<Blob> blobs = bucket.get(blobName1, blobName2);
148+
for (Blob blob : blobs) {
149+
if (blob == null) {
150+
// the blob was not found
151+
}
152+
}
153+
// [END getBlobFromStrings]
154+
return blobs;
155+
}
156+
157+
/**
158+
* Example of getting some blobs in the bucket, using a batch request.
159+
*/
160+
// [TARGET get(Iterable)]
161+
// [VARIABLE "my_blob_name1"]
162+
// [VARIABLE "my_blob_name2"]
163+
public List<Blob> getBlobFromStringIterable(String blobName1, String blobName2) {
164+
// [START getBlobFromStringIterable]
165+
List<String> blobNames = new LinkedList<>();
166+
blobNames.add(blobName1);
167+
blobNames.add(blobName2);
168+
List<Blob> blobs = bucket.get(blobNames);
169+
for (Blob blob : blobs) {
170+
if (blob == null) {
171+
// the blob was not found
172+
}
173+
}
174+
// [END getBlobFromStringIterable]
175+
return blobs;
176+
}
177+
178+
/**
179+
* Example of creating a blob in the bucket from a byte array.
180+
*/
181+
// [TARGET create(String, byte[], BlobTargetOption...)]
182+
// [VARIABLE "my_blob_name"]
183+
public Blob createBlobFromByteArray(String blobName) {
184+
// [START createBlobFromByteArray]
185+
Blob blob = bucket.create(blobName, "Hello, World!".getBytes(UTF_8));
186+
// [END createBlobFromByteArray]
187+
return blob;
188+
}
189+
190+
/**
191+
* Example of creating a blob in the bucket from an input stream.
192+
*/
193+
// [TARGET create(String, InputStream, BlobWriteOption...)]
194+
// [VARIABLE "my_blob_name"]
195+
public Blob createBlobFromInputStream(String blobName) {
196+
// [START createBlobFromInputStream]
197+
InputStream content = new ByteArrayInputStream("Hello, World!".getBytes(UTF_8));
198+
Blob blob = bucket.create(blobName, content);
199+
// [END createBlobFromInputStream]
200+
return blob;
201+
}
202+
203+
/**
204+
* Example of creating a blob in the bucket from a byte array with a content type.
205+
*/
206+
// [TARGET create(String, byte[], String, BlobTargetOption...)]
207+
// [VARIABLE "my_blob_name"]
208+
public Blob createBlobFromByteArrayWithContentType(String blobName) {
209+
// [START createBlobFromByteArrayWithContentType]
210+
Blob blob = bucket.create(blobName, "Hello, World!".getBytes(UTF_8), "text/plain");
211+
// [END createBlobFromByteArrayWithContentType]
212+
return blob;
213+
}
214+
215+
/**
216+
* Example of creating a blob in the bucket from an input stream with a content type.
217+
*/
218+
// [TARGET create(String, InputStream, String, BlobWriteOption...)]
219+
// [VARIABLE "my_blob_name"]
220+
public Blob createBlobFromInputStreamWithContentType(String blobName) {
221+
// [START createBlobFromInputStreamWithContentType]
222+
InputStream content = new ByteArrayInputStream("Hello, World!".getBytes(UTF_8));
223+
Blob blob = bucket.create(blobName, content, "text/plain");
224+
// [END createBlobFromInputStreamWithContentType]
225+
return blob;
226+
}
227+
}

‎gcloud-java-examples/src/test/java/com/google/cloud/examples/storage/snippets/ITBucketSnippets.java‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
/*
2+
* Copyright 2016 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.cloud.examples.storage.snippets;
18+
19+
import static org.junit.Assert.assertEquals;
20+
import static org.junit.Assert.assertNotNull;
21+
import static org.junit.Assert.assertTrue;
22+
23+
import com.google.cloud.storage.Blob;
24+
import com.google.cloud.storage.Bucket;
25+
import com.google.cloud.storage.BucketInfo;
26+
import com.google.cloud.storage.Storage;
27+
import com.google.cloud.storage.StorageException;
28+
import com.google.cloud.storage.testing.RemoteStorageHelper;
29+
import com.google.common.collect.ImmutableSet;
30+
31+
import org.junit.AfterClass;
32+
import org.junit.BeforeClass;
33+
import org.junit.Rule;
34+
import org.junit.Test;
35+
import org.junit.rules.ExpectedException;
36+
37+
import java.util.Iterator;
38+
import java.util.List;
39+
import java.util.Set;
40+
import java.util.concurrent.ExecutionException;
41+
import java.util.concurrent.TimeUnit;
42+
import java.util.logging.Level;
43+
import java.util.logging.Logger;
44+
45+
public class ITBucketSnippets {
46+
47+
private static final Logger log = Logger.getLogger(ITBucketSnippets.class.getName());
48+
private static final String BUCKET = RemoteStorageHelper.generateBucketName();
49+
private static final String BLOB1 = "blob1";
50+
private static final String BLOB2 = "blob2";
51+
private static final String BLOB3 = "blob3";
52+
private static final String BLOB4 = "blob4";
53+
private static final Set<String> BLOBS = ImmutableSet.of(BLOB1, BLOB2, BLOB3, BLOB4);
54+
55+
private static Storage storage;
56+
private static BucketSnippets bucketSnippets;
57+
58+
@Rule
59+
public ExpectedException thrown = ExpectedException.none();
60+
61+
@BeforeClass
62+
public static void beforeClass() {
63+
RemoteStorageHelper helper = RemoteStorageHelper.create();
64+
storage = helper.options().service();
65+
bucketSnippets = new BucketSnippets(storage.create(BucketInfo.of(BUCKET)));
66+
}
67+
68+
@AfterClass
69+
public static void afterClass() throws ExecutionException, InterruptedException {
70+
if (storage != null) {
71+
boolean wasDeleted = RemoteStorageHelper.forceDelete(storage, BUCKET, 5, TimeUnit.SECONDS);
72+
if (!wasDeleted && log.isLoggable(Level.WARNING)) {
73+
log.log(Level.WARNING, "Deletion of bucket {0} timed out, bucket is not empty", BUCKET);
74+
}
75+
}
76+
}
77+
78+
@Test
79+
public void testBucket() {
80+
assertTrue(bucketSnippets.exists());
81+
Bucket bucket = bucketSnippets.reload();
82+
assertNotNull(bucket);
83+
Bucket updatedBucket = bucketSnippets.update();
84+
assertTrue(updatedBucket.versioningEnabled());
85+
Blob blob1 = bucketSnippets.createBlobFromByteArray(BLOB1);
86+
assertNotNull(blob1);
87+
Blob blob2 = bucketSnippets.createBlobFromByteArrayWithContentType(BLOB2);
88+
assertNotNull(blob2);
89+
Blob blob3 = bucketSnippets.createBlobFromInputStream(BLOB3);
90+
assertNotNull(blob3);
91+
Blob blob4 = bucketSnippets.createBlobFromInputStreamWithContentType(BLOB4);
92+
assertNotNull(blob4);
93+
Iterator<Blob> blobIterator = bucketSnippets.listBlobs();
94+
while (blobIterator.hasNext()) {
95+
assertTrue(BLOBS.contains(blobIterator.next().name()));
96+
}
97+
blob1 = bucketSnippets.getBlob(BLOB1, blob1.generation());
98+
assertEquals(BLOB1, blob1.name());
99+
List<Blob> blobs = bucketSnippets.getBlobFromStrings(BLOB2, BLOB3);
100+
assertEquals(BLOB2, blobs.get(0).name());
101+
assertEquals(BLOB3, blobs.get(1).name());
102+
blobs = bucketSnippets.getBlobFromStringIterable(BLOB3, BLOB4);
103+
assertEquals(BLOB3, blobs.get(0).name());
104+
assertEquals(BLOB4, blobs.get(1).name());
105+
thrown.expect(StorageException.class);
106+
assertTrue(bucketSnippets.delete());
107+
}
108+
}

0 commit comments

Comments
 (0)