org.dspace.content.packager
Class METSManifest

java.lang.Object
  org.dspace.content.packager.METSManifest

public class METSManifest
extends Object

Manage the METS manifest document for METS importer classes, such as the package importer org.dspace.content.packager.MetsSubmission and the federated importer org.dspace.app.mets.FederatedMETSImport

It can parse the METS document, build an internal model, and give the importers access to that model. It also crosswalks all of the descriptive and administrative metadata in the METS manifest into the target DSpace Item, under control of the importer.

It reads the following DSpace Configuration entries:

• Local XML schema (XSD) declarations, in the general format:
  mets.xsd.identifier = namespace xsd-URL
  eg. mets.xsd.dc = http://purl.org/dc/elements/1.1/ dc.xsd
  Add a separate config entry for each schema.
• Crosswalk plugin mappings: These tell it the name of the crosswalk plugin to invoke for metadata sections with a particular value of MDTYPE (or OTHERMDTYPE) By default, the crosswalk mechanism will look for a plugin with the same name as the metadata type (e.g. "MODS", "DC"). This example line invokes the QDC plugin when MDTYPE="DC"
mets.submission.crosswalk.DC = QDC
  general format is:
  mets.submission.crosswalk.mdType = pluginName

Author:

Robert Tansley, WeiHua Huang, Rita Lee, Larry Stone

See Also:

org.dspace.content.packager.MetsSubmission, org.dspace.app.mets.FederatedMETSImport

Nested Class Summary

static interface

METSManifest.Mdref Callback interface to retrieve data streams in mdRef elements.

Field Summary

static String	CONFIG_METS_PREFIX Prefix of DSpace configuration lines that map METS metadata type to crosswalk plugin names.
static String	MANIFEST_FILE Canonical filename of METS manifest within a package or as a bitstream.
static org.jdom.Namespace	metsNS METS namespace -- includes "mets" prefix for use in XPaths
static org.jdom.Namespace	xlinkNS XLink namespace -- includes "xlink" prefix prefix for use in XPaths

Method Summary

static METSManifest	create(InputStream is, boolean validate, String configName) Create a new manifest object from a serialized METS XML document.
void	crosswalkBitstream(Context context, PackageParameters params, Bitstream bitstream, String fileId, METSManifest.Mdref callback) Crosswalk the metadata associated with a particular file element into the bitstream it corresponds to.
void	crosswalkItemDmd(Context context, PackageParameters params, DSpaceObject dso, org.jdom.Element dmdSec, METSManifest.Mdref callback) Invokes appropriate crosswalks on Item-wide descriptive metadata.
void	crosswalkObjectOtherAdminMD(Context context, PackageParameters params, DSpaceObject dso, METSManifest.Mdref callback) Crosswalk all technical and source metadata sections that belong to the whole object.
boolean	crosswalkObjectSourceMD(Context context, PackageParameters params, DSpaceObject dso, METSManifest.Mdref callback) Just crosswalk the sourceMD sections; used to set the handle and parent of AIP.
static String	getBundleName(org.jdom.Element file) Get the DSpace bundle name corresponding to the USE attribute of the file group enclosing this file element.
String[]	getChildMetsFilePaths() Retrieve the file paths for the children objects' METS Manifest files.
List	getChildObjDivs() Get an array of child object <div>s from the METS Manifest <structMap>.
List<org.jdom.Element>	getContentFiles() Gets all file elements which make up the item's content.
org.jdom.Element[]	getDmdElements(String dmdList) Gets all dmdSec elements from a space separated list
static String	getFileName(org.jdom.Element file) Get the "local" file name of this file or mdRef element.
org.jdom.Element[]	getItemDmds() Gets all dmdSec elements containing metadata for the DSpace Item.
org.jdom.Element[]	getItemRightsMD() Return rights metadata section(s) relevant to item as a whole.
InputStream	getMdContentAsStream(org.jdom.Element mdSec, METSManifest.Mdref callback) Return contents of *md element as stream.
List<org.jdom.Element>	getMdContentAsXml(org.jdom.Element mdSec, METSManifest.Mdref callback) Return contents of *md element as List of XML Element objects.
String	getMdContentMimeType(org.jdom.Element mdSec) Returns MIME type of metadata content, if available.
List	getMdFiles() Gets list of all mdRef elements in the METS document.
String	getMdType(org.jdom.Element mdSec) Get the metadata type from within a *mdSec element.
org.jdom.Element	getMets()
InputStream	getMetsAsStream() Return entire METS document as an inputStream
String	getObjID() Return the OBJID attribute of the METS manifest.
org.jdom.Element	getObjStructDiv() Return the <div> which describes this DSpace Object (and its contents) from the <structMap>.
String	getOriginalFilePath(org.jdom.Element file) Get the "original" file element for a derived file.
String	getParentOwnerLink() Return the reference to the Parent Object from the "Parent" <structMap>.
org.jdom.Element	getPrimaryOrLogoBitstream() Returns file element corresponding to primary bitstream.
String	getProfile() Gets name of the profile to which this METS document conforms.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MANIFEST_FILE

public static final String MANIFEST_FILE

