| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.jclouds.glacier; |
| |
| import java.io.Closeable; |
| import java.net.URI; |
| import java.util.Map; |
| |
| import org.jclouds.glacier.domain.ArchiveMetadataCollection; |
| import org.jclouds.glacier.domain.JobMetadata; |
| import org.jclouds.glacier.domain.JobRequest; |
| import org.jclouds.glacier.domain.MultipartUploadMetadata; |
| import org.jclouds.glacier.domain.PaginatedJobCollection; |
| import org.jclouds.glacier.domain.PaginatedMultipartUploadCollection; |
| import org.jclouds.glacier.domain.PaginatedVaultCollection; |
| import org.jclouds.glacier.domain.VaultMetadata; |
| import org.jclouds.glacier.options.PaginationOptions; |
| import org.jclouds.glacier.util.ContentRange; |
| import org.jclouds.io.Payload; |
| |
| import com.google.common.hash.HashCode; |
| |
| /** |
| * Provides access to Amazon Glacier resources via their REST API. |
| * <p/> |
| * |
| * @see GlacierAsyncClient |
| * @see <a href="http://aws.amazon.com/documentation/glacier/" /> |
| */ |
| public interface GlacierClient extends Closeable { |
| |
| /** |
| * Creates a new vault to store archives. An account can only create up to 1,000 vaults per region, but each vault |
| * can contain an unlimited number of archives. |
| * |
| * @param vaultName |
| * A name for the Vault being created. |
| * @return A reference to an URI pointing to the resource created. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-vault-put.html" /> |
| */ |
| URI createVault(String vaultName); |
| |
| /** |
| * Deletes a vault. Vaults can only be deleted if there are no archives in the vault in the last inventory computed |
| * by Amazon, and there are no new uploads after it. This is very important, as Amazon only updates inventories once |
| * every 24 hours. |
| * |
| * @param vaultName |
| * Name of the Vault being deleted. |
| * @return False if the vault was not empty and therefore not deleted, true otherwise. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-vault-delete.html" /> |
| */ |
| boolean deleteVault(String vaultName); |
| |
| /** |
| * Retrieves the metadata for a vault. The response include information like the vault ARN, the creation data, the |
| * number of archives contained within the vault and total size of these archives. The number of archives and |
| * the total size is based on the last inventory computed by amazon and the information may be outdated. |
| * |
| * @param vaultName |
| * Name of the Vault being described. |
| * @return A VaultMetadata object containing all the information relevant to the vault if the vault exists, |
| * null otherwise. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-vault-get.html" /> |
| */ |
| VaultMetadata describeVault(String vaultName); |
| |
| /** |
| * Lists vaults according to specified options. By default this operation returns up to 1,000 vaults. |
| * |
| * @param options |
| * Options used for pagination. |
| * @return A PaginatedVaultCollection object containing the list of vaults. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-vaults-get.html" /> |
| */ |
| PaginatedVaultCollection listVaults(PaginationOptions options); |
| |
| /** |
| * @see GlacierClient#listVaults(PaginationOptions) |
| */ |
| PaginatedVaultCollection listVaults(); |
| |
| /** |
| * Stores an archive in a vault. Archives up to 4GB in size can be uploaded using this operation. Once the archive |
| * is uploaded it is immutable, this means that archive or its description cannot be modified. Except for the |
| * optional description Glacier does not support additional metadata. |
| * |
| * @param vaultName |
| * Name of the Vault where the archive is being stored. |
| * @param payload |
| * Payload to be uploaded. |
| * @param description |
| * Description for the archive. |
| * @return A String containing the Archive identifier in Amazon Glacier. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-archive-post.html" /> |
| */ |
| String uploadArchive(String vaultName, Payload payload, String description); |
| |
| /** |
| * @see GlacierClient#uploadArchive(String, org.jclouds.io.Payload, String) |
| */ |
| String uploadArchive(String vaultName, Payload payload); |
| |
| /** |
| * Deletes an archive from a vault. Be aware that after deleting an archive it may still be listed in the |
| * inventories until amazon compute a new inventory. |
| * |
| * @param vaultName |
| * Name of the Vault where the archive is stored. |
| * @param archiveId |
| * Amazon Glacier archive identifier. |
| * @return False if the archive was not deleted, true otherwise. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-archive-delete.html" /> |
| */ |
| boolean deleteArchive(String vaultName, String archiveId); |
| |
| /** |
| * Starts a new multipart upload. Using a multipart upload you can upload archives up to 40,000GB (10,000 parts, |
| * 4GB each). The part size must be a megabyte multiplied by a power of 2 and every part must be the same size |
| * except the last one, which can have a smaller size. In addition, you don't need to know the archive size to |
| * initiate a multipart upload. |
| * |
| * @param vaultName |
| * Name of the Vault where the archive is going to be stored. |
| * @param partSizeInMB |
| * Content size for each part. |
| * @param description |
| * The archive description. |
| * @return The Multipart Upload Id. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-multipart-initiate-upload.html" /> |
| */ |
| String initiateMultipartUpload(String vaultName, long partSizeInMB, String description); |
| |
| /** |
| * @see GlacierClient#initiateMultipartUpload(String, long, String) |
| */ |
| String initiateMultipartUpload(String vaultName, long partSizeInMB); |
| |
| /** |
| * Uploads one of the multipart upload parts. The part size has to match the one specified in the multipart upload |
| * request, and the range needs to be aligned. In addition, to ensure that the data is not corrupted, the tree hash |
| * and the linear hash are checked by Glacier. |
| * |
| * @param vaultName |
| * Name of the Vault where the archive is going to be stored. |
| * @param uploadId |
| * Multipart upload identifier. |
| * @param range |
| * The content range that this part is uploading. |
| * @param payload |
| * Content for this part. |
| * @return Tree-hash of the payload calculated by Amazon. This hash needs to be stored to complete the multipart |
| * upload. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-upload-part.html" /> |
| */ |
| HashCode uploadPart(String vaultName, String uploadId, ContentRange range, Payload payload); |
| |
| /** |
| * Completes the multipart upload. After uploading all the parts this operation should be called to inform Glacier. |
| * Again, the checksum and the ranges of the whole archive will be computed to verify the data. |
| * |
| * @param vaultName |
| * Name of the Vault where the archive is going to be stored. |
| * @param uploadId |
| * Multipart upload identifier. |
| * @param hashes |
| * Map containing the pairs partnumber-treehash of each uploaded part. |
| * @param archiveSize |
| * Size of the complete archive. |
| * @return A String containing the Archive identifier in Amazon Glacier. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-multipart-complete-upload.html" /> |
| */ |
| String completeMultipartUpload(String vaultName, String uploadId, Map<Integer, HashCode> hashes, long archiveSize); |
| |
| /** |
| * Aborts the multipart upload. Once aborted, you cannot upload any more parts to it. |
| * |
| * @param vaultName |
| * Name of the Vault where the archive was going to be stored. |
| * @param uploadId |
| * Multipart upload identifier. |
| * @return True if the multipart upload was aborted, false otherwise. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-multipart-abort-upload.html" /> |
| */ |
| boolean abortMultipartUpload(String vaultName, String uploadId); |
| |
| /** |
| * Lists the multipart upload parts. You can list the parts of an ongoing multipart upload at any time. By default |
| * it returns up to 1,000 uploaded parts, but you can control this using the request options. |
| * |
| * @param vaultName |
| * Name of the Vault where the archive is going to be stored. |
| * @param uploadId |
| * Multipart upload identifier. |
| * @param options |
| * Options used for pagination. |
| * @return A MultipartUploadMetadata, containing an iterable part list with a marker. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-multipart-list-parts.html" /> |
| */ |
| MultipartUploadMetadata listParts(String vaultName, String uploadId, PaginationOptions options); |
| |
| /** |
| * @see GlacierClient#listParts(String, String, org.jclouds.glacier.options.PaginationOptions) |
| */ |
| MultipartUploadMetadata listParts(String vaultName, String uploadId); |
| |
| /** |
| * Lists the ongoing multipart uploads in a vault. By default, this operation returns up to 1,000 multipart uploads. |
| * You can control this using the request options. |
| * |
| * @param vaultName |
| * Name of the Vault where the archive is going to be stored. |
| * @param options |
| * Options used for pagination. |
| * @return A PaginatedMultipartUploadCollection, containing an iterable multipart upload list with a marker. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-multipart-list-uploads.html" /> |
| */ |
| PaginatedMultipartUploadCollection listMultipartUploads(String vaultName, PaginationOptions options); |
| |
| /** |
| * @see GlacierClient#listMultipartUploads(String, org.jclouds.glacier.options.PaginationOptions) |
| */ |
| PaginatedMultipartUploadCollection listMultipartUploads(String vaultName); |
| |
| /** |
| * Initiates a job. The job can be an inventory retrieval or an archive retrieval. Once the job is started the |
| * estimated time to complete it is ~4 hours. |
| * |
| * @param vaultName |
| * Name of the target Vault for the job. |
| * @param job |
| * JobRequest instance with the concrete request. |
| * @return The job identifier. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-initiate-job-post.html" /> |
| */ |
| String initiateJob(String vaultName, JobRequest job); |
| |
| /** |
| * Retrieves information about an ongoing job. Among the information you will find the initiation date, the user who |
| * initiated the job or the status message. |
| * |
| * @param vaultName |
| * Name of the target Vault for the job. |
| * @param jobId |
| * Job identifier. |
| * @return The job metadata if the job exists in the vault, null otherwise. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-describe-job-get.html" /> |
| */ |
| JobMetadata describeJob(String vaultName, String jobId); |
| |
| /** |
| * Lists the ongoing jobs and the recently finished jobs for a vault. By default this operation returns up to |
| * 1,000 jobs in the response, but you can control this using the request options. Note that this operation also |
| * returns the recently finished jobs and you can still download their output. |
| * |
| * @param vaultName |
| * Name of the target Vault. |
| * @param options |
| * Options used for pagination |
| * @return A PaginatedJobCollection, containing an iterable job list with a marker. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-jobs-get.html" /> |
| */ |
| PaginatedJobCollection listJobs(String vaultName, PaginationOptions options); |
| |
| /** |
| * Lists jobs. |
| */ |
| PaginatedJobCollection listJobs(String vaultName); |
| |
| /** |
| * Gets the raw job output of any kind of job. You can download the job output within the 24 hour period after |
| * Glacier comlpetes a job. |
| * |
| * @param vaultName |
| * Name of the target Vault for the job. |
| * @param jobId |
| * Job identifier. |
| * @param range |
| * The range of bytes to retrieve from the output. |
| * @return The content data. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-job-output-get.html" /> |
| */ |
| Payload getJobOutput(String vaultName, String jobId, ContentRange range); |
| |
| /** |
| * Downloads the output of an archive retrieval job. |
| * |
| * @param vaultName |
| * Name of the target Vault for the job. |
| * @param jobId |
| * Job identifier. |
| * @return The content data. |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-job-output-get.html" /> |
| */ |
| Payload getJobOutput(String vaultName, String jobId); |
| |
| /** |
| * Gets the job output for the given job ID. The job must be an inventory retrieval, otherwise this operation will |
| * fail. This operation will parse the job output and build a collection of ArchiveMetadata. |
| * |
| * @param vaultName |
| * Name of the target Vault for the job. |
| * @param jobId |
| * Job identifier. |
| * @return The ArchiveMetadata collection |
| * @see <a href="http://docs.aws.amazon.com/amazonglacier/latest/dev/api-job-output-get.html" /> |
| */ |
| ArchiveMetadataCollection getInventoryRetrievalOutput(String vaultName, String jobId); |
| } |