PackageIngester


1   /*
2    * PackageIngester.java
3    *
4    * Version: $Revision: 1.1 $
5    *
6    * Date: $Date: 2006/03/17 00:04:38 $
7    *
8    * Copyright (c) 2002-2005, Hewlett-Packard Company and Massachusetts
9    * Institute of Technology.  All rights reserved.
10   *
11   * Redistribution and use in source and binary forms, with or without
12   * modification, are permitted provided that the following conditions are
13   * met:
14   *
15   * - Redistributions of source code must retain the above copyright
16   * notice, this list of conditions and the following disclaimer.
17   *
18   * - Redistributions in binary form must reproduce the above copyright
19   * notice, this list of conditions and the following disclaimer in the
20   * documentation and/or other materials provided with the distribution.
21   *
22   * - Neither the name of the Hewlett-Packard Company nor the name of the
23   * Massachusetts Institute of Technology nor the names of their
24   * contributors may be used to endorse or promote products derived from
25   * this software without specific prior written permission.
26   *
27   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
28   * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
29   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
30   * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
31   * HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
32   * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
33   * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
34   * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
35   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
36   * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
37   * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
38   * DAMAGE.
39   */
40  
41  package org.dspace.content.packager;
42  
43  import java.io.IOException  ;
44  import java.io.InputStream  ;
45  import java.sql.SQLException  ;
46  
47  import org.dspace.authorize.AuthorizeException;
48  import org.dspace.content.Collection;
49  import org.dspace.content.Item;
50  import org.dspace.content.WorkspaceItem;
51  import org.dspace.content.crosswalk.CrosswalkException;
52  import org.dspace.core.Context;
53                 
54  
55  /**
56   * Plugin Interface to interpret a Submission Information Package (SIP)
57   * and create (or replace) a DSpace item from its contents.
58   * <p>
59   * A package is a single data stream
60   * containing enough information to construct an Item.  It can be
61   * anything from an archive like a Zip file with a manifest and metadata,
62   * to a simple manifest containing external references to the content,
63   * to a self-contained file such as a PDF.  The interpretation
64   * of the package is entirely at the discretion of the implementing class.
65   * <p>
66   * The ingest methods are also given an attribute-value
67   * list of "parameters"  which may modify their actions.
68   * The parameters list is a generalized mechanism to pass parameters
69   * from the requestor to the packager, since different packagers will
70   * understand different sets of parameters.
71   *
72   * @author Larry Stone
73   * @version $Revision: 1.1 $
74   * @see PackageParameters
75   */
76  public interface PackageIngester
77  {
78      /**
79       * Create new Item out of the ingested package.
80       * The item will belong to the indicated
81       * collection.  This creates a <code>WorkspaceItem</code>, so it is
82       * up to the caller to decide whether to install it or submit
83       * it to normal DSpace Workflow.
84       * <p>
85       * The deposit license is passed explicitly as a string since there
86       * is no place for it in many package formats.  It is optional and may
87       * be given as <code>null</code>.
88       *
89       * @param context  DSpace context.
90       * @param collection  collection under which to create new item.
91       * @param in  input stream containing package to ingest.
92       * @param params Properties-style list of options (interpreted by each packager).
93       * @param license  may be null, which takes default license.
94       * @return workspace item created by ingest.
95       *
96       * @throws PackageValidationException if package is unacceptable or there is
97       *  a fatal error turning it into an Item.
98       */
99      WorkspaceItem ingest(Context context, Collection collection, InputStream   in,
100                          PackageParameters params, String   license)
101         throws PackageException, CrosswalkException,
102                AuthorizeException, SQLException  , IOException  ;
103 
104     /**
105      * Replace an existing Item with contents of the ingested package.
106      * The packager <em>may</em> choose not to implement <code>replace</code>,
107      * since it somewhat contradicts the archival nature of DSpace.
108      * The exact function of this method is highly implementation-dependent.
109      *
110      * @param context  DSpace context.
111      * @param item  existing item to be replaced
112      * @param in  input stream containing package to ingest.
113      * @param params Properties-style list of options specific to this packager
114      * @return item re-created by ingest.
115      *
116      * @throws PackageValidationException if package is unacceptable or there is
117      *  a fatal error turning it into an Item.
118      * @throws UnsupportedOperationException if this packager does not
119      *  implement <code>replace</code>.
120      */
121     Item replace(Context context, Item item, InputStream   in,
122                  PackageParameters params)
123         throws PackageException, UnsupportedOperationException  ,
124                CrosswalkException, AuthorizeException,
125                SQLException  , IOException  ;
126                
127 }
128
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags