IngestionCrosswalk


1   /*
2    * IngestionCrosswalk.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.crosswalk;
42  
43  import java.io.InputStream  ;
44  import java.io.IOException  ;
45  import java.sql.SQLException  ;
46  import java.util.List  ;
47  
48  import org.dspace.core.Context;
49  import org.dspace.content.DSpaceObject;
50  import org.dspace.authorize.AuthorizeException;
51  
52  import org.jdom.Element;
53  
54  /**
55   * Ingestion Crosswalk plugin -- translate an external metadata format
56   * into DSpace native metadata.
57   * <p>
58   * This describes a plugin that translates an external XML
59   * metadata format (e.g.  MODS) into the DSpace internal metadata
60   * representation.  A crosswalk plugin may operate on different kinds of
61   * DSpace Objects, so the concept of "metadata" encompasses the
62   * qualified Dublin Core fields on Items, properties of Bitstreams, and
63   * metadata on Collections and Communities.
64   * <p>
65   *
66   * @author Larry Stone
67   * @version $Revision: 1.1 $
68   */
69  public interface IngestionCrosswalk
70  {
71      /**
72       * Crosswalk metadata from external XML representation to DSpace
73       * internal representations.  This version accepts metadata as a
74       * <code>List</code> of JDOM XML elements.  It interprets the
75       * contents of each element and adds the appropriate values to the
76       * DSpace Object's internal metadata represenation.
77       * <p>
78       * Note that this method may be called several times for the same target
79       * Item, if the metadata comes as several lists of elements, so it should
80       * not add fixed metadata values on each or they may appear multiples times.
81       * <p>
82       * NOTE:  <br>
83       * Most XML metadata standards (e.g.  MODS) are defined as a "root"
84       * element which contains a sequence of "fields" that have the
85       * descriptive information.  Some metadata containers have a
86       * "disembodied" list of fields, rather than the root element, so
87       * this <code>ingest</code> method is intended to accept that bare
88       * list of fields.  However, it must also accept a list containing
89       * only the "root" element for the metadata structure (e.g.  the
90       * "mods:mods" wrapper in a MODS expression) as a member of the
91       * list.  It can handle this case by calling the single-element
92       * version of ingest() on the "root" element.
93       * <p>
94       * Some callers of the crosswalk plugin may not be careful about (or
95       * capable of) choosing whether the list or element version should
96       * be called.
97       * <p>
98       * @param context  DSpace context.
99       * @param dso DSpace Object (Item, Bitstream, etc) to which new metadata gets attached.
100      * @param metadata  List of XML Elements of metadata
101      *
102      * @throws CrosswalkInternalException (<code>CrosswalkException</code>) failure of the crosswalk itself.
103      * @throws CrosswalkObjectNotSupported (<code>CrosswalkException</code>) Cannot crosswalk into this kind of DSpace object.
104      * @throws MetadataValidationException (<code>CrosswalkException</code>)  metadata format was not acceptable or missing required elements.
105      * @throws IOException  I/O failure in services this calls
106      * @throws SQLException  Database failure in services this calls
107      * @throws AuthorizeException current user not authorized for this operation.
108      */
109     public void ingest(Context context, DSpaceObject dso, List   metadata)
110         throws CrosswalkException, IOException  , SQLException  , AuthorizeException;
111 
112     /**
113      * Crosswalk metadata from external XML representation to DSpace
114      * internal representations.  This version accepts a single "root"
115      * element of the XML metadata.
116      * <p>
117      * It is otherwise just like the <code>List</code> form of
118      * <code>ingest()</code> above.
119      * <p>
120      * @param context  DSpace context.
121      * @param dso DSpace Object (usually an Item) to which new metadata gets attached.
122      * @param root root Element of metadata document.
123      *
124      * @throws CrosswalkInternalException (<code>CrosswalkException</code>) failure of the crosswalk itself.
125      * @throws CrosswalkObjectNotSupported (<code>CrosswalkException</code>) Cannot crosswalk into this kind of DSpace object.
126      * @throws MetadataValidationException (<code>CrosswalkException</code>)  metadata format was not acceptable or missing required elements.
127      * @throws IOException  I/O failure in services this calls
128      * @throws SQLException  Database failure in services this calls
129      * @throws AuthorizeException current user not authorized for this operation.
130      */
131     public void ingest(Context context, DSpaceObject dso, Element root)
132         throws CrosswalkException, IOException  , SQLException  , AuthorizeException;
133 }
134
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags