org.dspace.content.packager

Class PackageUtils

java.lang.Object

org.dspace.content.packager.PackageUtils

public class PackageUtils
extends java.lang.Object

Container class for code that is useful to many packagers.

Version:

$Revision$

Author:

Larry Stone

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PackageUtils.UnclosableInputStream Stream wrapper that does not allow its wrapped stream to be closed.

Constructor Summary

Constructors

Constructor and Description
PackageUtils()

Method Summary

Methods

Modifier and Type	Method and Description
static void	addDepositLicense(Context context, java.lang.String license, Item item, Collection collection) Add DSpace Deposit License to an Item.
static void	checkItemMetadata(Item item) Test that item has adequate metadata.
static void	clearAllMetadata(DSpaceObject dso) Removes all metadata associated with a DSpace object.
static java.lang.String	containerMetadataToDC(java.lang.String databaseField) Translate a Container's (Community or Collection) database column into a valid Dublin Core metadata field.
static DSpaceObject	createDSpaceObject(Context context, DSpaceObject parent, int type, java.lang.String handle, PackageParameters params) Create the specified DSpace Object, based on the passed in Package Parameters (along with other basic info required to create the object)
static boolean	createFile(java.io.File file) Creates the specified file (along with all parent directories) if it doesn't already exist.
static java.lang.String	dcToContainerMetadata(java.lang.String dcField) Translate a Dublin Core metadata field into a Container's (Community or Collection) database column for that metadata entry.
static Bitstream	findDepositLicense(Context context, Item item) Utility to find the license bitstream from an item
static BitstreamFormat	findOrCreateBitstreamFormat(Context context, java.lang.String shortDesc, java.lang.String MIMEType, java.lang.String desc) Find or create a bitstream format to match the given short description.
static BitstreamFormat	findOrCreateBitstreamFormat(Context context, java.lang.String shortDesc, java.lang.String MIMEType, java.lang.String desc, int supportLevel, boolean internal) Find or create a bitstream format to match the given short description.
static Item	finishCreateItem(Context context, WorkspaceItem wsi, java.lang.String handle, PackageParameters params) Perform any final tasks on a newly created WorkspaceItem in order to finish ingestion of an Item.
static Bitstream	getBitstreamByFormat(Item item, BitstreamFormat bsf, java.lang.String bnName) Find bitstream by its format, looking in a specific bundle.
static Bitstream	getBitstreamByName(Item item, java.lang.String name) Find bitstream by its Name, looking in all bundles.
static Bitstream	getBitstreamByName(Item item, java.lang.String bsName, java.lang.String bnName) Find bitstream by its Name, looking in specific named bundle.
static java.lang.String	getFileExtension(java.lang.String filename) Utility method to retrieve the file extension off of a filename.
static java.lang.String	getPackageName(DSpaceObject dso, java.lang.String fileExtension) Returns name of a dissemination information package (DIP), based on the DSpace object and a provided fileExtension
static boolean	isMetaInfoBundle(Bundle bn) Predicate, does this bundle container meta-information.
static void	removeAllBitstreams(DSpaceObject dso) Remove all bitstreams (files) associated with a DSpace object.
static java.lang.String	translateGroupNameForExport(Context context, java.lang.String groupName) When DSpace creates Default Group Names they are of a very specific format, for example: COMMUNITY_[ID]_ADMIN COLLECTION_[ID]_ADMIN COLLECTION_[ID]_SUBMIT COLLECTION_[ID]_WORKFLOW_STEP_#
static java.lang.String	translateGroupNameForImport(Context context, java.lang.String groupName) This method does the exact opposite of the translateGroupNameForExport() method.
static void	updateDSpaceObject(DSpaceObject dso) Commit all recent changes to DSpaceObject.

Methods inherited from class java.lang.Object

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

Constructor Detail

PackageUtils

public PackageUtils()

Method Detail

dcToContainerMetadata

public static java.lang.String dcToContainerMetadata(java.lang.String dcField)

