org.dspace.content.packager

Class AbstractPackageIngester

java.lang.Object

org.dspace.content.packager.AbstractPackageIngester

All Implemented Interfaces:

PackageIngester

Direct Known Subclasses:

AbstractMETSIngester

public abstract class AbstractPackageIngester
extends Object
implements PackageIngester

An abstract implementation of a DSpace Package Ingester, which implements a few helper/utility methods that most (all?) PackageIngesters may find useful.

First, implements recursive functionality in ingestAll() and replaceAll() methods of the PackageIngester interface. These methods are setup to recursively call ingest() and replace() respectively.

Finally, it also implements several utility methods (createDSpaceObject(), finishCreateItem(), updateDSpaceObject()) which subclasses may find useful. This classes will allow subclasses to easily create/update objects without having to worry too much about normal DSpace submission workflows (which is taken care of in these utility methods).

All Package ingesters should either extend this abstract class or implement PackageIngester to better suit their needs.

Author:

Tim Donohue

See Also:

PackageIngester, PluginService

Field Summary

Fields

Modifier and Type	Field and Description
protected CollectionService	collectionService
protected HandleService	handleService
protected ItemService	itemService

Constructor Summary

Constructors

Constructor and Description
AbstractPackageIngester()

Method Summary

Modifier and Type	Method and Description
void	addPackageReference(DSpaceObject dso, String packageRef) During ingestion process, some submission information packages (SIPs) may reference other packages to be ingested (recursively).
protected void	addToIngestedMap(File pkgFile, DSpaceObject dso) Add parsed package and resulting DSpaceObject to list of successfully ingested/replaced objects.
protected List<String>	getIngestedList() Return List of all DSpaceObject Identifiers which have been ingested/replaced by this instance of the Ingester.
protected Map<File,String>	getIngestedMap() Return Map of all packages ingested and the DSpaceObjects which have been created/replaced by this instance of the Ingester.
List<String>	getPackageReferences(DSpaceObject dso) Return a list of known SIP references from a newly created DSpaceObject.
List<String>	ingestAll(Context context, DSpaceObject parent, File pkgFile, PackageParameters params, String license) Recursively create one or more DSpace Objects out of the contents of the ingested package (and all other referenced packages).
List<String>	replaceAll(Context context, DSpaceObject dso, File pkgFile, PackageParameters params) Recursively replace one or more DSpace Objects out of the contents of the ingested package (and all other referenced packages).

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.dspace.content.packager.PackageIngester

getParameterHelp, ingest, replace

Field Detail

collectionService

protected final CollectionService collectionService

itemService

protected final ItemService itemService

handleService

protected final HandleService handleService

Constructor Detail

AbstractPackageIngester

public AbstractPackageIngester()

Method Detail

ingestAll

public List<String> ingestAll(Context context,
                              DSpaceObject parent,
                              File pkgFile,
                              PackageParameters params,
                              String license)
                       throws PackageException,
                              UnsupportedOperationException,
                              CrosswalkException,
                              AuthorizeException,
                              SQLException,
                              IOException,
                              WorkflowException

Recursively create one or more DSpace Objects out of the contents of the ingested package (and all other referenced packages). The initial object is created under the indicated parent. All other objects are created based on their relationship to the initial object.

For example, a scenario may be to create a Collection based on a collection-level package, and also create an Item for every item-level package referenced by the collection-level package.

The output of this method is one or more newly created DSpaceObject Identifiers (i.e. Handles).

The packager may choose not to implement ingestAll, or simply forward the call to ingest if it is unable to support recursive ingestion.

The deposit license (Only significant for Item) is passed explicitly as a string since there is no place for it in many package formats. It is optional and may be given as null.

Specified by:

ingestAll in interface PackageIngester

Parameters:

context - DSpace context.

parent - parent under which to create the initial object (may be null -- in which case ingester must determine parent from package or throw an error).

pkgFile - The initial package file to ingest

params - Properties-style list of options (interpreted by each packager).

license - may be null, which takes default license.

