RemoteBlob.java

/* $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.rmi.remote;

import java.io.IOException;

import java.net.URI;

import java.rmi.Remote;
import java.rmi.RemoteException;

import java.util.Map;

import org.akubraproject.DuplicateBlobException;
import org.akubraproject.MissingBlobException;

/**
 * Represents a blob on the remote server.
 *
 * @author Pradeep Krishnan
 */
public interface RemoteBlob extends Remote {
  /**
   * Gets the id of the blob.
   *
   * @return the non-null immutable blob id
   *
   * @throws RemoteException on an error in rmi transport
   */
  URI getId() throws RemoteException;

  /**
   * Gets the canonical id of the blob, if known.
   *
   * @return the canonical id, if known; null otherwise.
   *
   * @throws RemoteException on an error in rmi transport
   * @throws IOException if an error occurred
   */
  URI getCanonicalId() throws RemoteException, IOException;

  /**
   * Tests if this blob exists on remote.
   *
   * @return the size
   *
   * @throws RemoteException on an error in rmi transport
   * @throws IOException error reported by the remote
   */
  boolean exists() throws RemoteException, IOException;

  /**
   * Gets the size of the blob from remote.
   *
   * @return the size
   *
   * @throws RemoteException on an error in rmi transport
   * @throws IOException error reported by the remote
   * @throws MissingBlobException error reported by the remote
   */
  long getSize() throws RemoteException, IOException, MissingBlobException;

  /**
   * Deletes a blob on the remote.
   *
   * @throws RemoteException on an error in rmi transport
   * @throws IOException error reported by the remote
   */
  void delete() throws RemoteException, IOException;

  /**
   * Moves the blob contents to another on the remote.
   *
   * @param id the other blob
   * @param hints the hints to pass to the remote
   *
   * @return the resulting Blob
   *
   * @throws RemoteException on an error in rmi transport
   * @throws DuplicateBlobException error reported by remote
   * @throws MissingBlobException error reported by remote
   * @throws UnsupportedOperationException error reported by remote
   * @throws IOException error reported by the remote
   */
  RemoteBlob moveTo(URI id, Map<String, String> hints)
       throws RemoteException, DuplicateBlobException, MissingBlobException,
              UnsupportedOperationException, IOException;

  /**
   * Create a stream to read from the blob on the remote.
   *
   * @return a new stream to read from the remote server blob.
   *
   * @throws RemoteException on an error in rmi transport
   * @throws IOException error reported by remote
   * @throws MissingBlobException error reported by remote
   */
  RemoteInputStream openInputStream() throws RemoteException, IOException, MissingBlobException;

  /**
   * Create a stream to write to the blob on the remote.
   *
   * @param estimatedSize the estimated size of this blob when the  write is complete
   * @param overwrite     if false and this blob already exists then do not overwrite the contents
   *                      but throw an exception instead
   *
   * @return a new stream to write to the remote server blob
   *
   * @throws RemoteException on an error in rmi transport
   * @throws IOException error reported by remote
   * @throws DuplicateBlobException error reported by remote
   */
  RemoteOutputStream openOutputStream(long estimatedSize, boolean overwrite)
                               throws RemoteException, IOException, DuplicateBlobException;
}