Canonical filename of METS manifest within a package or as a bitstream.

See Also:

Constant Field Values

CONFIG_METS_PREFIX

public static final String CONFIG_METS_PREFIX

Prefix of DSpace configuration lines that map METS metadata type to crosswalk plugin names.

See Also:

Constant Field Values

metsNS

public static final org.jdom.Namespace metsNS

METS namespace -- includes "mets" prefix for use in XPaths

xlinkNS

public static final org.jdom.Namespace xlinkNS

XLink namespace -- includes "xlink" prefix prefix for use in XPaths

Method Detail

create

public static METSManifest create(InputStream is,
                                  boolean validate,
                                  String configName)
                           throws IOException,
                                  MetadataValidationException

Create a new manifest object from a serialized METS XML document. Parse document read from the input stream, optionally validating.

Parameters:

is - input stream containing serialized XML

validate - if true, enable XML validation using schemas in document. Also validates any sub-documents.

Returns:

new METSManifest object.

Throws:

MetadataValidationException - if there is any error parsing or validating the METS.

IOException

getProfile

public String getProfile()

Gets name of the profile to which this METS document conforms.

Returns:

value the PROFILE attribute of mets element, or null if none.

getObjID

public String getObjID()

Return the OBJID attribute of the METS manifest. This is where the Handle URI/URN of the object can be found.

Returns:

OBJID attribute of METS manifest

getContentFiles

public List<org.jdom.Element> getContentFiles()
                                       throws MetadataValidationException

Gets all file elements which make up the item's content.

Returns:

a List of Elements.

Throws:

MetadataValidationException

getMdFiles

public List getMdFiles()
                throws MetadataValidationException

Gets list of all mdRef elements in the METS document. Used by ingester to e.g. check that all required files are present.

Returns:

a List of Elements.

Throws:

MetadataValidationException

getOriginalFilePath

public String getOriginalFilePath(org.jdom.Element file)

Get the "original" file element for a derived file. Finds the original from which this was derived by matching the GROUPID attribute that binds it to its original. For instance, the file for a thumbnail image would have the same GROUPID as its full-size version.

NOTE: This pattern of relating derived files through the GROUPID attribute is peculiar to the DSpace METS SIP profile, and may not be generally useful with other sorts of METS documents.

Parameters:

file - METS file element of derived file

Returns:

file path of original or null if none found.

getBundleName

public static String getBundleName(org.jdom.Element file)
                            throws MetadataValidationException

Get the DSpace bundle name corresponding to the USE attribute of the file group enclosing this file element.

Returns:

DSpace bundle name

Throws:

MetadataValidationException - when there is no USE attribute on the enclosing fileGrp.

getFileName

public static String getFileName(org.jdom.Element file)
                          throws MetadataValidationException

Get the "local" file name of this file or mdRef element. By "local" we mean the reference to the actual resource containing the data for this file, e.g. a relative path within a Zip or tar archive if the METS is serving as a manifest for that sort of package.

Returns:

"local" file name (i.e. relative to package or content directory) corresponding to this file or mdRef element.

Throws:

MetadataValidationException - when there is not enough information to find a resource identifier.

getPrimaryOrLogoBitstream

public org.jdom.Element getPrimaryOrLogoBitstream()
                                           throws MetadataValidationException

Returns file element corresponding to primary bitstream. There is ONLY a primary bitstream if the first div under first structMap has an fptr.

Returns:

file element of Item's primary bitstream, or null if there is none.

Throws:

MetadataValidationException

getMdType

public String getMdType(org.jdom.Element mdSec)
                 throws MetadataValidationException

Get the metadata type from within a *mdSec element.

Returns:

metadata type name.

Throws:

MetadataValidationException

getMdContentMimeType

public String getMdContentMimeType(org.jdom.Element mdSec)
                            throws MetadataValidationException

Returns MIME type of metadata content, if available.

Returns:

MIMEtype word, or null if none is available.

Throws:

MetadataValidationException

getMdContentAsXml

public List<org.jdom.Element> getMdContentAsXml(org.jdom.Element mdSec,
                                                METSManifest.Mdref callback)
                                         throws MetadataValidationException,
                                                PackageValidationException,
                                                IOException,
                                                SQLException,
                                                AuthorizeException

Return contents of *md element as List of XML Element objects. Gets content, dereferencing mdRef if necessary, or decoding and parsing a binData that contains XML.

Returns:

contents of metadata section, or empty list if no XML content is available.

Throws:

MetadataValidationException - if METS is invalid, or there is an error parsing the XML.

PackageValidationException

IOException

SQLException

AuthorizeException

getMdContentAsStream

public InputStream getMdContentAsStream(org.jdom.Element mdSec,
                                        METSManifest.Mdref callback)
                                 throws MetadataValidationException,
                                        PackageValidationException,
                                        IOException,
                                        SQLException,
                                        AuthorizeException

Return contents of *md element as stream. Gets content, dereferencing mdRef if necessary, or decoding a binData element if necessary.

Returns:

Stream containing contents of metadata section. Never returns null.

Throws:

MetadataValidationException - if METS format does not contain any metadata.

PackageValidationException

IOException

SQLException