Returns:

List of DSpaceObjects created

Throws:

PackageValidationException - if initial package (or any referenced package) is unacceptable or there is a fatal error in creating a DSpaceObject

UnsupportedOperationException - if this packager does not implement ingestAll

CrosswalkException - if crosswalk error

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

WorkflowException - if workflow error

PackageException

replaceAll

public List<String> replaceAll(Context context,
                               DSpaceObject dso,
                               File pkgFile,
                               PackageParameters params)
                        throws PackageException,
                               UnsupportedOperationException,
                               CrosswalkException,
                               AuthorizeException,
                               SQLException,
                               IOException,
                               WorkflowException

Recursively replace one or more DSpace Objects out of the contents of the ingested package (and all other referenced packages). The initial object to replace is indicated by dso. All other objects are replaced based on information provided in the referenced packages.

For example, a scenario may be to replace a Collection based on a collection-level package, and also replace *every* Item in that collection based on the item-level packages referenced by the collection-level package.

Please note that since the dso input only specifies the initial object to replace, any additional objects to replace must be determined based on the referenced packages (or initial package itself).

The output of this method is one or more replaced DSpaceObject Identifiers (i.e. Handles).

The packager may choose not to implement replaceAll, since it somewhat contradicts the archival nature of DSpace. It also may choose to forward the call to replace if it is unable to support recursive replacement.

Specified by:

replaceAll in interface PackageIngester

Parameters:

context - DSpace context.

dso - initial existing DSpace Object to be replaced, may be null if object to replace can be determined from package

pkgFile - The package file to ingest.

params - Properties-style list of options specific to this packager

Returns:

List of Identifiers of DSpaceObjects replaced

Throws:

PackageValidationException - if initial package (or any referenced package) is unacceptable or there is a fatal error in creating a DSpaceObject

UnsupportedOperationException - if this packager does not implement replaceAll

CrosswalkException - if crosswalk error

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

WorkflowException - if workflow error

PackageException

addPackageReference

public void addPackageReference(DSpaceObject dso,
                                String packageRef)

During ingestion process, some submission information packages (SIPs) may reference other packages to be ingested (recursively).

This method collects all references to other packages, so that we can choose to recursively ingest them, as necessary, alongside the DSpaceObject created from the original SIP.

References are collected based on the DSpaceObject created from the SIP (this way we keep the context of these references).

Parameters:

dso - DSpaceObject whose SIP referenced another package

packageRef - A reference to another package, which can be ingested after this one

getPackageReferences

public List<String> getPackageReferences(DSpaceObject dso)

Return a list of known SIP references from a newly created DSpaceObject.

These references should detail where another package exists which should be ingested alongside the current DSpaceObject.

The AbstractPackageIngester or an equivalent SIP handler is expected to understand how to deal with these package references.

Parameters:

dso - DSpaceObject whose SIP referenced other SIPs

Returns:

List of Strings which are the references to external submission ingestion packages (may be null if no SIPs were referenced)

addToIngestedMap

protected void addToIngestedMap(File pkgFile,
                                DSpaceObject dso)

Add parsed package and resulting DSpaceObject to list of successfully ingested/replaced objects.

Parameters:

pkgFile - the package file that was used to create the object

dso - the DSpaceObject created/replaced

getIngestedMap

protected Map<File,String> getIngestedMap()

Return Map of all packages ingested and the DSpaceObjects which have been created/replaced by this instance of the Ingester.

The Map "key" is the package file which was parsed, and the "value" is the Identifier (i.e. Handle) of the DSpaceObject which was created/replaced.

Returns:

Map of DSpaceObjects which have been created/replaced.

getIngestedList

protected List<String> getIngestedList()

Return List of all DSpaceObject Identifiers which have been ingested/replaced by this instance of the Ingester.

This list can be useful in reporting back to the user what content has been added or replaced. It's used by ingestAll() and replaceAll() to return this list of everything that was ingested/replaced.

Returns:

List of Identifiers for DSpaceObjects which have been added/replaced