@UESComponent public interface UESStorageService
Usage constraints:
The methods of this interface throw exception UESStorageServiceRTException or one of its subclasses. Type of subclasses can be different according to implementation.
API status: under development (incompatible changes might appear between releases).
| Modifier and Type | Method and Description |
|---|---|
UESBucket |
createBucket(java.lang.String bucketId)
Creates a new bucket.
|
void |
deleteBucket(java.lang.String bucketId)
Deletes a bucket.
|
void |
deleteObject(java.lang.String bucketId,
Deletes an object from a bucket.
|
boolean |
doesBucketExist(java.lang.String bucketId)
Checks if the specified bucket exists.
|
java.util.List<UESBucket> |
getBucketList()
Lists all buckets belonging to the service user.
|
UESObjectListing |
getNextObjectList(java.lang.String bucketId,
Provides an easy way to continue a truncated object listing and retrieve the next page of results.
|
UESStorageObject |
getObject(java.lang.String bucketId,
Returns an object representing the details and data of an item in a service.
|
UESObjectListing |
getObjectList(java.lang.String bucketId,
Returns a list of summary information about the objects in the specified bucket.
|
UESStorageObject |
putObject(java.lang.String bucketId,
Puts an object inside an existing bucket, creating a new object or overwriting an existing one
with the same identifier.
|
UESStorageServiceRTException - If storage service fails to get the list of buckets.bucketId - Identifier of the bucket.true if the specified bucket exists in UDDS; the value false if there
is no bucket in UDDS with that name.UESStorageServiceRTException - If any errors occurred while checking bucket existence.bucketId - Identifier of the new bucket. Valid characters for bucket
ID are: small letters from english alphabet (a-z), digits (0-9), slash (/)
and dash (-). Bucket ID cannot ends with dash.UESStorageServiceRTException - If the bucket cannot be created for some reason.bucketId - Identifier of the bucket to delete.UESStorageServiceRTException - If the bucket cannot be deleted.bucketId - Identifier of an existing bucket.object - The object containing all information that will be written to the storage. At
very least this object must be valid. It must contain valid object ID. The
rules for object ID are described in UESStorageObject.setID(String).
Beyond that it may contain: an input stream with the object's data content and metadata.
Note: It is very important to set the object's Content-Length to match the size of the data input stream when possible, as this can remove the need to read data into memory to determine its size.
UESStorageServiceRTException - If the object cannot be put in the bucket (e.g. the bucket
does not exist).bucketId - The identifier of the bucket containing the object to be deleted.objectId - The identifier representing the object.UESStorageServiceRTException - If the object cannot be deleted from the bucket.
Because buckets can contain a virtually unlimited number of objects, the complete results of a list query can be
extremely large. To manage large result sets, UDDS uses pagination to split them into multiple sublists. Always
check the UESObjectListing#isTruncated() method to see if the returned listing is complete or if additional
calls are needed to get more results. Alternatively, use the UESStorageService.getNextObjectList(String, UESObjectListing)
method as an easy way to get the next page of object listings.
Calling UESObjectListingCriteria.setDelimiter(String) sets the delimiter, allowing groups of keys that
share the delimiter-terminated prefix to be included in the returned listing. This allows applications to organize
and browse their keys hierarchically, similar to how a file system organizes files into directories. These common
prefixes can be retrieved through the UESObjectListing.getCommonPrefixes() method.
For example, consider a bucket that contains the following keys:
If calling getObjectList with a prefix value of "abc/" and a delimiter value of "/" on this bucket,
a UESObjectListing is returned that contains three objects ("abc/file1.txt", "abc/file2.txt",
"abc/file3.txt") and one entry in the common prefixes list ("abc/xyz/"). To see deeper into the virtual hierarchy,
make another call to getObjectList setting the prefix parameter to any interesting common
prefix to list the individual keys under that prefix.
bucketId - The identifier of the the bucket whose contents will be listed.criteria - The criteria for listing the objects in a specified bucket.UESStorageServiceRTException - If the list cannot be retrieved.#getNextObjectList(String, UESObjectListing)}
To continue the object listing and retrieve the next page of results, call the initial ObjectListing
from one the getObjectList method. If truncated (indicated when UESObjectListing.isTrunkated()
returns true), pass the UESObjectListing back into this method in order to retrieve the
next page of results. Continue using this method to retrieve more results until the returned
UESObjectListing indicates that it is not truncated.
bucketId - The identifier of the the bucket whose contents will be listed.previousListing - The previous truncated UESObjectListing. If a non-truncated
UESObjectListing is passed in, an empty UESObjectListing is returned without
ever contacting the underlying data storage.UESObjectListing results, beginning immediately after the last result in the
specified previous UESObjectListing.UESStorageServiceRTException - If the list cannot be retrieved.#getObjectList(String, UESObjectListingCriteria)}Important: It is the caller's responsibility to close the object's data input stream. The data stream should be consumed and closed as soon as is practical as network connections may be held open until the streams are closed. Excessive unclosed streams can lead to connection starvation.
bucketId - The identifier of the bucket containing the object.objectId - The identifier of the object.UESStorageServiceRTException - If the object cannot be retrieved.