org.dspace.content.packager

Class PackageUtils

java.lang.Object

org.dspace.content.packager.PackageUtils

public class PackageUtils
extends 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.

Field Summary

Fields

Modifier and Type	Field and Description
protected static BitstreamFormatService	bitstreamFormatService
protected static BitstreamService	bitstreamService
protected static BundleService	bundleService
protected static Map<String,String>	ccDCToMetadata
protected static String[]	ccMetadataMap
protected static Map<String,String>	ccMetadataToDC
protected static CollectionService	collectionService
protected static CommunityService	communityService
protected static HandleService	handleService
protected static InstallItemService	installItemService
protected static ItemService	itemService
protected static Map<String,String>	orphanGroups Lookaside list for translations we've already done, so we don't generate multiple names for the same group
protected static SiteService	siteService
protected static WorkspaceItemService	workspaceItemService

Constructor Summary

Constructors

Constructor and Description
PackageUtils()

Method Summary

Methods

Modifier and Type	Method and Description
static void	addDepositLicense(Context context, 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(Context context, DSpaceObject dso) Removes all metadata associated with a DSpace object.
static String	containerMetadataToDC(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, 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(File file) Creates the specified file (along with all parent directories) if it doesn't already exist.
static String	dcToContainerMetadata(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, String shortDesc, String MIMEType, String desc) Find or create a bitstream format to match the given short description.
static BitstreamFormat	findOrCreateBitstreamFormat(Context context, String shortDesc, String MIMEType, 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, String handle, PackageParameters params) Perform any final tasks on a newly created WorkspaceItem in order to finish ingestion of an Item.
static Bitstream	getBitstreamByFormat(Context context, Item item, BitstreamFormat bsf, String bnName) Find bitstream by its format, looking in a specific bundle.
static Bitstream	getBitstreamByName(Item item, String name) Find bitstream by its Name, looking in all bundles.
static Bitstream	getBitstreamByName(Item item, String bsName, String bnName) Find bitstream by its Name, looking in specific named bundle.
static String	getFileExtension(String filename) Utility method to retrieve the file extension off of a filename.
static String	getPackageName(DSpaceObject dso, 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(Context context, DSpaceObject dso) Remove all bitstreams (files) associated with a DSpace object.
static String	translateGroupNameForExport(Context context, 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 String	translateGroupNameForImport(Context context, String groupName) This method does the exact opposite of the translateGroupNameForExport() method.
static void	updateDSpaceObject(Context context, 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

Field Detail

ccMetadataMap

protected static final String[] ccMetadataMap

ccMetadataToDC

protected static final Map<String,String> ccMetadataToDC

ccDCToMetadata

protected static final Map<String,String> ccDCToMetadata

bitstreamService

protected static final BitstreamService bitstreamService

bitstreamFormatService

protected static final BitstreamFormatService bitstreamFormatService

bundleService

protected static final BundleService bundleService

communityService

protected static final CommunityService communityService

collectionService

protected static final CollectionService collectionService

installItemService

protected static final InstallItemService installItemService

handleService

protected static final HandleService handleService

workspaceItemService

protected static final WorkspaceItemService workspaceItemService

siteService

protected static final SiteService siteService

itemService

protected static final ItemService itemService

orphanGroups

protected static final Map<String,String> orphanGroups

Lookaside list for translations we've already done, so we don't generate multiple names for the same group

Constructor Detail

PackageUtils

public PackageUtils()

Method Detail

dcToContainerMetadata

public static String dcToContainerMetadata(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 String containerMetadataToDC(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 - if validation error

addDepositLicense

public static void addDepositLicense(Context context,
                     String license,
                     Item item,
                     Collection collection)
                              throws SQLException,
                                     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:

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

getBitstreamByName

public static Bitstream getBitstreamByName(Item item,
                           String name)
                                    throws 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:

SQLException - if database error

getBitstreamByName

public static Bitstream getBitstreamByName(Item item,
                           String bsName,
                           String bnName)
                                    throws 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:

SQLException - if database error

getBitstreamByFormat

public static Bitstream getBitstreamByFormat(Context context,
                             Item item,
                             BitstreamFormat bsf,
                             String bnName)
                                      throws SQLException

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

Parameters:

context - context

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:

SQLException - if database error

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,
                                          String shortDesc,
                                          String MIMEType,
                                          String desc)
                                                   throws 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:

SQLException - if database error

AuthorizeException - if authorization error

findOrCreateBitstreamFormat

public static BitstreamFormat findOrCreateBitstreamFormat(Context context,
                                          String shortDesc,
                                          String MIMEType,
                                          String desc,
                                          int supportLevel,
                                          boolean internal)
                                                   throws 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

supportLevel - support level

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

Returns:

BitstreamFormat object that was found or created. Never null.

Throws:

SQLException - if database error

AuthorizeException - if authorization error

findDepositLicense

public static Bitstream findDepositLicense(Context context,
                           Item item)
                                    throws SQLException,
                                           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:

SQLException - if database error

AuthorizeException - if authorization error

IOException - if the license bitstream can't be read

createDSpaceObject

public static DSpaceObject createDSpaceObject(Context context,
                              DSpaceObject parent,
                              int type,
                              String handle,
                              PackageParameters params)
                                       throws AuthorizeException,
                                              SQLException,
                                              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 - if authorization error

SQLException - if database error

IOException - if IO error

finishCreateItem

public static Item finishCreateItem(Context context,
                    WorkspaceItem wsi,
                    String handle,
                    PackageParameters params)
                             throws IOException,
                                    SQLException,
                                    AuthorizeException,
                                    WorkflowException

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:

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

WorkflowException - if workflow error

updateDSpaceObject

public static void updateDSpaceObject(Context context,
                      DSpaceObject dso)
                               throws AuthorizeException,
                                      SQLException,
                                      IOException

Commit all recent changes to DSpaceObject.

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

Parameters:

context - context

dso - DSpaceObject to update

Throws:

SQLException - if database error

AuthorizeException - if authorization error

IOException - if IO error

getFileExtension

public static String getFileExtension(String filename)

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

Parameters:

filename - Full filename

Returns:

file extension

getPackageName

public static String getPackageName(DSpaceObject dso,
                    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(File file)
                          throws 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 - file

Returns:

boolean true if succeeded, false otherwise

Throws:

IOException - if IO error

removeAllBitstreams

public static void removeAllBitstreams(Context context,
                       DSpaceObject dso)
                                throws SQLException,
                                       IOException,
                                       AuthorizeException

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

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

This method is useful for replace functionality.

Parameters:

context - context

dso - The object to remove all bitstreams from

Throws:

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

clearAllMetadata

public static void clearAllMetadata(Context context,
                    DSpaceObject dso)
                             throws SQLException,
                                    IOException,
                                    AuthorizeException

Removes all metadata associated with a DSpace object.

This method is useful for replace functionality.

Parameters:

context - context

dso - The object to remove all metadata from

Throws:

IOException - if IO error

SQLException - if database error

AuthorizeException - if authorization error

translateGroupNameForExport

public static String translateGroupNameForExport(Context context,
                                 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 - if package error

translateGroupNameForImport

public static String translateGroupNameForImport(Context context,
                                 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 - if package error