FileDataService.java

/*
 * Copyright (C) 2006-2016 DLR, Germany
 * 
 * All rights reserved
 * 
 * http://www.rcenvironment.de/
 */

package de.rcenvironment.core.datamanagement;

import java.io.IOException;
import java.io.InputStream;

import de.rcenvironment.core.authorization.AuthorizationException;
import de.rcenvironment.core.communication.common.CommunicationException;
import de.rcenvironment.core.communication.common.ResolvableNodeId;
import de.rcenvironment.core.datamanagement.commons.DataReference;
import de.rcenvironment.core.datamanagement.commons.MetaData;
import de.rcenvironment.core.datamanagement.commons.MetaDataSet;
import de.rcenvironment.core.utils.common.rpc.RemoteOperationException;

/**
 * Service that provides easy access to all file data by calling remote {@link RemotableFileDataService}s in the distributed system.
 * 
 * @author Doreen Seider
 */

public interface FileDataService {

    /**
     * Returns the {@link InputStream} of the given revision of the given {@link DataReference}.
     * 
     * @param dataReference {@link DataReference} which contains the needed revision.
     * @return {@link InputStream} of the given revision.
     * @throws AuthorizationException If the user has no read permission.
     * @throws CommunicationException in case of communication error
     */
    InputStream getStreamFromDataReference(DataReference dataReference)
        throws AuthorizationException, CommunicationException;

    /**
     * Creates a new {@link DataReference} from the given {@link InputStream} on the platform represented by the given
     * {@link ResolvableNodeId}. The new {@link DataReference} will contain the given {@link MetaData} and reserved {@link MetaData} which
     * will be set automatically.
     * 
     * @param inputStream InputStream that shall be saved.
     * @param metaDataSet MetaDataSet that shall be saved.
     * @param platform {@link ResolvableNodeId} of the platform to store the reference. If <code>null</code> the new reference will be
     *        created on the local platform.
     * @return DataReference for the given InputStream and MetaData.
     * @throws AuthorizationException If the user or the extension has no create permission.
     * @throws IOException on upload failure
     * @throws InterruptedException on thread interruption
     * @throws CommunicationException in case of communication error
     */
    DataReference newReferenceFromStream(InputStream inputStream, MetaDataSet metaDataSet,
        ResolvableNodeId platform) throws AuthorizationException, IOException, InterruptedException, CommunicationException;

    /**
     * Deletes a whole local or remote {@link DataReference} with all {@link Revision}s.
     * 
     * @param dataReference DataReference that shall be deleted.
     * @throws CommunicationException on communication error
     */
    void deleteReference(DataReference dataReference) throws CommunicationException;

    /**
     * Deletes a whole local {@link DataReference} with all {@link Revision}s.
     * 
     * @param binaryReferenceKey Key of the binary reference that shall be deleted.
     * @throws RemoteOperationException standard remote operation exception
     */
    void deleteReference(String binaryReferenceKey) throws RemoteOperationException;

}