1 /**
2 *
3 * Copyright (C) 2011 Cloud Conscious, LLC. <info@cloudconscious.com>
4 *
5 * ====================================================================
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 * ====================================================================
18 */
19 package org.jclouds.blobstore;
20
21 import java.util.Set;
22
23 import javax.annotation.Nullable;
24
25 import org.jclouds.blobstore.domain.Blob;
26 import org.jclouds.blobstore.domain.BlobBuilder;
27 import org.jclouds.blobstore.domain.BlobMetadata;
28 import org.jclouds.blobstore.domain.PageSet;
29 import org.jclouds.blobstore.domain.StorageMetadata;
30 import org.jclouds.blobstore.options.CreateContainerOptions;
31 import org.jclouds.blobstore.options.GetOptions;
32 import org.jclouds.blobstore.options.ListContainerOptions;
33 import org.jclouds.blobstore.options.PutOptions;
34 import org.jclouds.domain.Location;
35
36 /**
37 * Synchronous access to a BlobStore such as Amazon S3
38 *
39 * @author Adrian Cole
40 * @see AsyncBlobStore
41 *
42 * @see BlobStoreContextFactory
43 */
44 public interface BlobStore {
45 /**
46 * @return a reference to the context that created this BlobStore.
47 */
48 BlobStoreContext getContext();
49
50 /**
51 * creates a new blob with the specified name.
52 *
53 * @see #blobBuilder
54 */
55 @Deprecated
56 Blob newBlob(String name);
57
58 /**
59 *
60 * @return builder for creating new {@link Blob}s
61 */
62 BlobBuilder blobBuilder(String name);
63
64 /**
65 * The get locations command returns all the valid locations for containers. A location has a
66 * scope, which is typically region or zone. A region is a general area, like eu-west, where a
67 * zone is similar to a datacenter. If a location has a parent, that implies it is within that
68 * location. For example a location can be a rack, whose parent is likely to be a zone.
69 */
70 Set<? extends Location> listAssignableLocations();
71
72 /**
73 * Lists all root-level resources available to the identity.
74 */
75 PageSet<? extends StorageMetadata> list();
76
77 /**
78 * determines if a service-level container exists
79 */
80 boolean containerExists(String container);
81
82 /**
83 * Creates a namespace for your blobs
84 * <p/>
85 *
86 * A container is a namespace for your objects. Depending on the service, the scope can be
87 * global, identity, or sub-identity scoped. For example, in Amazon S3, containers are called
88 * buckets, and they must be uniquely named such that no-one else in the world conflicts. In
89 * other blobstores, the naming convention of the container is less strict. All blobstores allow
90 * you to list your containers and also the contents within them. These contents can either be
91 * blobs, folders, or virtual paths.
92 *
93 * @param location
94 * some blobstores allow you to specify a location, such as US-EAST, for where this
95 * container will exist. null will choose a default location
96 * @param container
97 * namespace. Typically constrained to lowercase alpha-numeric and hyphens.
98 * @return true if the container was created, false if it already existed.
99 */
100 boolean createContainerInLocation(@Nullable Location location, String container);
101
102 /**
103 *
104 * @param options
105 * controls default access control
106 * @see #createContainerInLocation(Location,String)
107 */
108 boolean createContainerInLocation(@Nullable Location location, String container, CreateContainerOptions options);
109
110 /**
111 * Lists all resources in a container non-recursive.
112 *
113 * @param container
114 * what to list
115 * @return a list that may be incomplete, depending on whether PageSet#getNextMarker is set
116 */
117 PageSet<? extends StorageMetadata> list(String container);
118
119 /**
120 * Like {@link #list(String)} except you can control the size, recursion, and context of the list
121 * using {@link ListContainerOptions options}
122 *
123 * @param container
124 * what to list
125 * @param options
126 * size, recursion, and context of the list
127 * @return a list that may be incomplete, depending on whether PageSet#getNextMarker is set
128 */
129 PageSet<? extends StorageMetadata> list(String container, ListContainerOptions options);
130
131 /**
132 * This will delete the contents of a container at its root path without deleting the container
133 *
134 * @param container
135 * what to clear
136 */
137 void clearContainer(String container);
138
139 /**
140 * Like {@link #clearContainer(String)} except you can use options to do things like recursive
141 * deletes, or clear at a different path than root.
142 *
143 * @param container
144 * what to clear
145 * @param options
146 * recursion and path to clear
147 */
148 void clearContainer(String container, ListContainerOptions options);
149
150 /**
151 * This will delete everything inside a container recursively.
152 *
153 * @param container
154 * what to delete
155 */
156 void deleteContainer(String container);
157
158 /**
159 * Determines if a directory exists
160 *
161 * @param container
162 * container where the directory resides
163 * @param directory
164 * full path to the directory
165 */
166 boolean directoryExists(String container, String directory);
167
168 /**
169 * Creates a folder or a directory marker depending on the service
170 *
171 * @param container
172 * container to create the directory in
173 * @param directory
174 * full path to the directory
175 */
176 void createDirectory(String container, String directory);
177
178 /**
179 * Deletes a folder or a directory marker depending on the service
180 *
181 * @param container
182 * container to delete the directory from
183 * @param directory
184 * full path to the directory to delete
185 */
186 void deleteDirectory(String containerName, String name);
187
188 /**
189 * Determines if a blob exists
190 *
191 * @param container
192 * container where the blob resides
193 * @param directory
194 * full path to the blob
195 */
196 boolean blobExists(String container, String name);
197
198 /**
199 * Adds a {@code Blob} representing the data at location {@code container/blob.metadata.name}
200 *
201 * @param container
202 * container to place the blob.
203 * @param blob
204 * fully qualified name relative to the container.
205 * @param options
206 * byte range or condition options
207 * @return etag of the blob you uploaded, possibly null where etags are unsupported
208 * @throws ContainerNotFoundException
209 * if the container doesn't exist
210 */
211 String putBlob(String container, Blob blob);
212
213 /**
214 * Adds a {@code Blob} representing the data at location {@code container/blob.metadata.name}
215 * options using multipart strategies.
216 *
217 * @param container
218 * container to place the blob.
219 * @param blob
220 * fully qualified name relative to the container.
221 * @param options
222 * byte range options
223 * @return etag of the blob you uploaded, possibly null where etags are unsupported
224 * @throws ContainerNotFoundException
225 * if the container doesn't exist
226 */
227 String putBlob(String container, Blob blob, PutOptions options);
228
229 /**
230 * Retrieves the metadata of a {@code Blob} at location {@code container/name}
231 *
232 * @param container
233 * container where this exists.
234 * @param name
235 * fully qualified name relative to the container.
236 * @return null if name isn't present or the blob you intended to receive.
237 * @throws ContainerNotFoundException
238 * if the container doesn't exist
239 */
240 BlobMetadata blobMetadata(String container, String name);
241
242 /**
243 * Retrieves a {@code Blob} representing the data at location {@code container/name}
244 *
245 * @param container
246 * container where this exists.
247 * @param name
248 * fully qualified name relative to the container.
249 * @return the blob you intended to receive or null, if it doesn't exist.
250 * @throws ContainerNotFoundException
251 * if the container doesn't exist
252 */
253 Blob getBlob(String container, String name);
254
255 /**
256 * Retrieves a {@code Blob} representing the data at location {@code container/name}
257 *
258 * @param container
259 * container where this exists.
260 * @param name
261 * fully qualified name relative to the container.
262 * @param options
263 * byte range or condition options
264 * @return the blob you intended to receive or null, if it doesn't exist.
265 * @throws ContainerNotFoundException
266 * if the container doesn't exist
267 */
268 Blob getBlob(String container, String name, GetOptions options);
269
270 /**
271 * Deletes a {@code Blob} representing the data at location {@code container/name}
272 *
273 * @param container
274 * container where this exists.
275 * @param name
276 * fully qualified name relative to the container.
277 * @throws ContainerNotFoundException
278 * if the container doesn't exist
279 */
280 void removeBlob(String container, String name);
281
282 /**
283 * @return a count of all blobs in the container, excluding directory markers
284 */
285 long countBlobs(String container);
286
287 /**
288 * @return a count of all blobs that are in a listing constrained by the options specified,
289 * excluding directory markers
290 */
291 long countBlobs(String container, ListContainerOptions options);
292
293 }