com.amazonaws.services.glacier.model

Class InitiateJobRequest

java.lang.Object

com.amazonaws.AmazonWebServiceRequest

com.amazonaws.services.glacier.model.InitiateJobRequest

All Implemented Interfaces:

Serializable

public class InitiateJobRequest
extends AmazonWebServiceRequest
implements Serializable

Container for the parameters to the InitiateJob operation.

This operation initiates a job of the specified type. In this release, you can initiate a job to retrieve either an archive or a vault inventory (a list of archives in a vault).

Retrieving data from Amazon Glacier is a two-step process:

1. Initiate a retrieval job.

2. After the job completes, download the bytes.

The retrieval request is executed asynchronously. When you initiate a retrieval job, Amazon Glacier creates a job and returns a job ID in the response. When Amazon Glacier completes the job, you can get the job output (archive or inventory data). For information about getting job output, see GetJobOutput operation.

The job must complete before you can get its output. To determine when a job is complete, you have the following options:

• Use Amazon SNS Notification You can specify an Amazon Simple Notification Service (Amazon SNS) topic to which Amazon Glacier can post a notification after the job is completed. You can specify an SNS topic per job request. The notification is sent only after Amazon Glacier completes the job. In addition to specifying an SNS topic per job request, you can configure vault notifications for a vault so that job notifications are always sent. For more information, see SetVaultNotifications.

• Get job details You can make a DescribeJob request to obtain job status information while a job is in progress. However, it is more efficient to use an Amazon SNS notification to determine when a job is complete.

NOTE: The information you get via notification is same that you get by calling DescribeJob.

If for a specific event, you add both the notification configuration on the vault and also specify an SNS topic in your initiate job request, Amazon Glacier sends both notifications. For more information, see SetVaultNotifications.

An AWS account has full permission to perform all operations (actions). However, AWS Identity and Access Management (IAM) users don't have any permissions by default. You must grant them explicit permission to perform specific actions. For more information, see Access Control Using AWS Identity and Access Management (IAM) .

About the Vault Inventory

Amazon Glacier prepares an inventory for each vault periodically, every 24 hours. When you initiate a job for a vault inventory, Amazon Glacier returns the last inventory for the vault. The inventory data you get might be up to a day or two days old. Also, the initiate inventory job might take some time to complete before you can download the vault inventory. So you do not want to retrieve a vault inventory for each vault operation. However, in some scenarios, you might find the vault inventory useful. For example, when you upload an archive, you can provide an archive description but not an archive name. Amazon Glacier provides you a unique archive ID, an opaque string of characters. So, you might maintain your own database that maps archive names to their corresponding Amazon Glacier assigned archive IDs. You might find the vault inventory useful in the event you need to reconcile information in your database with the actual vault inventory.

Range Inventory Retrieval

You can limit the number of inventory items retrieved by filtering on the archive creation date or by setting a limit.

Filtering by Archive Creation Date

You can retrieve inventory items for archives created between StartDate and EndDate by specifying values for these parameters in the InitiateJob request. Archives created on or after the StartDate and before the EndDate will be returned. If you only provide the StartDate without the EndDate , you will retrieve the inventory for all archives created on or after the StartDate . If you only provide the EndDate without the StartDate , you will get back the inventory for all archives created before the EndDate .

Limiting Inventory Items per Retrieval

You can limit the number of inventory items returned by setting the Limit parameter in the InitiateJob request. The inventory job output will contain inventory items up to the specified Limit . If there are more inventory items available, the result is paginated. After a job is complete you can use the DescribeJob operation to get a marker that you use in a subsequent InitiateJob request. The marker will indicate the starting point to retrieve the next set of inventory items. You can page through your entire inventory by repeatedly making InitiateJob requests with the marker from the previous DescribeJob output, until you get a marker from DescribeJob that returns null, indicating that there are no more inventory items available.

You can use the Limit parameter together with the date range parameters.

About Ranged Archive Retrieval

You can initiate an archive retrieval for the whole archive or a range of the archive. In the case of ranged archive retrieval, you specify a byte range to return or the whole archive. The range specified must be megabyte (MB) aligned, that is the range start value must be divisible by 1 MB and range end value plus 1 must be divisible by 1 MB or equal the end of the archive. If the ranged archive retrieval is not megabyte aligned, this operation returns a 400 response. Furthermore, to ensure you get checksum values for data you download using Get Job Output API, the range must be tree hash aligned.

An AWS account has full permission to perform all operations (actions). However, AWS Identity and Access Management (IAM) users don't have any permissions by default. You must grant them explicit permission to perform specific actions. For more information, see Access Control Using AWS Identity and Access Management (IAM) .

For conceptual information and the underlying REST API, go to Initiate a Job and Downloading a Vault Inventory

See Also:

AmazonGlacier.initiateJob(InitiateJobRequest), Serialized Form

Field Summary

Fields inherited from class com.amazonaws.AmazonWebServiceRequest

NOOP

Constructor Summary

Constructors

