org.dspace.content
Class Item

java.lang.Object
  org.dspace.content.DSpaceObject
      org.dspace.content.Item

public class Item
extends DSpaceObject

Class representing an item in DSpace.

This class holds in memory the item Dublin Core metadata, the bundles in the item, and the bitstreams in those bundles. When modifying the item, if you modify the Dublin Core or the "in archive" flag, you must call update for the changes to be written to the database. Creating, adding or removing bundles or bitstreams has immediate effect in the database.

Version:

$Revision: 3112 $

Author:

Robert Tansley, Martin Hald

Field Summary

static String

ANY Wild card for Dublin Core metadata qualifiers/languages

Method Summary

void	addBundle(Bundle b) Add an existing bundle to this item.
void	addDC(String element, String qualifier, String lang, String value) Deprecated.
void	addDC(String element, String qualifier, String lang, String[] values) Deprecated.
void	addMetadata(String schema, String element, String qualifier, String lang, String value) Add a single metadata field.
void	addMetadata(String schema, String element, String qualifier, String lang, String[] values) Add metadata fields.
boolean	canEdit() return TRUE if context's user can edit item, false otherwise
void	clearDC(String element, String qualifier, String lang) Deprecated.
void	clearMetadata(String schema, String element, String qualifier, String lang) Clear metadata values.
Bundle	createBundle(String name) Create a bundle in this item, with immediate effect
Bitstream	createSingleBitstream(InputStream is) Convenience method, calls createSingleBitstream() with name "ORIGINAL"
Bitstream	createSingleBitstream(InputStream is, String name) Create a single bitstream in a new bundle.
void	decache() Remove item and all its sub-structure from the context cache.
boolean	equals(DSpaceObject other) Return true if other is the same Item as this object, false otherwise
static Item	find(Context context, int id) Get an item from the database.
static ItemIterator	findAll(Context context) Get all the items in the archive.
static ItemIterator	findBySubmitter(Context context, EPerson eperson) Find all the items in the archive by a given submitter.
Bundle[]	getBundles() Get the bundles in this item.
Bundle[]	getBundles(String name) Get the bundles matching a bundle name (name corresponds roughly to type)
Collection[]	getCollections() Get the collections this item is in.
Collection[]	getCollectionsNotLinked() Get the collections this item is not in.
Community[]	getCommunities() Get the communities this item is in.
DCValue[]	getDC(String element, String qualifier, String lang) Deprecated.
String	getHandle() Get the Handle of the object.
int	getID() Get the internal ID of this item.
Date	getLastModified() Get the date the item was last modified, or the current date if last_modified is null
DCValue[]	getMetadata(String mdString) Retrieve metadata field values from a given metadata string of the form .[.|.*]
DCValue[]	getMetadata(String schema, String element, String qualifier, String lang) Get metadata for the item in a chosen schema.
String	getName() Get a proper name for the object.
Bitstream[]	getNonInternalBitstreams() Get all non-internal bitstreams in the item.
Collection	getOwningCollection() Get the owning Collection for the item
EPerson	getSubmitter() Get the e-person that originally submitted this item
int	getType() return type found in Constants
void	inheritCollectionDefaultPolicies(Collection c) remove all policies on an item and its contents, and replace them with the DEFAULT_ITEM_READ and DEFAULT_BITSTREAM_READ policies belonging to the collection.
boolean	isArchived() Find out if the item is part of the main archive
boolean	isOwningCollection(Collection c) Return true if this Collection 'owns' this item
boolean	isWithdrawn() Find out if the item has been withdrawn
void	licenseGranted(String license, EPerson eperson) Store a copy of the license a user granted in this item.
void	move(Collection from, Collection to) Moves the item from one collection to another one
void	reinstate() Reinstate a withdrawn item
void	removeBundle(Bundle b) Remove a bundle.
void	removeDSpaceLicense() Remove just the DSpace license from an item This is useful to update the current DSpace license, in case the user must accept the DSpace license again (either the item was rejected, or resumed after saving)
void	removeGroupPolicies(Group g) remove all of the policies for item's bitstreams and bundles that belong to a given Group
void	removeLicenses() Remove all licenses from an item - it was rejected
void	replaceAllBitstreamPolicies(List newpolicies) remove all of the policies for item's bitstreams and bundles and replace them with a new list of policies
void	replaceAllItemPolicies(List newpolicies) remove all of the policies for item and replace them with a new list of policies
void	setArchived(boolean isArchived) Set the "is_archived" flag.
void	setOwningCollection(Collection c) Set the owning Collection for the item
void	setSubmitter(EPerson sub) Set the e-person that originally submitted this item.
void	update() Update the item "in archive" flag and Dublin Core metadata in the database
void	withdraw() Withdraw the item from the archive.

