1 // Copyright 2009 Google Inc. All Rights Reserved.
3 package com
.google
.appengine
.api
.blobstore
;
5 import java
.io
.IOException
;
9 import javax
.servlet
.http
.HttpServletRequest
;
10 import javax
.servlet
.http
.HttpServletResponse
;
13 * {@code BlobstoreService} allows you to manage the creation and
14 * serving of large, immutable blobs to users.
17 public interface BlobstoreService
{
18 public static final int MAX_BLOB_FETCH_SIZE
= (1 << 20) - (1 << 15);
21 * Create an absolute URL that can be used by a user to
22 * asynchronously upload a large blob. Upon completion of the
23 * upload, a callback is made to the specified URL.
25 * @param successPath A relative URL which will be invoked
26 * after the user successfully uploads a blob. Must start with a "/".
28 * @throws IllegalArgumentException If successPath was not valid.
29 * @throws BlobstoreFailureException If an error occurred while
30 * communicating with the blobstore.
32 String
createUploadUrl(String successPath
);
35 * Create an absolute URL that can be used by a user to
36 * asynchronously upload a large blob. Upon completion of the
37 * upload, a callback is made to the specified URL.
39 * @param successPath A relative URL which will be invoked
40 * after the user successfully uploads a blob. Must start with a "/".
41 * @param uploadOptions Specific options applicable only for this
44 * @throws IllegalArgumentException If successPath was not valid.
45 * @throws BlobstoreFailureException If an error occurred while
46 * communicating with the blobstore.
48 String
createUploadUrl(String successPath
, UploadOptions uploadOptions
);
51 * Arrange for the specified blob to be served as the response
52 * content for the current request. {@code response} should be
53 * uncommitted before invoking this method, and should be assumed to
54 * be committed after invoking it. Any content written before
55 * calling this method will be ignored. You may, however, append
56 * custom headers before or after calling this method.
58 * <p>Range header will be automatically translated from the Content-Range
59 * header in the response.
61 * @param blobKey Blob-key to serve in response.
62 * @param response HTTP response object.
64 * @throws IOException If an I/O error occurred.
65 * @throws IllegalStateException If {@code response} was already committed.
67 void serve(BlobKey blobKey
, HttpServletResponse response
) throws IOException
;
70 * Arrange for the specified blob to be served as the response
71 * content for the current request. {@code response} should be
72 * uncommitted before invoking this method, and should be assumed to
73 * be committed after invoking it. Any content written before
74 * calling this method will be ignored. You may, however, append
75 * custom headers before or after calling this method.
77 * <p>This method will set the App Engine blob range header to serve a
78 * byte range of that blob.
80 * @param blobKey Blob-key to serve in response.
81 * @param byteRange Byte range to serve in response.
82 * @param response HTTP response object.
84 * @throws IOException If an I/O error occurred.
85 * @throws IllegalStateException If {@code response} was already committed.
87 void serve(BlobKey blobKey
, ByteRange byteRange
, HttpServletResponse response
)
91 * Arrange for the specified blob to be served as the response
92 * content for the current request. {@code response} should be
93 * uncommitted before invoking this method, and should be assumed to
94 * be committed after invoking it. Any content written before
95 * calling this method will be ignored. You may, however, append
96 * custom headers before or after calling this method.
98 * <p>This method will set the App Engine blob range header to the content
101 * @param blobKey Blob-key to serve in response.
102 * @param rangeHeader Content for range header to serve.
103 * @param response HTTP response object.
105 * @throws IOException If an I/O error occurred.
106 * @throws IllegalStateException If {@code response} was already committed.
108 void serve(BlobKey blobKey
, String rangeHeader
, HttpServletResponse response
)
112 * Get byte range from the request.
114 * @param request HTTP request object.
116 * @return Byte range as parsed from the HTTP range header. null if there is no header.
118 * @throws RangeFormatException Unable to parse header because of invalid format.
119 * @throws UnsupportedRangeFormatException Header is a valid HTTP range header, the specific
120 * form is not supported by app engine. This includes unit types other than "bytes" and multiple
123 ByteRange
getByteRange(HttpServletRequest request
);
126 * Permanently deletes the specified blobs. Deleting unknown blobs is a
129 * @throws BlobstoreFailureException If an error occurred while
130 * communicating with the blobstore.
132 void delete(BlobKey
... blobKeys
);
135 * Returns the {@link BlobKey} for any files that were uploaded, keyed by the
136 * upload form "name" field.
137 * <p>This method should only be called from within a request served by
138 * the destination of a {@code createUploadUrl} call.
140 * @throws IllegalStateException If not called from a blob upload
143 * @deprecated Use {@link #getUploads} instead. Note that getUploadedBlobs
144 * does not handle cases where blobs have been uploaded using the
145 * multiple="true" attribute of the file input form element.
147 @Deprecated Map
<String
, BlobKey
> getUploadedBlobs(HttpServletRequest request
);
150 * Returns the {@link BlobKey} for any files that were uploaded, keyed by the
151 * upload form "name" field.
152 * This method should only be called from within a request served by
153 * the destination of a {@link createUploadUrl} call.
155 * @throws IllegalStateException If not called from a blob upload
157 * @see getBlobInfos, getFileInfos
159 Map
<String
, List
<BlobKey
>> getUploads(HttpServletRequest request
);
162 * Returns the {@link BlobInfo} for any files that were uploaded, keyed by the
163 * upload form "name" field.
164 * This method should only be called from within a request served by
165 * the destination of a {@link createUploadUrl} call.
167 * @throws IllegalStateException If not called from a blob upload
169 * @see getFileInfos, getUploads
172 Map
<String
, List
<BlobInfo
>> getBlobInfos(HttpServletRequest request
);
175 * Returns the {@link FileInfo} for any files that were uploaded, keyed by the
176 * upload form "name" field.
177 * This method should only be called from within a request served by
178 * the destination of a {@link createUploadUrl} call.
180 * Prefer this method over {@link getBlobInfos} or {@link getUploads} if
181 * uploading files to Cloud Storage, as the FileInfo contains the name of the
182 * created filename in Cloud Storage.
184 * @throws IllegalStateException If not called from a blob upload
186 * @see getBlobInfos, getUploads
189 Map
<String
, List
<FileInfo
>> getFileInfos(HttpServletRequest request
);
192 * Get fragment from specified blob.
194 * @param blobKey Blob-key from which to fetch data.
195 * @param startIndex Start index of data to fetch.
196 * @param endIndex End index (inclusive) of data to fetch.
198 * @throws IllegalArgumentException If blob not found, indexes are negative,
199 * indexes are inverted or fetch size is too large.
200 * @throws SecurityException If the application does not have acces to the blob.
201 * @throws BlobstoreFailureException If an error occurred while communicating
202 * with the blobstore.
204 byte[] fetchData(BlobKey blobKey
, long startIndex
, long endIndex
);
207 * Create a {@link BlobKey} for a Google Storage File.
209 * The existance of the file represented by filename is not checked, hence
210 * a BlobKey can be created for a file that does not currently exist.
212 * You can safely persist the {@link BlobKey} generated by this function.
214 * <p>The created {@link BlobKey} can then be used as a parameter in API methods
215 * that can support objects in Google Storage, for example {@link serve}.
217 * @param filename The Google Storage filename. The filename must be in the
218 * format "/gs/bucket_name/object_name".
220 * @throws IllegalArgumentException If the filename does not have the prefix
223 BlobKey
createGsBlobKey(String filename
);