Interface BlobstoreService (2.0.0)

public interface BlobstoreService

BlobstoreService allows you to manage the creation and serving of large, immutable blobs to users.

Static Fields

MAX_BLOB_FETCH_SIZE

public static final int MAX_BLOB_FETCH_SIZE
Field Value
Type Description
int

Methods

createGsBlobKey(String filename)

public abstract BlobKey createGsBlobKey(String filename)

Create a BlobKey for a Google Storage File.

The existence of the file represented by filename is not checked, hence a BlobKey can be created for a file that does not currently exist.

You can safely persist the BlobKey generated by this function.

The created BlobKey can then be used as a parameter in API methods that can support objects in Google Storage, for example serve.

Parameter
Name Description
filename String

The Google Storage filename. The filename must be in the format "/gs/bucket_name/object_name".
Returns
Type Description
BlobKey

createUploadUrl(String successPath)

public abstract String createUploadUrl(String successPath)

Create an absolute URL that can be used by a user to asynchronously upload a large blob. Upon completion of the upload, a callback is made to the specified URL.

Parameter
Name Description
successPath String

A relative URL which will be invoked after the user successfully uploads a blob. Must start with a "/", and must be URL-encoded.
Returns
Type Description
String

createUploadUrl(String successPath, UploadOptions uploadOptions)

public abstract String createUploadUrl(String successPath, UploadOptions uploadOptions)

Create an absolute URL that can be used by a user to asynchronously upload a large blob. Upon completion of the upload, a callback is made to the specified URL.

Parameters
Name Description
successPath String

A relative URL which will be invoked after the user successfully uploads a blob. Must start with a "/".
uploadOptions UploadOptions

Specific options applicable only for this upload URL.
Returns
Type Description
String

delete(BlobKey[] blobKeys)

public abstract void delete(BlobKey[] blobKeys)

Permanently deletes the specified blobs. Deleting unknown blobs is a no-op.

Parameter
Name Description
blobKeys BlobKey[]

fetchData(BlobKey blobKey, long startIndex, long endIndex)

public abstract byte[] fetchData(BlobKey blobKey, long startIndex, long endIndex)

Get fragment from specified blob.

Parameters
Name Description
blobKey BlobKey

Blob-key from which to fetch data.
startIndex long

Start index of data to fetch.
endIndex long

End index (inclusive) of data to fetch.
Returns
Type Description
byte[]

getBlobInfos(HttpServletRequest request)

public abstract Map<String,List<BlobInfo>> getBlobInfos(HttpServletRequest request)

Returns the BlobInfo for any files that were uploaded, keyed by the upload form "name" field. This method should only be called from within a request served by the destination of a #createUploadUrl call. See Also: #getUploads, #getFileInfos

Parameter
Name Description
request jakarta.servlet.http.HttpServletRequest
Returns
Type Description
Map<String,List<BlobInfo>>

getByteRange(HttpServletRequest request)

public abstract @Nullable ByteRange getByteRange(HttpServletRequest request)

Get byte range from the request.

Parameter
Name Description
request jakarta.servlet.http.HttpServletRequest

HTTP request object.
Returns
Type Description
@org.checkerframework.checker.nullness.qual.Nullable com.google.appengine.api.blobstore.ByteRange

Byte range as parsed from the HTTP range header. null if there is no header.

getFileInfos(HttpServletRequest request)

public abstract Map<String,List<FileInfo>> getFileInfos(HttpServletRequest request)

Returns the FileInfo for any files that were uploaded, keyed by the upload form "name" field. This method should only be called from within a request served by the destination of a #createUploadUrl call.

Prefer this method over #getBlobInfos or #getUploads if uploading files to Cloud Storage, as the FileInfo contains the name of the created filename in Cloud Storage. See Also: #getUploads, #getBlobInfos

Parameter
Name Description
request jakarta.servlet.http.HttpServletRequest
Returns
Type Description
Map<String,List<FileInfo>>

getUploadedBlobs(HttpServletRequest request) (deprecated)

public abstract Map<String,BlobKey> getUploadedBlobs(HttpServletRequest request)

Deprecated. Use #getUploads instead. Note that getUploadedBlobs does not handle cases where blobs have been uploaded using the multiple="true" attribute of the file input form element.

Returns the BlobKey for any files that were uploaded, keyed by the upload form "name" field.

This method should only be called from within a request served by the destination of a createUploadUrl call.

Parameter
Name Description
request jakarta.servlet.http.HttpServletRequest
Returns
Type Description
Map<String,BlobKey>

getUploads(HttpServletRequest request)

public abstract Map<String,List<BlobKey>> getUploads(HttpServletRequest request)

Returns the BlobKey for any files that were uploaded, keyed by the upload form "name" field. This method should only be called from within a request served by the destination of a #createUploadUrl call. See Also: #getFileInfos, #getBlobInfos

Parameter
Name Description
request jakarta.servlet.http.HttpServletRequest
Returns
Type Description
Map<String,List<BlobKey>>

serve(BlobKey blobKey, @Nullable ByteRange byteRange, HttpServletResponse response)

public abstract void serve(BlobKey blobKey, @Nullable ByteRange byteRange, HttpServletResponse response)

Arrange for the specified blob to be served as the response content for the current request. response should be uncommitted before invoking this method, and should be assumed to be committed after invoking it. Any content written before calling this method will be ignored. You may, however, append custom headers before or after calling this method.

This method will set the App Engine blob range header to serve a byte range of that blob.

Parameters
Name Description
blobKey BlobKey

Blob-key to serve in response.
byteRange @org.checkerframework.checker.nullness.qual.Nullable com.google.appengine.api.blobstore.ByteRange

Byte range to serve in response.
response jakarta.servlet.http.HttpServletResponse

HTTP response object.
Exceptions
Type Description
IOException

If an I/O error occurred.

serve(BlobKey blobKey, HttpServletResponse response)

public abstract void serve(BlobKey blobKey, HttpServletResponse response)

Arrange for the specified blob to be served as the response content for the current request. response should be uncommitted before invoking this method, and should be assumed to be committed after invoking it. Any content written before calling this method will be ignored. You may, however, append custom headers before or after calling this method.

Range header will be automatically translated from the Content-Range header in the response.

Parameters
Name Description
blobKey BlobKey

Blob-key to serve in response.
response jakarta.servlet.http.HttpServletResponse

HTTP response object.
Exceptions
Type Description
IOException

If an I/O error occurred.

serve(BlobKey blobKey, String rangeHeader, HttpServletResponse response)

public abstract void serve(BlobKey blobKey, String rangeHeader, HttpServletResponse response)

Arrange for the specified blob to be served as the response content for the current request. response should be uncommitted before invoking this method, and should be assumed to be committed after invoking it. Any content written before calling this method will be ignored. You may, however, append custom headers before or after calling this method.

This method will set the App Engine blob range header to the content specified.

Parameters
Name Description
blobKey BlobKey

Blob-key to serve in response.
rangeHeader String

Content for range header to serve.
response jakarta.servlet.http.HttpServletResponse

HTTP response object.
Exceptions
Type Description
IOException

If an I/O error occurred.