Methods inherited from class org.dspace.content.DSpaceObject

addDetails, clearDetails, find, getDetails

Methods inherited from class java.lang.Object

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

Field Detail

ANY

public static final String ANY

Wild card for Dublin Core metadata qualifiers/languages

See Also:

Constant Field Values

Method Detail

find

public static Item find(Context context,
                        int id)
                 throws SQLException

Get an item from the database. The item, its Dublin Core metadata, and the bundle and bitstream metadata are all loaded into memory.

Parameters:

context - DSpace context object

id - Internal ID of the item

Returns:

the item, or null if the internal ID is invalid.

Throws:

SQLException

findAll

public static ItemIterator findAll(Context context)
                            throws SQLException

Get all the items in the archive. Only items with the "in archive" flag set are included. The order of the list is indeterminate.

Parameters:

context - DSpace context object

Returns:

an iterator over the items in the archive.

Throws:

SQLException

findBySubmitter

public static ItemIterator findBySubmitter(Context context,
                                           EPerson eperson)
                                    throws SQLException

Find all the items in the archive by a given submitter. The order is indeterminate. Only items with the "in archive" flag set are included.

Parameters:

context - DSpace context object

eperson - the submitter

Returns:

an iterator over the items submitted by eperson

Throws:

SQLException

getID

public int getID()

Get the internal ID of this item. In general, this shouldn't be exposed to users

Specified by:

getID in class DSpaceObject

Returns:

the internal identifier

getHandle

public String getHandle()

Description copied from class: DSpaceObject

Get the Handle of the object. This may return null

Specified by:

getHandle in class DSpaceObject

Returns:

Handle of the object, or null if it doesn't have one

See Also:

DSpaceObject.getHandle()

isArchived

public boolean isArchived()

Find out if the item is part of the main archive

Returns:

true if the item is in the main archive

isWithdrawn

public boolean isWithdrawn()

Find out if the item has been withdrawn

Returns:

true if the item has been withdrawn

getLastModified

public Date getLastModified()

Get the date the item was last modified, or the current date if last_modified is null

Returns:

the date the item was last modified, or the current date if the column is null.

setArchived

public void setArchived(boolean isArchived)

Set the "is_archived" flag. This is public and only WorkflowItem.archive() should set this.

Parameters:

isArchived - new value for the flag

setOwningCollection

public void setOwningCollection(Collection c)

Set the owning Collection for the item

Parameters:

c - Collection

getOwningCollection

public Collection getOwningCollection()
                               throws SQLException

Get the owning Collection for the item

Returns:

Collection that is the owner of the item

Throws:

SQLException

getDC

@Deprecated
public DCValue[] getDC(String element,
                                  String qualifier,
                                  String lang)

Deprecated.

Get Dublin Core metadata for the item. Passing in a null value for qualifier or lang only matches Dublin Core fields where that qualifier or languages is actually null. Passing in Item.ANY retrieves all metadata fields with any value for the qualifier or language, including null

Examples:

Return values of the unqualified "title" field, in any language. Qualified title fields (e.g. "title.uniform") are NOT returned:

item.getDC( "title", null, Item.ANY );

Return all US English values of the "title" element, with any qualifier (including unqualified):

item.getDC( "title", Item.ANY, "en_US" );

The ordering of values of a particular element/qualifier/language combination is significant. When retrieving with wildcards, values of a particular element/qualifier/language combinations will be adjacent, but the overall ordering of the combinations is indeterminate.

Parameters:

element - the Dublin Core element. Item.ANY matches any element. null doesn't really make sense as all DC must have an element.

qualifier - the qualifier. null means unqualified, and Item.ANY means any qualifier (including unqualified.)

lang - the ISO639 language code, optionally followed by an underscore and the ISO3166 country code. null means only values with no language are returned, and Item.ANY means values with any country code or no country code are returned.

