AbstractMETSIngester (DSpace Kernel :: API and Implementation 1.8.0-rc3 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.dspace.content.packager
Class AbstractMETSIngester

java.lang.Object
  org.dspace.content.packager.AbstractPackageIngester
      org.dspace.content.packager.AbstractMETSIngester

All Implemented Interfaces:: PackageIngester

Direct Known Subclasses:: DSpaceAIPIngester, DSpaceMETSIngester

public abstract class AbstractMETSIngester
extends AbstractPackageIngester
extends AbstractPackageIngester

Base class for package ingester of METS (Metadata Encoding & Transmission Standard) Packages.
See http://www.loc.gov/standards/mets/.

This is a generic packager framework intended to be subclassed to create ingesters for more specific METS "profiles". METS is an abstract and flexible framework that can encompass many different kinds of metadata and inner package structures.

Package Parameters:

validate -- true/false attempt to schema-validate the METS manifest.
manifestOnly -- package consists only of a manifest document.
ignoreHandle -- true/false, ignore AIP's idea of handle when ingesting.
ignoreParent -- true/false, ignore AIP's idea of parent when ingesting.

Configuration Properties:

mets.CONFIGNAME.ingest.preserveManifest - if true, the METS manifest itself is preserved in a bitstream named mets.xml in the METADATA bundle. If it is false (the default), the manifest is discarded after ingestion.
mets.CONFIGNAME.ingest.manifestBitstreamFormat - short name of the bitstream format to apply to the manifest; MUST be specified when preserveManifest is true.
mets.default.ingest.crosswalk.MD_SEC_NAME = PLUGIN_NAME Establishes a default crosswalk plugin for the given type of metadata in a METS mdSec (e.g. "DC", "MODS"). The plugin may be either a stream or XML-oriented ingestion crosswalk. Subclasses can override the default mapping with their own, substituting their configurationName for "default" in the configuration property key above.
mets.CONFIGNAME.ingest.useCollectionTemplate - if true, when an item is created, use the collection template. If it is false (the default), any existing collection template is ignored.

Version:: $Revision: 6764 $
Author:: Larry Stone, Tim Donohue
See Also:: METSManifest, AbstractPackageIngester, PackageIngester

Nested Class Summary
`protected static class`	`AbstractMETSIngester.MdrefManager` An instance of ZipMdrefManager holds the state needed to retrieve the contents of an external metadata stream referenced by an `mdRef` element in a Zipped up METS manifest.

Constructor Summary
`AbstractMETSIngester()`

Method Summary
`protected void`	`addBitstreams(Context context, Item item, METSManifest manifest, File pkgFile, PackageParameters params, AbstractMETSIngester.MdrefManager mdRefCallback)` Add Bitstreams to an Item, based on the files listed in the METS Manifest
`protected void`	`addContainerLogo(Context context, DSpaceObject dso, METSManifest manifest, File pkgFile, PackageParameters params)` Add a Logo to a Community or Collection container object based on a METS Manifest.
`abstract void`	`addLicense(Context context, Item item, String license, Collection collection, PackageParameters params)` Add license(s) to Item based on contents of METS and other policies.
`protected void`	`addManifestBitstream(Context context, Item item, METSManifest manifest)` Save/Preserve the METS Manifest as a Bitstream attached to the given DSpace item.
`protected void`	`addTemplateItem(Context context, DSpaceObject dso, METSManifest manifest, File pkgFile, PackageParameters params, AbstractMETSIngester.MdrefManager callback)` Add a Template Item to a Collection container object based on a METS Manifest.
`abstract void`	`crosswalkObjectDmd(Context context, DSpaceObject dso, METSManifest manifest, AbstractMETSIngester.MdrefManager callback, org.jdom.Element[] dmds, PackageParameters params)` Select the `dmdSec` element(s) to apply to the Item.
`protected String`	`decodeHandleURN(String value)` Parse the hdl: URI/URN format into a raw Handle.
`abstract void`	`finishBitstream(Context context, Bitstream bs, org.jdom.Element mfile, METSManifest manifest, PackageParameters params)` Subclass-dependent final processing on a Bitstream; could include fixing up the name, bundle, other attributes.
`abstract void`	`finishObject(Context context, DSpaceObject dso, PackageParameters params)` Hook for final "finishing" operations on the new Object.
`abstract String`	`getConfigurationName()` Returns keyword that makes the configuration keys of this subclass unique, e.g.
`protected static InputStream`	`getFileInputStream(File pkgFile, PackageParameters params, String path)` Retrieve the inputStream for a File referenced from a specific path within a METS package.
`protected String`	`getManifestBitstreamFormat()`
`String`	`getObjectHandle(METSManifest manifest)` Determines the handle of the DSpace object represented in this METS doc.
`abstract int`	`getObjectType(METSManifest manifest)` Determines what type of DSpace object is represented in this METS doc.
`String`	`getParameterHelp()` Returns a user help string which should describe the additional valid command-line options that this packager implementation will accept when using the `-o` or `--option` flags with the Packager script.
`DSpaceObject`	`getParentObject(Context context, METSManifest manifest)` Determines what parent DSpace object is referenced in this METS doc.
`DSpaceObject`	`ingest(Context context, DSpaceObject parent, File pkgFile, PackageParameters params, String license)` Create a new DSpace object out of a METS content package.
`protected DSpaceObject`	`ingestObject(Context context, DSpaceObject parent, METSManifest manifest, File pkgFile, PackageParameters params, String license)` Ingest/import a single DSpace Object, based on the associated METS Manifest and the parameters passed to the METSIngester
`protected METSManifest`	`parsePackage(Context context, File pkgFile, PackageParameters params)` Parse a given input package, ultimately returning the METS manifest out of the package.
`protected boolean`	`preserveManifest()`
`protected void`	`removeObject(Context context, DSpaceObject dso)` Remove an existing DSpace Object (called during a replace)
`DSpaceObject`	`replace(Context context, DSpaceObject dsoToReplace, File pkgFile, PackageParameters params)` Replace an existing DSpace object with the contents of a METS-based package.
`protected DSpaceObject`	`replaceObject(Context context, DSpaceObject dso, METSManifest manifest, File pkgFile, PackageParameters params, String license)` Replace the contents of a single DSpace Object, based on the associated METS Manifest and the parameters passed to the METSIngester.
`protected boolean`	`useCollectionTemplate()`

Methods inherited from class org.dspace.content.packager.AbstractPackageIngester
`addPackageReference, addToIngestedList, getIngestedList, getPackageReferences, ingestAll, replaceAll`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

AbstractMETSIngester

public AbstractMETSIngester()

Method Detail

ingest

public DSpaceObject ingest(Context context,
                           DSpaceObject parent,
                           File pkgFile,
                           PackageParameters params,
                           String license)
                    throws PackageValidationException,
                           CrosswalkException,
                           AuthorizeException,
                           SQLException,
                           IOException

Create a new DSpace object out of a METS content package. All contents are dictated by the METS manifest. Package is a ZIP archive (or optionally bare manifest XML document). In a Zip, all files relative to top level and the manifest (as per spec) in mets.xml.

Parameters:: context - DSpace context.; parent - parent under which to create new object (may be null -- in which case ingester must determine parent from package or throw an error).; pkgFile - The package file to ingest; params - Properties-style list of options (interpreted by each packager).; license - may be null, which takes default license.
Returns:: DSpaceObject created by ingest.
Throws:: PackageValidationException - if package is unacceptable or there is a fatal error turning it into a DSpaceObject.; CrosswalkException; AuthorizeException; SQLException; IOException

parsePackage

protected METSManifest parsePackage(Context context,
                                    File pkgFile,
                                    PackageParameters params)
                             throws IOException,
                                    SQLException,
                                    AuthorizeException,
                                    MetadataValidationException

Parse a given input package, ultimately returning the METS manifest out of the package. METS manifest is assumed to be a file named 'mets.xml'

Parameters:: context - DSpace Context; pkgFile - package to parse; params - Ingestion parameters
Returns:: parsed out METSManifest
Throws:: IOException; SQLException; AuthorizeException; MetadataValidationException

ingestObject

protected DSpaceObject ingestObject(Context context,
                                    DSpaceObject parent,
                                    METSManifest manifest,
                                    File pkgFile,
                                    PackageParameters params,
                                    String license)
                             throws IOException,
                                    SQLException,
                                    AuthorizeException,
                                    CrosswalkException,
                                    MetadataValidationException,
                                    PackageValidationException

Ingest/import a single DSpace Object, based on the associated METS Manifest and the parameters passed to the METSIngester

Parameters:: context - DSpace Context; parent - Parent DSpace Object; manifest - the parsed METS Manifest; pkgFile - the full package file (which may include content files if a zip); params - Parameters passed to METSIngester; license - DSpace license agreement
Returns:: completed result as a DSpace object
Throws:: IOException; SQLException; AuthorizeException; CrosswalkException; MetadataValidationException; PackageValidationException

replaceObject

protected DSpaceObject replaceObject(Context context,
                                     DSpaceObject dso,
                                     METSManifest manifest,
                                     File pkgFile,
                                     PackageParameters params,
                                     String license)
                              throws IOException,
                                     SQLException,
                                     AuthorizeException,
                                     CrosswalkException,
                                     MetadataValidationException,
                                     PackageValidationException

Replace the contents of a single DSpace Object, based on the associated METS Manifest and the parameters passed to the METSIngester.

Parameters:: context - DSpace Context; dso - DSpace Object to replace; manifest - the parsed METS Manifest; pkgFile - the full package file (which may include content files if a zip); params - Parameters passed to METSIngester; license - DSpace license agreement
Returns:: completed result as a DSpace object
Throws:: IOException; SQLException; AuthorizeException; CrosswalkException; MetadataValidationException; PackageValidationException

addBitstreams

protected void addBitstreams(Context context,
                             Item item,
                             METSManifest manifest,
                             File pkgFile,
                             PackageParameters params,
                             AbstractMETSIngester.MdrefManager mdRefCallback)
                      throws SQLException,
                             IOException,
                             AuthorizeException,
                             MetadataValidationException,
                             CrosswalkException,
                             PackageValidationException

Add Bitstreams to an Item, based on the files listed in the METS Manifest

Parameters:: context - DSpace Context; item - DSpace Item; manifest - METS Manifest; pkgFile - the full package file (which may include content files if a zip); params - Ingestion Parameters; mdRefCallback - MdrefManager storing info about mdRefs in manifest
Throws:: SQLException; IOException; AuthorizeException; MetadataValidationException; CrosswalkException; PackageValidationException

addManifestBitstream

protected void addManifestBitstream(Context context,
                                    Item item,
                                    METSManifest manifest)
                             throws IOException,
                                    SQLException,
                                    AuthorizeException,
                                    PackageValidationException

Save/Preserve the METS Manifest as a Bitstream attached to the given DSpace item.

Parameters:: context - DSpace Context; item - DSpace Item; manifest - The METS Manifest
Throws:: SQLException; AuthorizeException; PackageValidationException; IOException

addContainerLogo

protected void addContainerLogo(Context context,
                                DSpaceObject dso,
                                METSManifest manifest,
                                File pkgFile,
                                PackageParameters params)
                         throws SQLException,
                                IOException,
                                AuthorizeException,
                                MetadataValidationException,
                                PackageValidationException

Add a Logo to a Community or Collection container object based on a METS Manifest.

Parameters:: context - DSpace Context; dso - DSpace Container Object; manifest - METS Manifest; pkgFile - the full package file (which may include content files if a zip); params - Ingestion Parameters
Throws:: SQLException; IOException; AuthorizeException; MetadataValidationException; PackageValidationException

addTemplateItem

protected void addTemplateItem(Context context,
                               DSpaceObject dso,
                               METSManifest manifest,
                               File pkgFile,
                               PackageParameters params,
                               AbstractMETSIngester.MdrefManager callback)
                        throws SQLException,
                               IOException,
                               AuthorizeException,
                               CrosswalkException,
                               PackageValidationException

Add a Template Item to a Collection container object based on a METS Manifest.

Parameters:: context - DSpace Context; dso - DSpace Container Object; manifest - METS Manifest; pkgFile - the full package file (which may include content files if a zip); params - Ingestion Parameters; callback - the MdrefManager (manages all external metadata files referenced by METS mdref elements)
Throws:: SQLException; IOException; AuthorizeException; MetadataValidationException; PackageValidationException; CrosswalkException

replace

public DSpaceObject replace(Context context,
                            DSpaceObject dsoToReplace,
                            File pkgFile,
                            PackageParameters params)
                     throws PackageValidationException,
                            CrosswalkException,
                            AuthorizeException,
                            SQLException,
                            IOException

Replace an existing DSpace object with the contents of a METS-based package. All contents are dictated by the METS manifest. Package is a ZIP archive (or optionally bare manifest XML document). In a Zip, all files relative to top level and the manifest (as per spec) in mets.xml.

This method is similar to ingest(), except that if the object already exists in DSpace, it is emptied of files and metadata. The METS-based package is then used to ingest new values for these.

Parameters:: context - DSpace Context; dsoToReplace - DSpace Object to be replaced (may be null if it will be specified in the METS manifest itself); pkgFile - The package file to ingest; params - Parameters passed from the packager script
Returns:: DSpaceObject created by ingest.
Throws:: PackageValidationException - if package is unacceptable or there is a fatal error turning it into a DSpace Object.; IOException; SQLException; AuthorizeException; CrosswalkException

preserveManifest

protected boolean preserveManifest()

getManifestBitstreamFormat

protected String getManifestBitstreamFormat()

useCollectionTemplate

protected boolean useCollectionTemplate()

decodeHandleURN

protected String decodeHandleURN(String value)

Parse the hdl: URI/URN format into a raw Handle.

Parameters:: value - handle URI string
Returns:: raw handle (with 'hdl:' prefix removed)

removeObject

protected void removeObject(Context context,
                            DSpaceObject dso)
                     throws AuthorizeException,
                            SQLException,
                            IOException

Remove an existing DSpace Object (called during a replace)

Parameters:: dso - DSpace Object
Throws:: AuthorizeException; SQLException; IOException

getParentObject

public DSpaceObject getParentObject(Context context,
                                    METSManifest manifest)
                             throws PackageValidationException,
                                    MetadataValidationException,
                                    SQLException

Determines what parent DSpace object is referenced in this METS doc.

This is a default implementation which assumes the parent will be specified in a <structMap LABEL="Parent">. You should override this method if your METS manifest specifies the parent object in another location.

Parameters:: context - DSpace Context; manifest - METS manifest
Throws:: PackageValidationException - if parent reference cannot be found in manifest; MetadataValidationException; SQLException

getObjectHandle

public String getObjectHandle(METSManifest manifest)
                       throws PackageValidationException,
                              MetadataValidationException,
                              SQLException

Determines the handle of the DSpace object represented in this METS doc.

This is a default implementation which assumes the handle of the DSpace Object can be found in the <mets> @OBJID attribute. You should override this method if your METS manifest specifies the handle in another location. If no handle was found then null is returned.

Parameters:: manifest - METS manifest
Throws:: PackageValidationException - if handle cannot be found in manifest; MetadataValidationException; SQLException

getFileInputStream

protected static InputStream getFileInputStream(File pkgFile,
                                                PackageParameters params,
                                                String path)
                                         throws MetadataValidationException,
                                                IOException

Retrieve the inputStream for a File referenced from a specific path within a METS package.

If the packager is set to 'manifest-only' (i.e. pkgFile is just a manifest), we assume the file is available for download via a URL.

Otherwise, the pkgFile is a Zip, so the file should be retrieved from within that Zip package.

Parameters:: pkgFile - the full package file (which may include content files if a zip); params - Parameters passed to METSIngester; path - the File path (either path in Zip package or a URL)
Returns:: the InputStream for the file
Throws:: MetadataValidationException; IOException

getParameterHelp

public String getParameterHelp()

Returns a user help string which should describe the additional valid command-line options that this packager implementation will accept when using the -o or --option flags with the Packager script.

Returns:: a string describing additional command-line options available with this packager

crosswalkObjectDmd

public abstract void crosswalkObjectDmd(Context context,
                                        DSpaceObject dso,
                                        METSManifest manifest,
                                        AbstractMETSIngester.MdrefManager callback,
                                        org.jdom.Element[] dmds,
                                        PackageParameters params)
                                 throws CrosswalkException,
                                        PackageValidationException,
                                        AuthorizeException,
                                        SQLException,
                                        IOException

Select the dmdSec element(s) to apply to the Item. The implementation is responsible for choosing which (if any) of the metadata sections to crosswalk to get the descriptive metadata for the item being ingested. It is responsible for calling the crosswalk, using the manifest's helper i.e. manifest.crosswalkItemDmd(context,item,dmdElement,callback); (The callback argument is a reference to itself since the class also implements the METSManifest.MdRef interface to fetch package files referenced by mdRef elements.)

Note that item and manifest are available as protected fields from the superclass.

Parameters:: context - the DSpace context; manifest - the METSManifest; callback - the MdrefManager (manages all external metadata files referenced by METS mdref elements); dmds - array of Elements, each a METS dmdSec that applies to the Item as a whole.; params -
Throws:: CrosswalkException; PackageValidationException; AuthorizeException; SQLException; IOException

addLicense

public abstract void addLicense(Context context,
                                Item item,
                                String license,
                                Collection collection,
                                PackageParameters params)
                         throws PackageValidationException,
                                AuthorizeException,
                                SQLException,
                                IOException

Add license(s) to Item based on contents of METS and other policies. The implementation of this method controls exactly what licenses are added to the new item, including the DSpace deposit license. It is given the collection (which is the source of a default deposit license), an optional user-supplied deposit license (in the form of a String), and the METS manifest. It should invoke manifest.getItemRightsMD() to get an array of rightsMd elements which might contain other license information of interest, e.g. a Creative Commons license.

This framework does not add any licenses by default.

Note that crosswalking rightsMD sections can also add a deposit or CC license to the object.

Parameters:: context - the DSpace context; collection - DSpace Collection to which the item is being submitted.; license - optional user-supplied Deposit License text (may be null)
Throws:: PackageValidationException; AuthorizeException; SQLException; IOException

finishObject

public abstract void finishObject(Context context,
                                  DSpaceObject dso,
                                  PackageParameters params)
                           throws PackageValidationException,
                                  CrosswalkException,
                                  AuthorizeException,
                                  SQLException,
                                  IOException

Hook for final "finishing" operations on the new Object. This method is called when the new Object is otherwise complete and ready to be returned. The implementation should use this opportunity to make whatever final checks and modifications are necessary.

Parameters:: context - the DSpace context; dso - the DSpace Object; params - the Packager Parameters
Throws:: PackageValidationException; CrosswalkException; AuthorizeException; SQLException; IOException

getObjectType

public abstract int getObjectType(METSManifest manifest)
                           throws PackageValidationException

Determines what type of DSpace object is represented in this METS doc.

Throws:: PackageValidationException

finishBitstream

public abstract void finishBitstream(Context context,
                                     Bitstream bs,
                                     org.jdom.Element mfile,
                                     METSManifest manifest,
                                     PackageParameters params)
                              throws MetadataValidationException,
                                     SQLException,
                                     AuthorizeException,
                                     IOException

Subclass-dependent final processing on a Bitstream; could include fixing up the name, bundle, other attributes.

Throws:: MetadataValidationException; SQLException; AuthorizeException; IOException

getConfigurationName

public abstract String getConfigurationName()

Returns keyword that makes the configuration keys of this subclass unique, e.g. if it returns NAME, the key would be: "mets.NAME.ingest.preserveManifest = true"