KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > dspace > content > crosswalk > DisseminationCrosswalk


1 /*
2  * DisseminationCrosswalk.java
3  *
4  * Version: $Revision: 1.2 $
5  *
6  * Date: $Date: 2006/03/27 02:57:09 $
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.OutputStream JavaDoc;
44 import java.io.IOException JavaDoc;
45 import java.util.List JavaDoc;
46
47 import java.sql.SQLException JavaDoc;
48
49 import org.dspace.core.Context;
50 import org.dspace.content.Item;
51 import org.dspace.content.DSpaceObject;
52 import org.dspace.authorize.AuthorizeException;
53
54 import org.jdom.Element;
55 import org.jdom.Namespace;
56
57 /**
58  * Dissemination Crosswalk plugin -- translate DSpace native
59  * metadata into an external XML format.
60  * <p>
61  * This interface describes a plugin that produces metadata in an XML-based
62  * format from the state of a DSpace object. Note that the object
63  * may be an Item, Bitstream, Community, or Collection, although most
64  * implementations only work on one type of object.
65  *
66  * @author Larry Stone
67  * @version $Revision: 1.2 $
68  */
69 public interface DisseminationCrosswalk
70 {
71     /** XSI namespace, required for xsi:schemalocation attributes */
72     static final Namespace XSI_NS =
73         Namespace.getNamespace("xsi", "http://www.w3.org/2001/XMLSchema-instance");
74
75     /**
76      * Get XML namespaces of the elements this crosswalk may return.
77      * Returns the XML namespaces (as JDOM objects) of the root element.
78      *
79      * @return array of namespaces, which may be empty.
80      */
81     public Namespace[] getNamespaces();
82
83     /**
84      * Get the XML Schema location(s) of the target metadata format.
85      * Returns the string value of the <code>xsi:schemaLocation</code>
86      * attribute that should be applied to the generated XML.
87      * <p>
88      * It may return the empty string if no schema is known, but crosswalk
89      * authors are strongly encouraged to implement this call so their output
90      * XML can be validated correctly.
91      * @return SchemaLocation string, including URI namespace, followed by
92      * whitespace and URI of XML schema document, or empty string if unknown.
93      */
94     public String JavaDoc getSchemaLocation();
95
96     /**
97      * Predicate: Can this disseminator crosswalk the given object.
98      * Needed by OAI-PMH server implementation.
99      *
100      * @param dso dspace object, e.g. an <code>Item</code>.
101      * @return true when disseminator is capable of producing metadata.
102      */
103     public boolean canDisseminate(DSpaceObject dso);
104
105     /**
106      * Predicate: Does this disseminator prefer to return a list of Elements,
107      * rather than a single root Element?
108      * <p>
109      * Some metadata formats have an XML schema without a root element,
110      * for example, the Dublin Core and Qualified Dublin Core formats.
111      * This would be <code>true</code> for a crosswalk into QDC, since
112      * it would "prefer" to return a list, since any root element it has
113      * to produce would have to be part of a nonstandard schema. In
114      * most cases your implementation will want to return
115      * <code>false</code>
116      *
117      * @return true when disseminator prefers you call disseminateList().
118      */
119     public boolean preferList();
120
121     /**
122      * Execute crosswalk, returning List of XML elements.
123      * Returns a <code>List</code> of JDOM <code>Element</code> objects representing
124      * the XML produced by the crosswalk. This is typically called when
125      * a list of fields is desired, e.g. for embedding in a METS document
126      * <code>xmlData</code> field.
127      * <p>
128      * When there are no results, an
129      * empty list is returned, but never <code>null</code>.
130      *
131      * @param dso the DSpace Object whose metadata to export.
132      * @return results of crosswalk as list of XML elements.
133      *
134      * @throws CrosswalkInternalException (<code>CrosswalkException</code>) failure of the crosswalk itself.
135      * @throws CrosswalkObjectNotSupported (<code>CrosswalkException</code>) Cannot crosswalk this kind of DSpace object.
136      * @throws IOException I/O failure in services this calls
137      * @throws SQLException Database failure in services this calls
138      * @throws AuthorizeException current user not authorized for this operation.
139      */
140     public List JavaDoc disseminateList(DSpaceObject dso)
141         throws CrosswalkException, IOException JavaDoc, SQLException JavaDoc,
142                AuthorizeException;
143
144     /**
145      * Execute crosswalk, returning one XML root element as
146      * a JDOM <code>Element</code> object.
147      * This is typically the root element of a document.
148      * <p>
149      *
150      * @param dso the DSpace Object whose metadata to export.
151      * @return root Element of the target metadata, never <code>null</code>
152      *
153      * @throws CrosswalkInternalException (<code>CrosswalkException</code>) failure of the crosswalk itself.
154      * @throws CrosswalkObjectNotSupported (<code>CrosswalkException</code>) Cannot crosswalk this kind of DSpace object.
155      * @throws IOException I/O failure in services this calls
156      * @throws SQLException Database failure in services this calls
157      * @throws AuthorizeException current user not authorized for this operation.
158      */
159     public Element disseminateElement(DSpaceObject dso)
160         throws CrosswalkException, IOException JavaDoc, SQLException JavaDoc,
161                AuthorizeException;
162 }
163
Popular Tags