org.opencadc.inventory.storage

Interface StorageAdapter

public interface StorageAdapter

The interface to storage implementations. Implementations may throw InvalidConfigException or StorageEngageException from the constructor.

Method Summary

Modifier and Type	Method and Description
void	abortTransaction(java.lang.String transactionID) Abort a transaction.
StorageMetadata	commitTransaction(java.lang.String transactionID) Commit a transaction.
void	delete(org.opencadc.inventory.StorageLocation storageLocation) Delete from storage the artifact identified by storageLocation.
void	get(org.opencadc.inventory.StorageLocation storageLocation, java.io.OutputStream dest) Get from storage the artifact identified by storageLocation.
void	get(org.opencadc.inventory.StorageLocation storageLocation, java.io.OutputStream dest, ByteRange byteRange) Get parts of a stored object specified by one or more byte ranges.
PutTransaction	getTransactionStatus(java.lang.String transactionID) Get current transaction status.
java.util.Iterator<StorageMetadata>	iterator() Iterator of items ordered by StorageLocation.
java.util.Iterator<StorageMetadata>	iterator(java.lang.String storageBucketPrefix) Iterate over StorageMetadata ordered by their StorageLocation.
StorageMetadata	put(NewArtifact newArtifact, java.io.InputStream source, java.lang.String transactionID) Write an artifact to storage.
PutTransaction	revertTransaction(java.lang.String transactionID) Revert a transaction to a previous state.
PutTransaction	startTransaction(java.net.URI artifactURI, java.lang.Long contentLength) Start a transaction for a PUT operation.

Method Detail

get

void get(org.opencadc.inventory.StorageLocation storageLocation,
         java.io.OutputStream dest)
  throws java.lang.InterruptedException,
         ca.nrc.cadc.net.ResourceNotFoundException,
         ca.nrc.cadc.io.ReadException,
         ca.nrc.cadc.io.WriteException,
         StorageEngageException,
         ca.nrc.cadc.net.TransientException

Get from storage the artifact identified by storageLocation.

Parameters:

storageLocation - the storage location containing storageID and storageBucket

dest - the destination stream

Throws:

java.lang.InterruptedException - if thread receives an interrupt

ca.nrc.cadc.net.ResourceNotFoundException - if the artifact could not be found

ca.nrc.cadc.io.ReadException - if the storage system failed to stream

ca.nrc.cadc.io.WriteException - if the client failed to stream

StorageEngageException - if the adapter failed to interact with storage

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred

get

void get(org.opencadc.inventory.StorageLocation storageLocation,
         java.io.OutputStream dest,
         ByteRange byteRange)
  throws java.lang.InterruptedException,
         ca.nrc.cadc.net.ResourceNotFoundException,
         ca.nrc.cadc.io.ReadException,
         ca.nrc.cadc.io.WriteException,
         StorageEngageException,
         ca.nrc.cadc.net.TransientException

Get parts of a stored object specified by one or more byte ranges.

Parameters:

storageLocation - the object to read

dest - the destination stream

byteRange - a single byte range to retrieve

Throws:

java.lang.InterruptedException - if thread receives an interrupt

ca.nrc.cadc.net.ResourceNotFoundException - if the artifact could not be found

ca.nrc.cadc.io.ReadException - if the storage system failed to stream

ca.nrc.cadc.io.WriteException - if the client failed to stream

StorageEngageException - if the adapter failed to interact with storage

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred

put

StorageMetadata put(NewArtifact newArtifact,
                    java.io.InputStream source,
                    java.lang.String transactionID)
             throws ca.nrc.cadc.io.ByteLimitExceededException,
                    java.lang.IllegalArgumentException,
                    ca.nrc.cadc.net.IncorrectContentChecksumException,
                    ca.nrc.cadc.net.IncorrectContentLengthException,
                    java.lang.InterruptedException,
                    ca.nrc.cadc.io.ReadException,
                    ca.nrc.cadc.io.WriteException,
                    StorageEngageException,
                    ca.nrc.cadc.net.TransientException

Write an artifact to storage. The returned storage location will be used for future get and delete calls. if the storage implementation overwrites a previously used StorageLocation, it must perform an atomic replace and leave the previously stored bytes intact if the put fails. The storage implementation may be designed to always write to a new storage location (e.g. generated unique storageID); in this case, the caller is responsible for keeping track of and cleaning up previously stored objects (the previous StorageLocation of an Artifact). The value of storageBucket in the returned StorageMetadata and StorageLocation can be used to retrieve batches of artifacts in some of the iterator signatures defined in this interface. Batches of artifacts can be listed by bucket in two of the iterator methods in this interface. if storageBucket is null then the caller will not be able perform bucket-based batch validation through the iterator methods.

Parameters:

newArtifact - The holds information about the incoming artifact. if the contentChecksum and contentLength are set, they will be used to validate the bytes received.