Translate a Dublin Core metadata field into a Container's (Community or Collection) database column for that metadata entry.

e.g. "dc.title" would translate to the "name" database column

This method is of use when crosswalking Community or Collection metadata for ingest, as most ingest Crosswalks tend to deal with translating to DC-based metadata.

Parameters:

dcField - The dublin core metadata field

Returns:

The Community or Collection DB column where this metadata info is stored.

containerMetadataToDC

public static java.lang.String containerMetadataToDC(java.lang.String databaseField)

Translate a Container's (Community or Collection) database column into a valid Dublin Core metadata field. This is the opposite of 'dcToContainerMetadata()'.

e.g. the "name" database column would translate to "dc.title"

This method is of use when crosswalking Community or Collection metadata for dissemination, as most dissemination Crosswalks tend to deal with translating from DC-based metadata.

Parameters:

databaseField - The Community or Collection DB column

Returns:

The Dublin Core metadata field that this metadata translates to.

checkItemMetadata

public static void checkItemMetadata(Item item)
                              throws PackageValidationException

Test that item has adequate metadata. Check item for the minimal DC metadata required to ingest a new item, and throw a PackageValidationException if test fails. Used by all SIP processors as a common sanity test.

Parameters:

item - - item to test.

Throws:

PackageValidationException

addDepositLicense

public static void addDepositLicense(Context context,
                     java.lang.String license,
                     Item item,
                     Collection collection)
                              throws java.sql.SQLException,
                                     java.io.IOException,
                                     AuthorizeException

Add DSpace Deposit License to an Item. Utility function to add the a user-supplied deposit license or a default one if none was given; creates new bitstream in the "LICENSE" bundle and gives it the special license bitstream format.

Parameters:

context - - dspace context

license - - license string to add, may be null to invoke default.

item - - the item.

collection - - get the default license from here.

Throws:

java.sql.SQLException

java.io.IOException

AuthorizeException

getBitstreamByName

public static Bitstream getBitstreamByName(Item item,
                           java.lang.String name)
                                    throws java.sql.SQLException

Find bitstream by its Name, looking in all bundles.

Parameters:

item - Item whose bitstreams to search.

name - Bitstream's name to match.

Returns:

first bitstream found or null.

Throws:

java.sql.SQLException

getBitstreamByName

public static Bitstream getBitstreamByName(Item item,
                           java.lang.String bsName,
                           java.lang.String bnName)
                                    throws java.sql.SQLException

Find bitstream by its Name, looking in specific named bundle.

Parameters:

item - - dspace item whose bundles to search.

bsName - - name of bitstream to match.

bnName - - bundle name to match, or null for all.

Returns:

the format found or null if none found.

Throws:

java.sql.SQLException

getBitstreamByFormat

public static Bitstream getBitstreamByFormat(Item item,
                             BitstreamFormat bsf,
                             java.lang.String bnName)
                                      throws java.sql.SQLException

Find bitstream by its format, looking in a specific bundle. Used to look for particularly-typed Package Manifest bitstreams.

Parameters:

item - - dspace item whose bundles to search.

bsf - - BitstreamFormat object to match.

bnName - - bundle name to match, or null for all.

Returns:

the format found or null if none found.

Throws:

java.sql.SQLException

isMetaInfoBundle

public static boolean isMetaInfoBundle(Bundle bn)

Predicate, does this bundle container meta-information. I.e. does this bundle contain descriptive metadata or other metadata such as license bitstreams? If so we probably don't want to put it into the "content" section of a package; hence this predicate.

Parameters:

bn - -- the bundle

Returns:

true if this bundle name indicates it is a meta-info bundle.

findOrCreateBitstreamFormat

public static BitstreamFormat findOrCreateBitstreamFormat(Context context,
                                          java.lang.String shortDesc,
                                          java.lang.String MIMEType,
                                          java.lang.String desc)
                                                   throws java.sql.SQLException,
                                                          AuthorizeException

Find or create a bitstream format to match the given short description. Used by packager ingesters to obtain a special bitstream format for the manifest (and/or metadata) file.