Returns:

Dublin Core fields that match the parameters

getMetadata

public DCValue[] getMetadata(String schema,
                             String element,
                             String qualifier,
                             String lang)

Get metadata for the item in a chosen schema. See MetadataSchema for more information about schemas. Passing in a null value for qualifier or lang only matches metadata fields where that qualifier or languages is actually null. Passing in Item.ANY retrieves all metadata fields with any value for the qualifier or language, including null

Examples:

Return values of the unqualified "title" field, in any language. Qualified title fields (e.g. "title.uniform") are NOT returned:

item.getMetadata("dc", "title", null, Item.ANY );

Return all US English values of the "title" element, with any qualifier (including unqualified):

item.getMetadata("dc, "title", Item.ANY, "en_US" );

The ordering of values of a particular element/qualifier/language combination is significant. When retrieving with wildcards, values of a particular element/qualifier/language combinations will be adjacent, but the overall ordering of the combinations is indeterminate.

Parameters:

schema - the schema for the metadata field. Must match the name of an existing metadata schema.

element - the element name. Item.ANY matches any element. null doesn't really make sense as all metadata must have an element.

qualifier - the qualifier. null means unqualified, and Item.ANY means any qualifier (including unqualified.)

lang - the ISO639 language code, optionally followed by an underscore and the ISO3166 country code. null means only values with no language are returned, and Item.ANY means values with any country code or no country code are returned.

Returns:

metadata fields that match the parameters

getMetadata

public DCValue[] getMetadata(String mdString)

Retrieve metadata field values from a given metadata string of the form .[.|.*]

Parameters:

mdString - The metadata string of the form .[.|.*]

addDC

@Deprecated
public void addDC(String element,
                             String qualifier,
                             String lang,
                             String[] values)

Deprecated.

Add Dublin Core metadata fields. These are appended to existing values. Use clearDC to remove values. The ordering of values passed in is maintained.

Parameters:

element - the Dublin Core element

qualifier - the Dublin Core qualifer, or null for unqualified

lang - the ISO639 language code, optionally followed by an underscore and the ISO3166 country code. null means the value has no language (for example, a date).

values - the values to add.

addDC

@Deprecated
public void addDC(String element,
                             String qualifier,
                             String lang,
                             String value)

Deprecated.

Add a single Dublin Core metadata field. This is appended to existing values. Use clearDC to remove values.

Parameters:

element - the Dublin Core element

qualifier - the Dublin Core qualifer, or null for unqualified

lang - the ISO639 language code, optionally followed by an underscore and the ISO3166 country code. null means the value has no language (for example, a date).

value - the value to add.

addMetadata

public void addMetadata(String schema,
                        String element,
                        String qualifier,
                        String lang,
                        String[] values)

Add metadata fields. These are appended to existing values. Use clearDC to remove values. The ordering of values passed in is maintained.

Parameters:

schema - the schema for the metadata field. Must match the name of an existing metadata schema.

element - the metadata element name

qualifier - the metadata qualifer name, or null for unqualified

lang - the ISO639 language code, optionally followed by an underscore and the ISO3166 country code. null means the value has no language (for example, a date).

values - the values to add.

addMetadata

public void addMetadata(String schema,
                        String element,
                        String qualifier,
                        String lang,
                        String value)

Add a single metadata field. This is appended to existing values. Use clearDC to remove values.

Parameters:

schema - the schema for the metadata field. Must match the name of an existing metadata schema.

element - the metadata element name

qualifier - the metadata qualifer, or null for unqualified

lang - the ISO639 language code, optionally followed by an underscore and the ISO3166 country code. null means the value has no language (for example, a date).

value - the value to add.

clearDC

@Deprecated
public void clearDC(String element,
                               String qualifier,
                               String lang)

Deprecated.

Clear Dublin Core metadata values. As with getDC above, passing in null only matches fields where the qualifier or language is actually null.Item.ANY will match any element, qualifier or language, including null. Thus, item.clearDC(Item.ANY, Item.ANY, Item.ANY) will remove all Dublin Core metadata associated with an item.

Parameters:

element - the Dublin Core element to remove, or Item.ANY

qualifier - the qualifier. null means unqualified, and Item.ANY means any qualifier (including unqualified.)

lang - the ISO639 language code, optionally followed by an underscore and the ISO3166 country code. null means only values with no language are removed, and Item.ANY means values with any country code or no country code are removed.

clearMetadata

public void clearMetadata(String schema,
                          String element,
                          String qualifier,
                          String lang)

Clear metadata values. As with getDC above, passing in null only matches fields where the qualifier or language is actually null.Item.ANY will match any element, qualifier or language, including null. Thus, item.clearDC(Item.ANY, Item.ANY, Item.ANY) will remove all Dublin Core metadata associated with an item.

Parameters:

schema - the schema for the metadata field. Must match the name of an existing metadata schema.

element - the Dublin Core element to remove, or Item.ANY

qualifier - the qualifier. null means unqualified, and Item.ANY means any qualifier (including unqualified.)

lang - the ISO639 language code, optionally followed by an underscore and the ISO3166 country code. null means only values with no language are removed, and Item.ANY means values with any country code or no country code are removed.

getSubmitter

public EPerson getSubmitter()
                     throws SQLException

Get the e-person that originally submitted this item

Returns:

the submitter

Throws:

SQLException

setSubmitter

public void setSubmitter(EPerson sub)

Set the e-person that originally submitted this item. This is a public method since it is handled by the WorkspaceItem class in the ingest package. update must be called to write the change to the database.

Parameters:

sub - the submitter

getCollections

public Collection[] getCollections()
                            throws SQLException

Get the collections this item is in. The order is indeterminate.

Returns:

the collections this item is in, if any.

Throws:

SQLException

getCommunities

public Community[] getCommunities()
                           throws SQLException

Get the communities this item is in. Returns an unordered array of the communities that house the collections this item is in, including parent communities of the owning collections.

Returns:

the communities this item is in.

Throws:

SQLException

getBundles

public Bundle[] getBundles()
                    throws SQLException

Get the bundles in this item.

Returns:

the bundles in an unordered array

Throws:

SQLException

getBundles

public Bundle[] getBundles(String name)
                    throws SQLException

Get the bundles matching a bundle name (name corresponds roughly to type)

Parameters:

name - name of bundle (ORIGINAL/TEXT/THUMBNAIL)

Returns:

the bundles in an unordered array

Throws:

SQLException

createBundle

public Bundle createBundle(String name)
                    throws SQLException,
                           AuthorizeException

Create a bundle in this item, with immediate effect

Parameters:

name - bundle name (ORIGINAL/TEXT/THUMBNAIL)

Returns:

the newly created bundle

Throws:

SQLException

AuthorizeException

addBundle

public void addBundle(Bundle b)
               throws SQLException,
                      AuthorizeException

Add an existing bundle to this item. This has immediate effect.

Parameters:

b - the bundle to add

Throws:

SQLException

AuthorizeException

removeBundle

public void removeBundle(Bundle b)
                  throws SQLException,
                         AuthorizeException,
                         IOException

Remove a bundle. This may result in the bundle being deleted, if the bundle is orphaned.

Parameters:

b - the bundle to remove

Throws:

SQLException

AuthorizeException

IOException

createSingleBitstream

public Bitstream createSingleBitstream(InputStream is,
                                       String name)
                                throws AuthorizeException,
                                       IOException,
                                       SQLException

Create a single bitstream in a new bundle. Provided as a convenience method for the most common use.

Parameters:

is - the stream to create the new bitstream from

name - is the name of the bundle (ORIGINAL, TEXT, THUMBNAIL)

Returns:

Bitstream that is created

Throws:

AuthorizeException

IOException

SQLException

createSingleBitstream

public Bitstream createSingleBitstream(InputStream is)
                                throws AuthorizeException,
                                       IOException,
                                       SQLException

Convenience method, calls createSingleBitstream() with name "ORIGINAL"

Parameters:

is - InputStream

Returns:

created bitstream

Throws:

AuthorizeException

IOException

SQLException

getNonInternalBitstreams

public Bitstream[] getNonInternalBitstreams()
                                     throws SQLException

Get all non-internal bitstreams in the item. This is mainly used for auditing for provenance messages and adding format.* DC values. The order is indeterminate.

Returns:

non-internal bitstreams.

Throws:

SQLException

licenseGranted

public void licenseGranted(String license,
                           EPerson eperson)
                    throws SQLException,
                           IOException,
                           AuthorizeException

Store a copy of the license a user granted in this item.

Parameters:

license - the license the user granted

eperson - the eperson who granted the license

Throws:

SQLException

IOException

AuthorizeException

removeDSpaceLicense

public void removeDSpaceLicense()
                         throws SQLException,
                                AuthorizeException,
                                IOException

Remove just the DSpace license from an item This is useful to update the current DSpace license, in case the user must accept the DSpace license again (either the item was rejected, or resumed after saving)

This method is used by the org.dspace.submit.step.LicenseStep class

Throws:

SQLException

AuthorizeException

IOException

removeLicenses

public void removeLicenses()
                    throws SQLException,
                           AuthorizeException,
                           IOException

Remove all licenses from an item - it was rejected

Throws:

SQLException

AuthorizeException

IOException

update

public void update()
            throws SQLException,
                   AuthorizeException

Update the item "in archive" flag and Dublin Core metadata in the database

Throws:

SQLException

AuthorizeException

withdraw

public void withdraw()
              throws SQLException,
                     AuthorizeException,
                     IOException

Withdraw the item from the archive. It is kept in place, and the content and metadata are not deleted, but it is not publicly accessible.

Throws:

SQLException

AuthorizeException

IOException

reinstate

public void reinstate()
               throws SQLException,
                      AuthorizeException,
                      IOException

Reinstate a withdrawn item

Throws:

SQLException

AuthorizeException

IOException

decache

public void decache()
             throws SQLException

Remove item and all its sub-structure from the context cache. Useful in batch processes where a single context has a long, multi-item lifespan

Throws:

SQLException

equals

public boolean equals(DSpaceObject other)

Return true if other is the same Item as this object, false otherwise

Parameters:

other - object to compare to

Returns:

true if object passed in represents the same item as this object

isOwningCollection

public boolean isOwningCollection(Collection c)

Return true if this Collection 'owns' this item

Parameters:

c - Collection

Returns:

true if this Collection owns this item

getType

public int getType()

return type found in Constants

Specified by:

getType in class DSpaceObject

Returns:

int Constants.ITEM

replaceAllItemPolicies

public void replaceAllItemPolicies(List newpolicies)
                            throws SQLException,
                                   AuthorizeException

remove all of the policies for item and replace them with a new list of policies

Parameters:

newpolicies - - this will be all of the new policies for the item and its contents

Throws:

SQLException

AuthorizeException

replaceAllBitstreamPolicies

public void replaceAllBitstreamPolicies(List newpolicies)
                                 throws SQLException,
                                        AuthorizeException

remove all of the policies for item's bitstreams and bundles and replace them with a new list of policies

Parameters:

newpolicies - - this will be all of the new policies for the bundle and bitstream contents

Throws:

SQLException

AuthorizeException

removeGroupPolicies

public void removeGroupPolicies(Group g)
                         throws SQLException

remove all of the policies for item's bitstreams and bundles that belong to a given Group

Parameters:

g - Group referenced by policies that needs to be removed

Throws:

SQLException

inheritCollectionDefaultPolicies

public void inheritCollectionDefaultPolicies(Collection c)
                                      throws SQLException,
                                             AuthorizeException

remove all policies on an item and its contents, and replace them with the DEFAULT_ITEM_READ and DEFAULT_BITSTREAM_READ policies belonging to the collection.

Parameters:

c - Collection

Throws:

SQLException - if an SQL error or if no default policies found. It's a bit draconian, but default policies must be enforced.

AuthorizeException

move

public void move(Collection from,
                 Collection to)
          throws SQLException,
                 AuthorizeException,
                 IOException

Moves the item from one collection to another one

Throws:

SQLException

AuthorizeException

IOException

getCollectionsNotLinked

public Collection[] getCollectionsNotLinked()
                                     throws SQLException

Get the collections this item is not in.

Returns:

the collections this item is not in, if any.

Throws:

SQLException

canEdit

public boolean canEdit()
                throws SQLException

return TRUE if context's user can edit item, false otherwise

Returns:

boolean true = current user can edit item

Throws:

SQLException

getName

public String getName()

Description copied from class: DSpaceObject

Get a proper name for the object. This may return null. Name should be suitable for display in a user interface.

Specified by:

getName in class DSpaceObject

Returns:

Name for the object, or null if it doesn't have one