Constructor and Description
InitiateJobRequest() Default constructor for a new InitiateJobRequest object.
InitiateJobRequest(String vaultName, JobParameters jobParameters) Constructs a new InitiateJobRequest object.
InitiateJobRequest(String accountId, String vaultName, JobParameters jobParameters) Constructs a new InitiateJobRequest object.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(Object obj)
String	getAccountId() The AccountId is the AWS Account ID.
JobParameters	getJobParameters() Provides options for specifying job information.
String	getVaultName() The name of the vault.
int	hashCode()
void	setAccountId(String accountId) The AccountId is the AWS Account ID.
void	setJobParameters(JobParameters jobParameters) Provides options for specifying job information.
void	setVaultName(String vaultName) The name of the vault.
String	toString() Returns a string representation of this object; useful for testing and debugging.
InitiateJobRequest	withAccountId(String accountId) The AccountId is the AWS Account ID.
InitiateJobRequest	withJobParameters(JobParameters jobParameters) Provides options for specifying job information.
InitiateJobRequest	withVaultName(String vaultName) The name of the vault.

Methods inherited from class com.amazonaws.AmazonWebServiceRequest

copyPrivateRequestParameters, getCustomRequestHeaders, getGeneralProgressListener, getReadLimit, getRequestClientOptions, getRequestCredentials, getRequestMetricCollector, putCustomRequestHeader, setGeneralProgressListener, setRequestCredentials, setRequestMetricCollector, withGeneralProgressListener, withRequestMetricCollector

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

InitiateJobRequest

public InitiateJobRequest()

Default constructor for a new InitiateJobRequest object. Callers should use the setter or fluent setter (with...) methods to initialize this object after creating it.

InitiateJobRequest

public InitiateJobRequest(String vaultName,
                  JobParameters jobParameters)

Constructs a new InitiateJobRequest object. Callers should use the setter or fluent setter (with...) methods to initialize any additional object members.

Parameters:

vaultName - The name of the vault.

jobParameters - Provides options for specifying job information.

InitiateJobRequest

public InitiateJobRequest(String accountId,
                  String vaultName,
                  JobParameters jobParameters)

Constructs a new InitiateJobRequest object. Callers should use the setter or fluent setter (with...) methods to initialize any additional object members.

Parameters:

accountId - The AccountId is the AWS Account ID. You can specify either the AWS Account ID or optionally a '-', in which case Amazon Glacier uses the AWS Account ID associated with the credentials used to sign the request. If you specify your Account ID, do not include hyphens in it.

vaultName - The name of the vault.

jobParameters - Provides options for specifying job information.

Method Detail

getAccountId

public String getAccountId()

The AccountId is the AWS Account ID. You can specify either the AWS Account ID or optionally a '-', in which case Amazon Glacier uses the AWS Account ID associated with the credentials used to sign the request. If you specify your Account ID, do not include hyphens in it.

Returns:

The AccountId is the AWS Account ID. You can specify either the AWS Account ID or optionally a '-', in which case Amazon Glacier uses the AWS Account ID associated with the credentials used to sign the request. If you specify your Account ID, do not include hyphens in it.

setAccountId

public void setAccountId(String accountId)

The AccountId is the AWS Account ID. You can specify either the AWS Account ID or optionally a '-', in which case Amazon Glacier uses the AWS Account ID associated with the credentials used to sign the request. If you specify your Account ID, do not include hyphens in it.

Parameters:

accountId - The AccountId is the AWS Account ID. You can specify either the AWS Account ID or optionally a '-', in which case Amazon Glacier uses the AWS Account ID associated with the credentials used to sign the request. If you specify your Account ID, do not include hyphens in it.

withAccountId

public InitiateJobRequest withAccountId(String accountId)

The AccountId is the AWS Account ID. You can specify either the AWS Account ID or optionally a '-', in which case Amazon Glacier uses the AWS Account ID associated with the credentials used to sign the request. If you specify your Account ID, do not include hyphens in it.

Returns a reference to this object so that method calls can be chained together.

Parameters:

accountId - The AccountId is the AWS Account ID. You can specify either the AWS Account ID or optionally a '-', in which case Amazon Glacier uses the AWS Account ID associated with the credentials used to sign the request. If you specify your Account ID, do not include hyphens in it.

Returns:

A reference to this updated object so that method calls can be chained together.

getVaultName

public String getVaultName()

The name of the vault.

Returns:

The name of the vault.

setVaultName

public void setVaultName(String vaultName)

The name of the vault.

Parameters:

vaultName - The name of the vault.

withVaultName

public InitiateJobRequest withVaultName(String vaultName)

The name of the vault.

Returns a reference to this object so that method calls can be chained together.

Parameters:

vaultName - The name of the vault.

Returns:

A reference to this updated object so that method calls can be chained together.

getJobParameters

public JobParameters getJobParameters()

Provides options for specifying job information.

Returns:

Provides options for specifying job information.

setJobParameters

public void setJobParameters(JobParameters jobParameters)

Provides options for specifying job information.

Parameters:

jobParameters - Provides options for specifying job information.

withJobParameters

public InitiateJobRequest withJobParameters(JobParameters jobParameters)

Provides options for specifying job information.

Returns a reference to this object so that method calls can be chained together.

Parameters:

jobParameters - Provides options for specifying job information.

Returns:

A reference to this updated object so that method calls can be chained together.

toString

public String toString()

Returns a string representation of this object; useful for testing and debugging.

Overrides:

toString in class Object

Returns:

A string representation of this object.

See Also:

Object.toString()

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object