java/src/main/com/google/appengine/api/blobstore/BlobstoreService.java

   1 // Copyright 2009 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.blobstore;
   4
   5 import java.io.IOException;
   6 import java.util.List;
   7 import java.util.Map;
   8
   9 import javax.servlet.http.HttpServletRequest;
  10 import javax.servlet.http.HttpServletResponse;
  11
  12 /**
  13  * {@code BlobstoreService} allows you to manage the creation and
  14  * serving of large, immutable blobs to users.
  15  *
  16  */
  17 public interface BlobstoreService {
  18   public static final int MAX_BLOB_FETCH_SIZE = (1 << 20) - (1 << 15);
  19
  20   /**
  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.
  24    *
  25    * @param successPath A relative URL which will be invoked
  26    * after the user successfully uploads a blob. Must start with a "/".
  27    *
  28    * @throws IllegalArgumentException If successPath was not valid.
  29    * @throws BlobstoreFailureException If an error occurred while
  30    * communicating with the blobstore.
  31    */
  32   String createUploadUrl(String successPath);
  33
  34   /**
  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.
  38    *
  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
  42    * upload URL.
  43    *
  44    * @throws IllegalArgumentException If successPath was not valid.
  45    * @throws BlobstoreFailureException If an error occurred while
  46    * communicating with the blobstore.
  47    */
  48   String createUploadUrl(String successPath, UploadOptions uploadOptions);
  49
  50   /**
  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.
  57    *
  58    * <p>Range header will be automatically translated from the Content-Range
  59    * header in the response.
  60    *
  61    * @param blobKey Blob-key to serve in response.
  62    * @param response HTTP response object.
  63    *
  64    * @throws IOException If an I/O error occurred.
  65    * @throws IllegalStateException If {@code response} was already committed.
  66    */
  67   void serve(BlobKey blobKey, HttpServletResponse response) throws IOException;
  68
  69   /**
  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.
  76    *
  77    * <p>This method will set the App Engine blob range header to serve a
  78    * byte range of that blob.
  79    *
  80    * @param blobKey Blob-key to serve in response.
  81    * @param byteRange Byte range to serve in response.
  82    * @param response HTTP response object.
  83    *
  84    * @throws IOException If an I/O error occurred.
  85    * @throws IllegalStateException If {@code response} was already committed.
  86    */
  87   void serve(BlobKey blobKey, ByteRange byteRange, HttpServletResponse response)
  88       throws IOException;
  89
  90   /**
  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.
  97    *
  98    * <p>This method will set the App Engine blob range header to the content
  99    * specified.
 100    *
 101    * @param blobKey Blob-key to serve in response.
 102    * @param rangeHeader Content for range header to serve.
 103    * @param response HTTP response object.
 104    *
 105    * @throws IOException If an I/O error occurred.
 106    * @throws IllegalStateException If {@code response} was already committed.
 107    */
 108   void serve(BlobKey blobKey, String rangeHeader, HttpServletResponse response)
 109       throws IOException;
 110
 111   /**
 112    * Get byte range from the request.
 113    *
 114    * @param request HTTP request object.
 115    *
 116    * @return Byte range as parsed from the HTTP range header.  null if there is no header.
 117    *
 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
 121    * ranges.
 122    */
 123   ByteRange getByteRange(HttpServletRequest request);
 124
 125   /**
 126    * Permanently deletes the specified blobs.  Deleting unknown blobs is a
 127    * no-op.
 128    *
 129    * @throws BlobstoreFailureException If an error occurred while
 130    * communicating with the blobstore.
 131    */
 132   void delete(BlobKey... blobKeys);
 133
 134   /**
 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.
 139    *
 140    * @throws IllegalStateException If not called from a blob upload
 141    * callback request.
 142    *
 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.
 146    */
 147   @Deprecated Map<String, BlobKey> getUploadedBlobs(HttpServletRequest request);
 148
 149   /**
 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.
 154    *
 155    * @throws IllegalStateException If not called from a blob upload
 156    * callback request.
 157    * @see getBlobInfos, getFileInfos
 158    */
 159   Map<String, List<BlobKey>> getUploads(HttpServletRequest request);
 160
 161   /**
 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.
 166    *
 167    * @throws IllegalStateException If not called from a blob upload
 168    * callback request.
 169    * @see getFileInfos, getUploads
 170    * @since: 1.7.5
 171    */
 172   Map<String, List<BlobInfo>> getBlobInfos(HttpServletRequest request);
 173
 174   /**
 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.
 179    *
 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.
 183    *
 184    * @throws IllegalStateException If not called from a blob upload
 185    * callback request.
 186    * @see getBlobInfos, getUploads
 187    * @since: 1.7.5
 188    */
 189   Map<String, List<FileInfo>> getFileInfos(HttpServletRequest request);
 190
 191   /**
 192    * Get fragment from specified blob.
 193    *
 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.
 197    *
 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.
 203    */
 204   byte[] fetchData(BlobKey blobKey, long startIndex, long endIndex);
 205
 206   /**
 207    * Create a {@link BlobKey} for a Google Storage File.
 208    *
 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.
 211    *
 212    * <p>The created {@link BlobKey} will include a short lived access token using
 213    * the application's service account for authorization. Typically this token
 214    * will be valid for 60 minutes, and as a result the {@link BlobKey} that
 215    * is returned may be used across multiple requests. It is not recommended
 216    * that the {@link BlobKey} be stored in persistent storage as once the token
 217    * expires the {@link BlobKey} will no longer be valid.
 218    *
 219    * <p>The created {@link BlobKey} can then be used as a parameter in API methods
 220    * that can support objects in Google Storage, for example {@link serve}.
 221    *
 222    * @param filename The Google Storage filename. The filename must be in the
 223    * format "/gs/bucket_name/object_name".
 224    *
 225    * @throws IllegalArgumentException If the filename does not have the prefix
 226    * "/gs/".
 227    */
 228   BlobKey createGsBlobKey(String filename);
 229 }