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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	METSManifest.Mdref Callback interface to retrieve data streams in mdRef elements.

Field Summary

Fields

Modifier and Type	Field and Description
protected List<org.jdom.Element>	bundleFiles
static String	CONFIG_METS_PREFIX Prefix of DSpace configuration lines that map METS metadata type to crosswalk plugin names.
protected static String	CONFIG_XSD_PREFIX prefix of config lines identifying local XML Schema (XSD) files
protected String	configName name of packager who created this manifest object, for looking up configuration entries.
protected List<org.jdom.Element>	contentFiles <file> elements in "original" file group (bundle)
protected static org.jdom.Namespace	dcNS Dublin core element namespace
protected static org.jdom.Namespace	dcTermNS Dublin core term namespace (for qualified DC)
protected static String	localSchemas
static String	MANIFEST_FILE Canonical filename of METS manifest within a package or as a bitstream.
protected List	mdFiles all mdRef elements in the manifest
protected org.jdom.Element	mets root element of the current METS manifest.
static org.jdom.Namespace	metsNS METS namespace -- includes "mets" prefix for use in XPaths
protected org.jdom.input.SAXBuilder	parser builder to use for mdRef streams, inherited from create()
static org.jdom.Namespace	xlinkNS XLink namespace -- includes "xlink" prefix prefix for use in XPaths

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	METSManifest(org.jdom.input.SAXBuilder builder, org.jdom.Element mets, String configName) Default constructor, only called internally.

Method Summary

Modifier and Type	Method and Description
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	crosswalkBundle(Context context, PackageParameters params, Bundle bundle, String fileId, METSManifest.Mdref callback)
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.
protected void	crosswalkXmd(Context context, PackageParameters params, DSpaceObject dso, org.jdom.Element xmd, METSManifest.Mdref callback, boolean createMissingMetadataFields)
protected String[]	getAmdIDs() Get an array of all AMDID values for this object
List<org.jdom.Element>	getBundleFiles() Gets all file elements which make up the item's content.
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.
static String	getBundleName(org.jdom.Element file, boolean getParent) 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()
protected Object	getCrosswalk(String type, Class clazz)
org.jdom.Element[]	getDmdElements(String dmdList) Gets all dmdSec elements from a space separated list
protected org.jdom.Element	getElementByXPath(String path, boolean nullOk)
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.
protected static String	normalizeBundleName(String in)

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

CONFIG_XSD_PREFIX

protected static final String CONFIG_XSD_PREFIX

prefix of config lines identifying local XML Schema (XSD) files

See Also:

Constant Field Values

dcNS

protected static final org.jdom.Namespace dcNS

Dublin core element namespace

dcTermNS

protected static final org.jdom.Namespace dcTermNS

Dublin core term namespace (for qualified DC)

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

mets

protected org.jdom.Element mets

root element of the current METS manifest.

mdFiles

protected List mdFiles

all mdRef elements in the manifest

contentFiles

protected List<org.jdom.Element> contentFiles

<file> elements in "original" file group (bundle)

bundleFiles

protected List<org.jdom.Element> bundleFiles

parser

protected org.jdom.input.SAXBuilder parser

builder to use for mdRef streams, inherited from create()

configName

protected String configName

name of packager who created this manifest object, for looking up configuration entries.

localSchemas

protected static String localSchemas

Constructor Detail

METSManifest

protected METSManifest(org.jdom.input.SAXBuilder builder,
                       org.jdom.Element mets,
                       String configName)

Default constructor, only called internally.

Parameters:

builder - XML parser (for parsing mdRef'd files and binData)

mets - parsed METS document

configName - config name

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.

configName - config name

Returns:

new METSManifest object.

Throws:

IOException - if IO error

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

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

getBundleFiles

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

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

Returns:

a List of Elements.

Throws:

MetadataValidationException - if validation error

getContentFiles

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

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 - if validation error

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.

normalizeBundleName

protected static String normalizeBundleName(String in)

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.

Parameters:

file - file element

Returns:

DSpace bundle name

Throws:

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

getBundleName

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

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

Parameters:

file - file element

getParent - parent flag

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.

Parameters:

file - file element

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 - if validation error

getMdType

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

Get the metadata type from within a *mdSec element.

Parameters:

mdSec - mdSec element

Returns:

metadata type name.

Throws:

MetadataValidationException - if validation error

getMdContentMimeType

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

Returns MIME type of metadata content, if available.

Parameters:

mdSec - mdSec element

Returns:

MIMEtype word, or null if none is available.

Throws:

MetadataValidationException - if validation error

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.

Parameters:

mdSec - mdSec element

callback - mdref callback

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 - if invalid package

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

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.

Parameters:

mdSec - mdSec element

callback - mdref callback

Returns:

Stream containing contents of metadata section. Never returns null.

Throws:

MetadataValidationException - if METS format does not contain any metadata.

PackageValidationException - if invalid package

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

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 - if metadata validation error

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 - if metadata validation error

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 - if metadata validation error

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 - if metadata validation error

getElementByXPath

protected org.jdom.Element getElementByXPath(String path,
                                             boolean nullOk)
                                      throws MetadataValidationException

Throws:

MetadataValidationException

getCrosswalk

protected Object getCrosswalk(String type,
                              Class clazz)

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.

Parameters:

context - context

callback - mdref callback

dso - DSpaceObject

params - package params

dmdSec - dmdSec element

Throws:

MetadataValidationException - if METS error

CrosswalkException - if crosswalk error

PackageValidationException - if invalid package

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

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.

Parameters:

context - context

callback - mdref callback

params - package params

dso - DSpaceObject

Throws:

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

PackageValidationException - if invalid package

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

CrosswalkException

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.

Parameters:

context - context

callback - mdref callback

params - package params

dso - DSpaceObject

Returns:

true if any metadata section was actually crosswalked, false otherwise

Throws:

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

PackageValidationException - if invalid package

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

CrosswalkException - if crosswalk error

getAmdIDs

protected String[] getAmdIDs()
                      throws MetadataValidationException

Get an array of all AMDID values for this object

Returns:

array of all AMDID values for this object

Throws:

MetadataValidationException - if metadata validation error

crosswalkXmd

protected void crosswalkXmd(Context context,
                            PackageParameters params,
                            DSpaceObject dso,
                            org.jdom.Element xmd,
                            METSManifest.Mdref callback,
                            boolean createMissingMetadataFields)
                     throws MetadataValidationException,
                            PackageValidationException,
                            CrosswalkException,
                            IOException,
                            SQLException,
                            AuthorizeException

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 - mdref callback

Throws:

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

PackageValidationException - if invalid package

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

CrosswalkException - if crosswalk error

crosswalkBundle

public void crosswalkBundle(Context context,
                            PackageParameters params,
                            Bundle bundle,
                            String fileId,
                            METSManifest.Mdref callback)
                     throws MetadataValidationException,
                            PackageValidationException,
                            CrosswalkException,
                            IOException,
                            SQLException,
                            AuthorizeException

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