AuthorizeException

getObjStructDiv

public org.jdom.Element getObjStructDiv()
                                 throws MetadataValidationException

Return the <div> which describes this DSpace Object (and its contents) from the <structMap>. In all cases, this is the first <div> in the first <structMap>.

Returns:

Element which is the DSpace Object Contents <div>

Throws:

MetadataValidationException

getChildObjDivs

public List getChildObjDivs()
                     throws MetadataValidationException

Get an array of child object <div>s from the METS Manifest <structMap>. These <div>s reference the location of any child objects METS manifests.

Returns:

a List of Elements, each a <div>. May be empty but NOT null.

Throws:

MetadataValidationException

getChildMetsFilePaths

public String[] getChildMetsFilePaths()
                               throws MetadataValidationException

Retrieve the file paths for the children objects' METS Manifest files. These file paths are located in the <mptr> where @LOCTYPE=URL

Returns:

a list of Strings, corresponding to relative file paths of children METS manifests

Throws:

MetadataValidationException

getParentOwnerLink

public String getParentOwnerLink()
                          throws MetadataValidationException

Return the reference to the Parent Object from the "Parent" <structMap>. This parent object is the owner of current object.

Returns:

Link to the Parent Object (this is the Handle of that Parent)

Throws:

MetadataValidationException

getItemDmds

public org.jdom.Element[] getItemDmds()
                               throws MetadataValidationException

Gets all dmdSec elements containing metadata for the DSpace Item.

Returns:

array of Elements, each a dmdSec. May be empty but NOT null.

Throws:

MetadataValidationException - if the METS is missing a reference to item-wide DMDs in the correct place.

getDmdElements

public org.jdom.Element[] getDmdElements(String dmdList)
                                  throws MetadataValidationException

Gets all dmdSec elements from a space separated list

Parameters:

dmdList - space-separated list of DMDIDs

Returns:

array of Elements, each a dmdSec. May be empty but NOT null.

Throws:

MetadataValidationException - if the METS is missing a reference to item-wide DMDs in the correct place.

getItemRightsMD

public org.jdom.Element[] getItemRightsMD()
                                   throws MetadataValidationException

Return rights metadata section(s) relevant to item as a whole.

Returns:

array of rightsMd elements, possibly empty but never null.

Throws:

MetadataValidationException - if METS is invalid, e.g. referenced amdSec is missing.

crosswalkItemDmd

public void crosswalkItemDmd(Context context,
                             PackageParameters params,
                             DSpaceObject dso,
                             org.jdom.Element dmdSec,
                             METSManifest.Mdref callback)
                      throws MetadataValidationException,
                             PackageValidationException,
                             CrosswalkException,
                             IOException,
                             SQLException,
                             AuthorizeException

Invokes appropriate crosswalks on Item-wide descriptive metadata.

Throws:

MetadataValidationException

PackageValidationException

CrosswalkException

IOException

SQLException

AuthorizeException

crosswalkObjectOtherAdminMD

public void crosswalkObjectOtherAdminMD(Context context,
                                        PackageParameters params,
                                        DSpaceObject dso,
                                        METSManifest.Mdref callback)
                                 throws MetadataValidationException,
                                        PackageValidationException,
                                        CrosswalkException,
                                        IOException,
                                        SQLException,
                                        AuthorizeException

Crosswalk all technical and source metadata sections that belong to the whole object.

Throws:

MetadataValidationException - if METS is invalid, e.g. referenced amdSec is missing.

PackageValidationException

CrosswalkException

IOException

SQLException

AuthorizeException

crosswalkObjectSourceMD

public boolean crosswalkObjectSourceMD(Context context,
                                       PackageParameters params,
                                       DSpaceObject dso,
                                       METSManifest.Mdref callback)
                                throws MetadataValidationException,
                                       PackageValidationException,
                                       CrosswalkException,
                                       IOException,
                                       SQLException,
                                       AuthorizeException

Just crosswalk the sourceMD sections; used to set the handle and parent of AIP.

Returns:

true if any metadata section was actually crosswalked, false otherwise

Throws:

MetadataValidationException

PackageValidationException

CrosswalkException

IOException

SQLException

AuthorizeException

crosswalkBitstream

public void crosswalkBitstream(Context context,
                               PackageParameters params,
                               Bitstream bitstream,
                               String fileId,
                               METSManifest.Mdref callback)
                        throws MetadataValidationException,
                               PackageValidationException,
                               CrosswalkException,
                               IOException,
                               SQLException,
                               AuthorizeException

Crosswalk the metadata associated with a particular file element into the bitstream it corresponds to.

Parameters:

context - a dspace context.

params - any PackageParameters which may affect how bitstreams are crosswalked

bitstream - bitstream target of the crosswalk

fileId - value of ID attribute in the file element responsible for the contents of that bitstream.

callback - ???

Throws:

MetadataValidationException

PackageValidationException

CrosswalkException

IOException

SQLException

AuthorizeException

getMets

public org.jdom.Element getMets()

Returns:

root element of METS document.

getMetsAsStream

public InputStream getMetsAsStream()

Return entire METS document as an inputStream

Returns:

entire METS document as a stream