Skip to content

Commit 9979502

Browse files
aozarovaozarov
committed
Merge pull request #356 from mziccard/storage-javadoc
Better document Storage API
2 parents e4471f9 + 5f9eaa4 commit 9979502

File tree

7 files changed

+559
-2
lines changed

7 files changed

+559
-2
lines changed

‎gcloud-java-storage/src/main/java/com/google/gcloud/storage/Acl.java‎

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,10 @@
2323
import java.util.Objects;
2424

2525
/**
26-
* Access Control List on for buckets or blobs.
26+
* Access Control List for buckets or blobs.
27+
*
28+
* @see <a href="https://cloud.google.com/storage/docs/access-control#About-Access-Control-Lists">
29+
* About Access Control Lists</a>
2730
*/
2831
public final class Acl implements Serializable {
2932

@@ -36,6 +39,9 @@ public enum Role {
3639
OWNER, READER, WRITER
3740
}
3841

42+
/**
43+
* Base class for Access Control List entities.
44+
*/
3945
public abstract static class Entity implements Serializable {
4046

4147
private static final long serialVersionUID = -2707407252771255840L;
@@ -52,10 +58,16 @@ public enum Type {
5258
this.value = value;
5359
}
5460

61+
/**
62+
* Returns the type of entity.
63+
*/
5564
public Type type() {
5665
return type;
5766
}
5867

68+
/**
69+
* Returns the entity's value.
70+
*/
5971
protected String value() {
6072
return value;
6173
}
@@ -112,42 +124,75 @@ static Entity fromPb(String entity) {
112124
}
113125
}
114126

127+
/**
128+
* Class for ACL Domain entities.
129+
*/
115130
public static final class Domain extends Entity {
116131

117132
private static final long serialVersionUID = -3033025857280447253L;
118133

134+
/**
135+
* Creates a domain entity.
136+
*
137+
* @param domain the domain associated to this entity
138+
*/
119139
public Domain(String domain) {
120140
super(Type.DOMAIN, domain);
121141
}
122142

143+
/**
144+
* Returns the domain associated to this entity.
145+
*/
123146
public String domain() {
124147
return value();
125148
}
126149
}
127150

151+
/**
152+
* Class for ACL Group entities.
153+
*/
128154
public static final class Group extends Entity {
129155

130156
private static final long serialVersionUID = -1660987136294408826L;
131157

158+
/**
159+
* Creates a group entity.
160+
*
161+
* @param email the group email
162+
*/
132163
public Group(String email) {
133164
super(Type.GROUP, email);
134165
}
135166

167+
/**
168+
* Returns the group email.
169+
*/
136170
public String email() {
137171
return value();
138172
}
139173
}
140174

175+
/**
176+
* Class for ACL User entities.
177+
*/
141178
public static final class User extends Entity {
142179

143180
private static final long serialVersionUID = 3076518036392737008L;
144181
private static final String ALL_USERS = "allUsers";
145182
private static final String ALL_AUTHENTICATED_USERS = "allAuthenticatedUsers";
146183

184+
/**
185+
* Creates a user entity.
186+
*
187+
* @param email the user email
188+
*/
147189
public User(String email) {
148190
super(Type.USER, email);
149191
}
150192

193+
/**
194+
* Returns the user email.
195+
*/
151196
public String email() {
152197
return value();
153198
}
@@ -174,6 +219,9 @@ public static User ofAllAuthenticatedUsers() {
174219
}
175220
}
176221

222+
/**
223+
* Class for ACL Project entities.
224+
*/
177225
public static final class Project extends Entity {
178226

179227
private static final long serialVersionUID = 7933776866530023027L;
@@ -185,16 +233,28 @@ public enum ProjectRole {
185233
OWNERS, EDITORS, VIEWERS
186234
}
187235

236+
/**
237+
* Creates a project entity.
238+
*
239+
* @param pRole a role in the project, used to select project's teams
240+
* @param projectId id of the project
241+
*/
188242
public Project(ProjectRole pRole, String projectId) {
189243
super(Type.PROJECT, pRole.name().toLowerCase() + "-" + projectId);
190244
this.pRole = pRole;
191245
this.projectId = projectId;
192246
}
193247

248+
/**
249+
* Returns the role in the project for this entity.
250+
*/
194251
public ProjectRole projectRole() {
195252
return pRole;
196253
}
197254

255+
/**
256+
* Returns the project id for this entity.
257+
*/
198258
public String projectId() {
199259
return projectId;
200260
}
@@ -214,15 +274,27 @@ String toPb() {
214274
}
215275
}
216276

277+
/**
278+
* Creats an ACL object.
279+
*
280+
* @param entity the entity for this ACL object
281+
* @param role the role to associate to the {@code entity} object
282+
*/
217283
public Acl(Entity entity, Role role) {
218284
this.entity = entity;
219285
this.role = role;
220286
}
221287

288+
/**
289+
* Returns the entity for this ACL object.
290+
*/
222291
public Entity entity() {
223292
return entity;
224293
}
225294

295+
/**
296+
* Returns the role associated to the entity in this ACL object.
297+
*/
226298
public Role role() {
227299
return role;
228300
}

‎gcloud-java-storage/src/main/java/com/google/gcloud/storage/Blob.java‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,9 @@ public final class Blob {
5050
private final Storage storage;
5151
private final BlobInfo info;
5252

53+
/**
54+
* Class for specifying blob source options when {@code Blob} methods are used.
55+
*/
5356
public static class BlobSourceOption extends Option {
5457

5558
private static final long serialVersionUID = 214616862061934846L;
@@ -88,18 +91,34 @@ private Storage.BlobGetOption toGetOption(BlobInfo blobInfo) {
8891
}
8992
}
9093

94+
/**
95+
* Returns an option for blob's generation match. If this option is used the request will fail
96+
* if generation does not match.
97+
*/
9198
public static BlobSourceOption generationMatch() {
9299
return new BlobSourceOption(StorageRpc.Option.IF_GENERATION_MATCH);
93100
}
94101

102+
/**
103+
* Returns an option for blob's generation mismatch. If this option is used the request will
104+
* fail if generation matches.
105+
*/
95106
public static BlobSourceOption generationNotMatch() {
96107
return new BlobSourceOption(StorageRpc.Option.IF_GENERATION_NOT_MATCH);
97108
}
98109

110+
/**
111+
* Returns an option for blob's metageneration match. If this option is used the request will
112+
* fail if metageneration does not match.
113+
*/
99114
public static BlobSourceOption metagenerationMatch() {
100115
return new BlobSourceOption(StorageRpc.Option.IF_METAGENERATION_MATCH);
101116
}
102117

118+
/**
119+
* Returns an option for blob's metageneration mismatch. If this option is used the request will
120+
* fail if metageneration matches.
121+
*/
103122
public static BlobSourceOption metagenerationNotMatch() {
104123
return new BlobSourceOption(StorageRpc.Option.IF_METAGENERATION_NOT_MATCH);
105124
}

‎gcloud-java-storage/src/main/java/com/google/gcloud/storage/BlobId.java‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,16 @@ private BlobId(String bucket, String name) {
3838
this.name = name;
3939
}
4040

41+
/**
42+
* Returns the name of the bucket containing the blob.
43+
*/
4144
public String bucket() {
4245
return bucket;
4346
}
4447

48+
/**
49+
* Returns the name of the blob.
50+
*/
4551
public String name() {
4652
return name;
4753
}
@@ -72,6 +78,12 @@ StorageObject toPb() {
7278
return storageObject;
7379
}
7480

81+
/**
82+
* Creates a blob identifier.
83+
*
84+
* @param bucket the name of the bucket that contains the blob
85+
* @param name the name of the blob
86+
*/
7587
public static BlobId of(String bucket, String name) {
7688
return new BlobId(checkNotNull(bucket), checkNotNull(name));
7789
}

0 commit comments

Comments
 (0)