NOTE: When creating a new format, do NOT set any extensions, since we don't want any file with the same extension, which may be something generic like ".xml", to accidentally get set to this format.

Parameters:

context - - the context.

shortDesc - - short descriptive name, used to locate existing format.

MIMEType - - MIME content-type

desc - - long description

Returns:

BitstreamFormat object that was found or created. Never null.

Throws:

java.sql.SQLException

AuthorizeException

findOrCreateBitstreamFormat

public static BitstreamFormat findOrCreateBitstreamFormat(Context context,
                                          java.lang.String shortDesc,
                                          java.lang.String MIMEType,
                                          java.lang.String desc,
                                          int supportLevel,
                                          boolean internal)
                                                   throws java.sql.SQLException,
                                                          AuthorizeException

Find or create a bitstream format to match the given short description. Used by packager ingesters to obtain a special bitstream format for the manifest (and/or metadata) file.

NOTE: When creating a new format, do NOT set any extensions, since we don't want any file with the same extension, which may be something generic like ".xml", to accidentally get set to this format.

Parameters:

context - - the context.

shortDesc - - short descriptive name, used to locate existing format.

MIMEType - - mime content-type

desc - - long description

internal - value for the 'internal' flag of a new format if created.

Returns:

BitstreamFormat object that was found or created. Never null.

Throws:

java.sql.SQLException

AuthorizeException

findDepositLicense

public static Bitstream findDepositLicense(Context context,
                           Item item)
                                    throws java.sql.SQLException,
                                           java.io.IOException,
                                           AuthorizeException

Utility to find the license bitstream from an item

Parameters:

context - DSpace context

item - the item

Returns:

the license bitstream or null

Throws:

java.io.IOException - if the license bitstream can't be read

java.sql.SQLException

AuthorizeException

createDSpaceObject

public static DSpaceObject createDSpaceObject(Context context,
                              DSpaceObject parent,
                              int type,
                              java.lang.String handle,
                              PackageParameters params)
                                       throws AuthorizeException,
                                              java.sql.SQLException,
                                              java.io.IOException

Create the specified DSpace Object, based on the passed in Package Parameters (along with other basic info required to create the object)

Parameters:

context - DSpace Context

parent - Parent Object

type - Type of new Object

handle - Handle of new Object (may be null)

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

Returns:

newly created DSpace Object (or null)

Throws:

AuthorizeException

java.sql.SQLException

java.io.IOException

finishCreateItem

public static Item finishCreateItem(Context context,
                    WorkspaceItem wsi,
                    java.lang.String handle,
                    PackageParameters params)
                             throws java.io.IOException,
                                    java.sql.SQLException,
                                    AuthorizeException

Perform any final tasks on a newly created WorkspaceItem in order to finish ingestion of an Item.

This may include starting up a workflow for the new item, restoring it, or archiving it (based on params passed in)

Parameters:

context - DSpace Context

wsi - Workspace Item that requires finishing

handle - Handle to assign to item (may be null)

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

Returns:

finished Item

Throws:

java.io.IOException

java.sql.SQLException

AuthorizeException

updateDSpaceObject

public static void updateDSpaceObject(DSpaceObject dso)
                               throws AuthorizeException,
                                      java.sql.SQLException,
                                      java.io.IOException

Commit all recent changes to DSpaceObject.

This method is necessary as there is no generic 'update()' on a DSpaceObject

Parameters:

dso - DSpaceObject to update

Throws:

AuthorizeException

java.sql.SQLException

java.io.IOException

getFileExtension

public static java.lang.String getFileExtension(java.lang.String filename)

Utility method to retrieve the file extension off of a filename.

Parameters:

filename - Full filename

Returns:

file extension

getPackageName

public static java.lang.String getPackageName(DSpaceObject dso,
                              java.lang.String fileExtension)

Returns name of a dissemination information package (DIP), based on the DSpace object and a provided fileExtension

Format: [dspace-obj-type]@[handle-with-dashes].[fileExtension] OR [dspace-obj-type]@internal-id-[dspace-ID].[fileExtension]

