001: /*
002: * DisseminationCrosswalk.java
003: *
004: * Version: $Revision: 2108 $
005: *
006: * Date: $Date: 2007-07-30 12:26:50 -0500 (Mon, 30 Jul 2007) $
007: *
008: * Copyright (c) 2002-2005, Hewlett-Packard Company and Massachusetts
009: * Institute of Technology. All rights reserved.
010: *
011: * Redistribution and use in source and binary forms, with or without
012: * modification, are permitted provided that the following conditions are
013: * met:
014: *
015: * - Redistributions of source code must retain the above copyright
016: * notice, this list of conditions and the following disclaimer.
017: *
018: * - Redistributions in binary form must reproduce the above copyright
019: * notice, this list of conditions and the following disclaimer in the
020: * documentation and/or other materials provided with the distribution.
021: *
022: * - Neither the name of the Hewlett-Packard Company nor the name of the
023: * Massachusetts Institute of Technology nor the names of their
024: * contributors may be used to endorse or promote products derived from
025: * this software without specific prior written permission.
026: *
027: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
028: * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
029: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
030: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
031: * HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
032: * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
033: * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
034: * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
035: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
036: * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
037: * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
038: * DAMAGE.
039: */
040:
041: package org.dspace.content.crosswalk;
042:
043: import java.io.IOException;
044: import java.sql.SQLException;
045: import java.util.List;
046:
047: import org.dspace.authorize.AuthorizeException;
048: import org.dspace.content.DSpaceObject;
049: import org.jdom.Element;
050: import org.jdom.Namespace;
051:
052: /**
053: * Dissemination Crosswalk plugin -- translate DSpace native
054: * metadata into an external XML format.
055: * <p>
056: * This interface describes a plugin that produces metadata in an XML-based
057: * format from the state of a DSpace object. Note that the object
058: * may be an Item, Bitstream, Community, or Collection, although most
059: * implementations only work on one type of object.
060: *
061: * @author Larry Stone
062: * @version $Revision: 2108 $
063: */
064: public interface DisseminationCrosswalk {
065: /** XSI namespace, required for xsi:schemalocation attributes */
066: static final Namespace XSI_NS = Namespace.getNamespace("xsi",
067: "http://www.w3.org/2001/XMLSchema-instance");
068:
069: /**
070: * Get XML namespaces of the elements this crosswalk may return.
071: * Returns the XML namespaces (as JDOM objects) of the root element.
072: *
073: * @return array of namespaces, which may be empty.
074: */
075: public Namespace[] getNamespaces();
076:
077: /**
078: * Get the XML Schema location(s) of the target metadata format.
079: * Returns the string value of the <code>xsi:schemaLocation</code>
080: * attribute that should be applied to the generated XML.
081: * <p>
082: * It may return the empty string if no schema is known, but crosswalk
083: * authors are strongly encouraged to implement this call so their output
084: * XML can be validated correctly.
085: * @return SchemaLocation string, including URI namespace, followed by
086: * whitespace and URI of XML schema document, or empty string if unknown.
087: */
088: public String getSchemaLocation();
089:
090: /**
091: * Predicate: Can this disseminator crosswalk the given object.
092: * Needed by OAI-PMH server implementation.
093: *
094: * @param dso dspace object, e.g. an <code>Item</code>.
095: * @return true when disseminator is capable of producing metadata.
096: */
097: public boolean canDisseminate(DSpaceObject dso);
098:
099: /**
100: * Predicate: Does this disseminator prefer to return a list of Elements,
101: * rather than a single root Element?
102: * <p>
103: * Some metadata formats have an XML schema without a root element,
104: * for example, the Dublin Core and Qualified Dublin Core formats.
105: * This would be <code>true</code> for a crosswalk into QDC, since
106: * it would "prefer" to return a list, since any root element it has
107: * to produce would have to be part of a nonstandard schema. In
108: * most cases your implementation will want to return
109: * <code>false</code>
110: *
111: * @return true when disseminator prefers you call disseminateList().
112: */
113: public boolean preferList();
114:
115: /**
116: * Execute crosswalk, returning List of XML elements.
117: * Returns a <code>List</code> of JDOM <code>Element</code> objects representing
118: * the XML produced by the crosswalk. This is typically called when
119: * a list of fields is desired, e.g. for embedding in a METS document
120: * <code>xmlData</code> field.
121: * <p>
122: * When there are no results, an
123: * empty list is returned, but never <code>null</code>.
124: *
125: * @param dso the DSpace Object whose metadata to export.
126: * @return results of crosswalk as list of XML elements.
127: *
128: * @throws CrosswalkInternalException (<code>CrosswalkException</code>) failure of the crosswalk itself.
129: * @throws CrosswalkObjectNotSupported (<code>CrosswalkException</code>) Cannot crosswalk this kind of DSpace object.
130: * @throws IOException I/O failure in services this calls
131: * @throws SQLException Database failure in services this calls
132: * @throws AuthorizeException current user not authorized for this operation.
133: */
134: public List disseminateList(DSpaceObject dso)
135: throws CrosswalkException, IOException, SQLException,
136: AuthorizeException;
137:
138: /**
139: * Execute crosswalk, returning one XML root element as
140: * a JDOM <code>Element</code> object.
141: * This is typically the root element of a document.
142: * <p>
143: *
144: * @param dso the DSpace Object whose metadata to export.
145: * @return root Element of the target metadata, never <code>null</code>
146: *
147: * @throws CrosswalkInternalException (<code>CrosswalkException</code>) failure of the crosswalk itself.
148: * @throws CrosswalkObjectNotSupported (<code>CrosswalkException</code>) Cannot crosswalk this kind of DSpace object.
149: * @throws IOException I/O failure in services this calls
150: * @throws SQLException Database failure in services this calls
151: * @throws AuthorizeException current user not authorized for this operation.
152: */
153: public Element disseminateElement(DSpaceObject dso)
154: throws CrosswalkException, IOException, SQLException,
155: AuthorizeException;
156: }
|