/*
 * DataMover.java
 *
 * Created on February 8, 2006, 3:27 PM
 *
 * To change this template, choose Tools | Options and locate the template under
 * the Source Creation and Management node. Right-click the template and choose
 * Open. You can then make changes to the template in the Source Editor.
 */

package edu.umiacs.pawn.resource;

import edu.umiacs.util.ParameterException;
import edu.umiacs.util.Parameters;
import java.io.InputStream;

/**
 * This is the class that will move items from a client's package to the final
 * backend storage. This will be run on the receiving server.
 *
 * The interface is designed to be used as a callback that is executed as
 * the receiving server runs though a given collection much in the same way
 * a SAX parser runs through an XML document. The implementation is responsible
 * for keeping it's own internal state.
 *
 * @author toaster
 */
public interface DataMover
{
    
    /**
     * Set parameters necessary for moving data. This will be called before 
     * any transfer actions are called.
     *
     * @param clientParam   parameters supplied from the client gui
     * @param globalParam   parameters supplied from the scheduler as a global config for this resource
     *
     * @throws ParameterException if parameters are missing or of unexpected type or bad configuration
     *
     */
    public void setParameters(Parameters clientParam, Parameters globalParam, 
            TransferContext ctx) throws ParameterException;
    
    /**
     * Receive notification that transfer is about to start
     */
    public void startTransfer();
    
    /**
     * Receive notification that transfer has ended
     */
    public void endTransfer();
    
    /**
     * Notification that a manifest has been started. The getXX context methods will 
     * return manifest related information.
     *
     * @param manifestURN 
     */
    public void startManifest(long manifestId);
    
    /**
     * Receive notification that an object has been started
     *
     * @param objectURN 
     */
    public void startObject(long objectId);
    
    /**
     * 
     *
     * @return 
     */
    public String processMetadata();
    
    /**
     * Commit the current object into long term storage and return a descriptive
     * handle to the location.
     *
     *
     * @return 
     */
    public String processObject();
    
    /**
     * Commit the current manifest into long-term storage and return a descriptive
     * handle to the location. 
     *
     * @return 
     */
    public String processManifest();
    
    /**
     * 
     * @param objectURN 
     */
    public void endObject(long objectId);
    
    /**
     * 
     * @param manifestURN 
     */
    public void endManifest(long manifestId);
    
    
}