source - The stream from which to read.

transactionID - existing transactionID or null for auto-commit

Returns:

current StorageMetadata

Throws:

ca.nrc.cadc.io.ByteLimitExceededException - if content length exceeds internal limit

java.lang.IllegalArgumentException - if the newArtifact is invalid or the transaction does not exist

ca.nrc.cadc.net.IncorrectContentChecksumException - if the calculated checksum does not match the expected checksum as described in newArtifact.

ca.nrc.cadc.net.IncorrectContentLengthException - if the calculated length does not match the expected length as described in newArtifact.

java.lang.InterruptedException - if thread receives an interrupt

ca.nrc.cadc.io.ReadException - if the client failed to stream.

ca.nrc.cadc.io.WriteException - if the storage system failed to stream.

StorageEngageException - if the adapter failed to interact with storage.

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred.

delete

void delete(org.opencadc.inventory.StorageLocation storageLocation)
     throws ca.nrc.cadc.net.ResourceNotFoundException,
            java.io.IOException,
            java.lang.InterruptedException,
            StorageEngageException,
            ca.nrc.cadc.net.TransientException

Delete from storage the artifact identified by storageLocation.

Parameters:

storageLocation - Identifies the artifact to delete.

Throws:

ca.nrc.cadc.net.ResourceNotFoundException - if the artifact could not be found.

java.io.IOException - if an unrecoverable error occurred.

java.lang.InterruptedException - if thread receives an interrupt

StorageEngageException - if the adapter failed to interact with storage.

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred.

startTransaction

PutTransaction startTransaction(java.net.URI artifactURI,
                                java.lang.Long contentLength)
                         throws StorageEngageException,
                                ca.nrc.cadc.net.TransientException

Start a transaction for a PUT operation.

Parameters:

artifactURI - artifact identifier

contentLength - complete length of the data

Returns:

transaction status

Throws:

StorageEngageException - if the adapter failed to interact with storage

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred

revertTransaction

PutTransaction revertTransaction(java.lang.String transactionID)
                          throws java.lang.IllegalArgumentException,
                                 StorageEngageException,
                                 ca.nrc.cadc.net.TransientException,
                                 java.lang.UnsupportedOperationException

Revert a transaction to a previous state.

Parameters:

transactionID - existing transaction ID

Returns:

final storage metadata

Throws:

java.lang.IllegalArgumentException - if the specified transaction does not exist

StorageEngageException - if the adapter failed to interact with storage

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred

java.lang.UnsupportedOperationException - if the transaction cannot be reverted

commitTransaction

StorageMetadata commitTransaction(java.lang.String transactionID)
                           throws java.lang.IllegalArgumentException,
                                  StorageEngageException,
                                  ca.nrc.cadc.net.TransientException

Commit a transaction.

Parameters:

transactionID - existing transaction ID

Returns:

current transaction status

Throws:

java.lang.IllegalArgumentException - if the specified transaction does not exist

StorageEngageException - if the adapter failed to interact with storage

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred

abortTransaction

void abortTransaction(java.lang.String transactionID)
               throws java.lang.IllegalArgumentException,
                      StorageEngageException,
                      ca.nrc.cadc.net.TransientException

Abort a transaction.

Parameters:

transactionID - existing transaction ID

Throws:

java.lang.IllegalArgumentException - if the specified transaction does not exist

StorageEngageException - if the adapter failed to interact with storage

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred

getTransactionStatus

PutTransaction getTransactionStatus(java.lang.String transactionID)
                             throws java.lang.IllegalArgumentException,
                                    StorageEngageException,
                                    ca.nrc.cadc.net.TransientException

Get current transaction status.

Parameters:

transactionID - existing transaction ID

Returns:

transaction status with current storage metadata for bytes received and stored

Throws:

java.lang.IllegalArgumentException - if the specified transaction does not exist

StorageEngageException - if the adapter failed to interact with storage

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred

iterator

java.util.Iterator<StorageMetadata> iterator()
                                      throws StorageEngageException,
                                             ca.nrc.cadc.net.TransientException

Iterator of items ordered by StorageLocation.

Returns:

An iterator over an ordered list of items in storage.

Throws:

StorageEngageException - if the adapter failed to interact with storage.

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred.

iterator

java.util.Iterator<StorageMetadata> iterator(java.lang.String storageBucketPrefix)
                                      throws StorageEngageException,
                                             ca.nrc.cadc.net.TransientException

Iterate over StorageMetadata ordered by their StorageLocation.

Parameters:

storageBucketPrefix - null, partial, or complete storageBucket string

Returns:

iterator over StorageMetadata sorted by StorageLocation

Throws:

StorageEngageException - if the adapter failed to interact with storage.

ca.nrc.cadc.net.TransientException - if an unexpected, temporary exception occurred.