PackageIngester.java

/*
 * PackageIngester.java
 *
 * Version: $Revision: 3705 $
 *
 * Date: $Date: 2009-04-11 18:02:24 +0100 (Sat, 11 Apr 2009) $
 *
 * Copyright (c) 2002-2005, Hewlett-Packard Company and Massachusetts
 * Institute of Technology.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * - Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *
 * - Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 *
 * - Neither the name of the Hewlett-Packard Company nor the name of the
 * Massachusetts Institute of Technology nor the names of their
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 */

package org.dspace.content.packager;

import java.io.IOException;
import java.io.InputStream;
import java.sql.SQLException;

import org.dspace.authorize.AuthorizeException;
import org.dspace.content.Bitstream;
import org.dspace.content.Collection;
import org.dspace.content.Item;
import org.dspace.content.WorkspaceItem;
import org.dspace.content.crosswalk.CrosswalkException;
import org.dspace.content.crosswalk.MetadataValidationException;
import org.dspace.core.Constants;
import org.dspace.core.Context;

import uk.ac.jorum.exceptions.CriticalException;
import uk.ac.jorum.exceptions.NonCriticalException;
               

/**
 * Plugin Interface to interpret a Submission Information Package (SIP)
 * and create (or replace) a DSpace item from its contents.
 * <p>
 * A package is a single data stream
 * containing enough information to construct an Item.  It can be
 * anything from an archive like a Zip file with a manifest and metadata,
 * to a simple manifest containing external references to the content,
 * to a self-contained file such as a PDF.  The interpretation
 * of the package is entirely at the discretion of the implementing class.
 * <p>
 * The ingest methods are also given an attribute-value
 * list of "parameters"  which may modify their actions.
 * The parameters list is a generalized mechanism to pass parameters
 * from the requestor to the packager, since different packagers will
 * understand different sets of parameters.
 *
 * @author Larry Stone
 * @version $Revision: 3705 $
 * @see PackageParameters
 */
public interface PackageIngester
{
	// START 24/9/09 GWaller Added params into interface so they can be referenced by all packager classes 
	/** String defining the constant name use to switch package XML validation on/off */
	public static final String VALIDATE_PARAM = "validate";
	
	/** String defining the constant name use to tell the packager to fail or not if a licence is not found */
	public static final String FAIL_NO_LICENCE_PARAM = "failNoLicence";
	// END 24/9/09 GWaller Added params into interface so they can be referenced by all packager classes 
    
	public static final String ALTER_OWNING_COL_PARAM = "alterOwningCol";
	public static final String FORCED_CC_LICENCE = "forcedCCLicence";
	
	// GWaller 6/5/10 IssueID#263 Support for web links not in a manifest resource element
	public static final String MAX_METADATA_WEB_LINKS_TO_USE = "maxMetadataWebLinks";
	
	/**
     * Create new Item out of the ingested package.
     * The item will belong to the indicated
     * collection.  This creates a <code>WorkspaceItem</code>, so it is
     * up to the caller to decide whether to install it or submit
     * it to normal DSpace Workflow.
     * <p>
     * The deposit license is passed explicitly as a string since there
     * is no place for it in many package formats.  It is optional and may
     * be given as <code>null</code>.
     *
     * @param context  DSpace context.
     * @param collection  collection under which to create new item.
     * @param in  input stream containing package to ingest.
     * @param params Properties-style list of options (interpreted by each packager).
     * @param license  may be null, which takes default license.
     * @return workspace item created by ingest.
     *
     * @throws PackageValidationException if package is unacceptable or there is
     *  a fatal error turning it into an Item.
     */
	// GWaller 26/08/09 Modified to support array of Collections
    WorkspaceItem ingest(Context context, Collection[] collections, InputStream in,
                         PackageParameters params, String license)
        throws PackageException, CrosswalkException,
               AuthorizeException, SQLException, IOException;

    /**
     * Replace an existing Item with contents of the ingested package.
     * The packager <em>may</em> choose not to implement <code>replace</code>,
     * since it somewhat contradicts the archival nature of DSpace.
     * The exact function of this method is highly implementation-dependent.
     *
     * @param context  DSpace context.
     * @param item  existing item to be replaced
     * @param in  input stream containing package to ingest.
     * @param params Properties-style list of options specific to this packager
     * @return item re-created by ingest.
     *
     * @throws PackageValidationException if package is unacceptable or there is
     *  a fatal error turning it into an Item.
     * @throws UnsupportedOperationException if this packager does not
     *  implement <code>replace</code>.
     */
    Item replace(Context context, Item item, InputStream in,
                 PackageParameters params)
        throws PackageException, UnsupportedOperationException,
               CrosswalkException, AuthorizeException,
               SQLException, IOException;
    
    // START GWaller 11/11/09 IssueID #73 Added post install hook method which is called after the item is installed 
    public void postInstallHook(Context context, Item item) throws NonCriticalException, CriticalException;
    // END GWaller 11/11/09 IssueID #73 Added post install hook method which is called after the item is installed 
               
    // START GWaller 02/02/09 IssueID #175 Added methods to deal with licence manipulation inside packages
    /**
     * This method ensures the licence information is correct in the package manifest i.e. it contains the same
     * licence name and url as supplied in the paramaters. It potentially alters the XML manifest and
     * backs up the original.
     * NOTE: if the manifest was altered the new manifest is stored in the Constants.METADATA_BUNDLE_NAME bundle
     * and has the appropriate manifest name e.g. IMSIngester.MANIFEST_FILE
     * NOTE: This method will close the input stream of the manifest to examine
     * @param context DSpace context to use for DB calls
     * @param item the item which contains the package
     * @param bitstreamContainingManifest can be null. Set this to a non-null value if the manifest to check is contained in a bitstream
     * @param manifestStream can be null (only if bitstreamContainingManifest is non-null). Set to the stream containing the manifest to check
     * @param backupBitstream set to true if the manifest should be backed up before being changed (only applicable 
     * if bitstreamContainingManifest is non null)
     * @param licenceUrl the url of the licence which the item should have
     * @param licenceName the name of the licence which the item should have
     * @return true if the manifest was changed, false otherwise
     * @throws SQLException
     * @throws IOException
     * @throws AuthorizeException
     * @throws MetadataValidationException
     * @throws CriticalException
     */
    public boolean updateLicenceInfoInManifest(Context context, 
			   Item item,
			   Bitstream bitstreamContainingManifest,
			   InputStream manifestStream,
			   boolean backupBitstream,
			   String licenceUrl, 
			   String licenceName) throws SQLException, 
										  IOException, 
										  AuthorizeException, 
										  MetadataValidationException,
										  CriticalException;
    
    public void updateEmbeddedLicence(Context context, Item item) throws NonCriticalException , CriticalException;
    
    // END GWaller 02/02/09 IssueID #175 Added methods to deal with licence manipulation inside packages
}