/* $HeadURL:: $
* $Id$
*
* Copyright (c) 2009-2010 DuraSpace
* http://duraspace.org
*
* In collaboration with Topaz Inc.
* http://www.topazproject.org
*
* Licensed 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.akubraproject;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.URI;
import java.util.Map;
/**
* Interface to abstract the idea of a blob in the blob store.
*
* @author Chris Wilper
* @author Pradeep Krishnan
* @author Ronald Tschalär
*/
public interface Blob {
/**
* Gets the connection that provided this blob.
*
* @return the blob store connection that created this blob
*/
BlobStoreConnection getConnection();
/**
* Gets the id of the blob. Blob ids are URIs as defined by RFC 3986, and therefore will
* always have a scheme.
*
* @return the non-null immutable blob id
*/
URI getId();
/**
* Gets the canonical id of the blob, if known. The definition of what is canonical is
* up to the individual store implementation. When available, the canonical id should be
* used in caches and other indexes where duplication is undesirable.
*
* @return the canonical id, if known; null otherwise.
* @throws IOException if an error occurred
*/
URI getCanonicalId() throws IOException;
/**
* Opens a new InputStream for reading the content.
*
* @return the input stream.
* @throws MissingBlobException if the blob does not {@link #exists exist}.
* @throws IOException if the stream cannot be opened for any other reason.
*/
InputStream openInputStream() throws IOException, MissingBlobException;
/**
* Opens a new OutputStream for writing the content. If the blob does not exist it is created
* with the data written to the stream as the content; else if <var>overwrite</var> is true the
* existing content is replaced with the new data.
*
* @param estimatedSize the estimated size of the data if known (or -1 if unknown).
* This can allow for the implementation to make better decisions
* on buffering or reserving space.
* @param overwrite if false and this blob already exists then do not overwrite the contents
* but throw an exception instead
* @return the output stream.
* @throws DuplicateBlobException if this blob exists and <var>overwrite</var> is false
* @throws IOException if the stream cannot be opened for any other reason.
*/
OutputStream openOutputStream(long estimatedSize, boolean overwrite)
throws IOException, DuplicateBlobException;
/**
* Gets the size of the blob, in bytes.
*
* @return the size in bytes, or -1 if unknown
* @throws MissingBlobException if the blob does not {@link #exists exist}.
* @throws IOException if an error occurred during
*/
long getSize() throws IOException, MissingBlobException;
/**
* Tests if a blob with this id exists in this blob-store.
*
* @return true if the blob denoted by this id exists; false otherwise.
*
* @throws IOException if an error occurred during existence check
* @see #openOutputStream
* @see #delete
*/
boolean exists() throws IOException;
/**
* Removes this blob from the store. This operation is idempotent and does
* not throw an exception if the blob does not {@link #exists exist}.
*
* @throws IOException if the blob cannot be deleted for any reason
*/
void delete() throws IOException;
/**
* Move this blob under the new id. Before the move, this blob must exist and the destination
* blob must not. After the move, this blob will not exist but the destination blob will.
*
* @param blobId the blob id; may be null if the store supports id-generation
* @param hints A set of hints to allow the implementation to optimize the operation (can be
* null)
*
* @return the resulting Blob from the move
*
* @throws UnsupportedIdException if blobId is not in a recognized/usable pattern by this store
* @throws UnsupportedOperationException if <var>blobId</var> is null and this store is not
* capable of generating ids.
* @throws MissingBlobException if this blob does not exist
* @throws DuplicateBlobException if a blob with <var>blobId</var> already exists
* @throws IOException if an error occurs while attempting the operation
*/
Blob moveTo(URI blobId, Map<String, String> hints)
throws DuplicateBlobException, IOException, MissingBlobException, NullPointerException,
IllegalArgumentException;
}