Parameters:

dso - DSpace Object to create file name for

fileExtension - file Extension of output file.

Returns:

filename of a DIP representing the DSpace Object

createFile

public static boolean createFile(java.io.File file)
                          throws java.io.IOException

Creates the specified file (along with all parent directories) if it doesn't already exist. If the file already exists, nothing happens.

Parameters:

file -

Returns:

boolean true if succeeded, false otherwise

Throws:

java.io.IOException

removeAllBitstreams

public static void removeAllBitstreams(DSpaceObject dso)
                                throws java.sql.SQLException,
                                       java.io.IOException,
                                       AuthorizeException

Remove all bitstreams (files) associated with a DSpace object.

If this object is an Item, it removes all bundles & bitstreams. If this object is a Community or Collection, it removes all logo bitstreams.

This method is useful for replace functionality.

Parameters:

dso - The object to remove all bitstreams from

Throws:

java.sql.SQLException

java.io.IOException

AuthorizeException

clearAllMetadata

public static void clearAllMetadata(DSpaceObject dso)
                             throws java.sql.SQLException,
                                    java.io.IOException,
                                    AuthorizeException

Removes all metadata associated with a DSpace object.

This method is useful for replace functionality.

Parameters:

dso - The object to remove all metadata from

Throws:

java.sql.SQLException

java.io.IOException

AuthorizeException

translateGroupNameForExport

public static java.lang.String translateGroupNameForExport(Context context,
                                           java.lang.String groupName)
                                                    throws PackageException

When DSpace creates Default Group Names they are of a very specific format, for example:

• COMMUNITY_[ID]_ADMIN
• COLLECTION_[ID]_ADMIN
• COLLECTION_[ID]_SUBMIT
• COLLECTION_[ID]_WORKFLOW_STEP_#

Although these names work fine within DSpace, the DSpace internal ID (represented by [ID] above) becomes meaningless when content is exported outside of DSpace. In order to make these Group names meaningful outside of DSpace, they must be translated into a different format:

COMMUNITY_[HANDLE]_ADMIN (e.g. COMMUNITY_hdl:123456789/10_ADMIN), etc.

This format replaces the internal ID with an external Handle identifier (which is expected to be more meaningful even when content is exported from DSpace).

This method prepares group names for export by replacing any found internal IDs with the appropriate external Handle identifier. If the group name doesn't have an embedded internal ID, it is returned as is. If the group name contains an embedded internal ID, but the corresponding Handle cannot be determined, then it will be translated to GROUP_[random]_[objectType]_[groupType] and not re-translated on import.

This method may be useful to any Crosswalks/Packagers which deal with import/export of DSpace Groups.

Also see the translateGroupNameForImport() method which does the opposite of this method.

Parameters:

context - current DSpace Context

groupName - Group's name

Returns:

the group name, with any internal IDs translated to Handles

Throws:

PackageException

translateGroupNameForImport

public static java.lang.String translateGroupNameForImport(Context context,
                                           java.lang.String groupName)
                                                    throws PackageException

This method does the exact opposite of the translateGroupNameForExport() method. It prepares group names for import by replacing any found external Handle identifiers with the appropriate DSpace Internal identifier. As a basic example, it would change a group named "COLLECTION_hdl:123456789/10_ADMIN" to a name similar to "COLLECTION_11_ADMIN (where '11' is the internal ID of that Collection).

If the group name either doesn't have an embedded handle, then it is returned as is. If it has an embedded handle, but the corresponding internal ID cannot be determined, then an error is thrown. It is up to the calling method whether that error should be displayed to the user or if the group should just be skipped (since its associated object doesn't currently exist).

This method may be useful to any Crosswalks/Packagers which deal with import/export of DSpace Groups.

Also see the translateGroupNameForExport() method which does the opposite of this method.

Parameters:

context - current DSpace Context

groupName - Group's name

Returns:

the group name, with any Handles translated to internal IDs

Throws:

PackageException