org.dspace.content

Class Collection

java.lang.Object

org.dspace.content.DSpaceObject

org.dspace.content.Collection

public class Collection
extends DSpaceObject

Class representing a collection.

The collection's metadata (name, introductory text etc), workflow groups, and default group of submitters are loaded into memory. Changes to metadata are not written to the database until update is called. If you create or remove a workflow group, the change is only reflected in the database after calling update. The default group of submitters is slightly different - creating or removing this has instant effect.

Version:

$Revision$

Author:

Robert Tansley

Method Summary

Methods

Modifier and Type	Method and Description
void	addItem(Item item) Add an item to the collection.
void	canEdit()
void	canEdit(boolean useInheritance)
boolean	canEditBoolean()
boolean	canEditBoolean(boolean useInheritance)
int	countItems() counts items in this collection
Group	createAdministrators() Create a default administrators group if one does not already exist.
Group	createSubmitters() Create a default submitters group if one does not already exist.
void	createTemplateItem() Create an empty template item for this collection.
Group	createWorkflowGroup(int step) Create a workflow group for the given step if one does not already exist.
boolean	equals(java.lang.Object other) Return true if other is the same Collection as this object, false otherwise
static Collection	find(Context context, int id) Get a collection from the database.
static Collection[]	findAll(Context context) Get all collections in the system.
static Collection[]	findAll(Context context, java.lang.Integer limit, java.lang.Integer offset) Get all collections in the system.
static Collection[]	findAuthorized(Context context, Community comm, int actionID) return an array of collections that user has a given permission on (useful for trimming 'select to collection' list) or figuring out which collections a person is an editor for.
Group	getAdministrators() Get the default group of administrators, if there is one.
DSpaceObject	getAdminObject(int action) Return the dspace object where an ADMIN action right is sufficient to grant the initial authorize check.
ItemIterator	getAllItems() Get all the items in this collection.
Community[]	getCommunities() Get the communities this collection appears in
java.lang.String	getHandle() Get the Handle of the object.
int	getID() Get the internal ID of this collection
ItemIterator	getItems() Get the in_archive items in this collection.
ItemIterator	getItems(java.lang.Integer limit, java.lang.Integer offset) Get the in_archive items in this collection.
java.lang.String	getLicense() Get the license that users must grant before submitting to this collection.
java.lang.String	getLicenseCollection() Get the license that users must grant before submitting to this collection.
Bitstream	getLogo() Get the logo for the collection.
java.lang.String	getMetadata(java.lang.String field) Get the value of a metadata field
java.lang.String	getName() Get a proper name for the object.
DSpaceObject	getParentObject() Return the dspace object that "own" the current object in the hierarchy.
Group	getSubmitters() Get the default group of submitters, if there is one.
Item	getTemplateItem() Get the template item for this collection.
int	getType() return type found in Constants
Group	getWorkflowGroup(int step) Get the the workflow group corresponding to a particular workflow step.
boolean	hasCustomLicense() Find out if the collection has a custom license
int	hashCode()
void	removeAdministrators() Remove the administrators group, if no group has already been created then return without error.
void	removeItem(Item item) Remove an item.
void	removeSubmitters() Remove the submitters group, if no group has already been created then return without error.
void	removeTemplateItem() Remove the template item for this collection, if there is one.
void	setLicense(java.lang.String license) Set the license for this collection.
Bitstream	setLogo(java.io.InputStream is) Give the collection a logo.
void	setMetadata(java.lang.String field, java.lang.String value) Set a metadata value
void	setWorkflowGroup(int step, Group g) Set the workflow group corresponding to a particular workflow step.
void	update() Update the collection metadata (including logo and workflow groups) to the database.
void	updateLastModified()

Methods inherited from class org.dspace.content.DSpaceObject

addDetails, clearDetails, find, getDetails, getTypeText

Methods inherited from class java.lang.Object

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

Method Detail

find

public static Collection find(Context context,
              int id)
                       throws java.sql.SQLException

Get a collection from the database. Loads in the metadata

Parameters:

context - DSpace context object

id - ID of the collection

Returns:

the collection, or null if the ID is invalid.

Throws:

java.sql.SQLException

findAll

public static Collection[] findAll(Context context)
                            throws java.sql.SQLException

Get all collections in the system. These are alphabetically sorted by collection name.

Parameters:

context - DSpace context object

Returns:

the collections in the system

Throws:

java.sql.SQLException

findAll

public static Collection[] findAll(Context context,
                   java.lang.Integer limit,
                   java.lang.Integer offset)
                            throws java.sql.SQLException

Get all collections in the system. Adds support for limit and offset.

Parameters:

context -

limit -

offset -

Returns:

Throws:

java.sql.SQLException

getItems

public ItemIterator getItems()
                      throws java.sql.SQLException

Get the in_archive items in this collection. The order is indeterminate.

Returns:

an iterator over the items in the collection.

Throws:

java.sql.SQLException

getItems

public ItemIterator getItems(java.lang.Integer limit,
                    java.lang.Integer offset)
                      throws java.sql.SQLException

Get the in_archive items in this collection. The order is indeterminate. Provides the ability to use limit and offset, for efficient paging.

Parameters:

limit - Max number of results in set

offset - Number of results to jump ahead by. 100 = 100th result is first, not 100th page.

Returns:

an iterator over the items in the collection.

Throws:

java.sql.SQLException

getAllItems

public ItemIterator getAllItems()
                         throws java.sql.SQLException

Get all the items in this collection. The order is indeterminate.

Returns:

an iterator over the items in the collection.

Throws:

java.sql.SQLException

getID

public int getID()

Get the internal ID of this collection

Specified by:

getID in class DSpaceObject

Returns:

the internal identifier

getHandle

public java.lang.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()

getMetadata

public java.lang.String getMetadata(java.lang.String field)

Get the value of a metadata field

Parameters:

field - the name of the metadata field to get

Returns:

the value of the metadata field

Throws:

java.lang.IllegalArgumentException - if the requested metadata field doesn't exist

setMetadata

public void setMetadata(java.lang.String field,
               java.lang.String value)
                 throws java.util.MissingResourceException

Set a metadata value

Parameters:

field - the name of the metadata field to get

value - value to set the field to

Throws:

java.lang.IllegalArgumentException - if the requested metadata field doesn't exist

java.util.MissingResourceException

getName

public java.lang.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

getLogo

public Bitstream getLogo()

Get the logo for the collection. null is returned if the collection does not have a logo.

Returns:

the logo of the collection, or null

setLogo

public Bitstream setLogo(java.io.InputStream is)
                  throws AuthorizeException,
                         java.io.IOException,
                         java.sql.SQLException

Give the collection a logo. Passing in null removes any existing logo. You will need to set the format of the new logo bitstream before it will work, for example to "JPEG". Note that update will need to be called for the change to take effect. Setting a logo and not calling update later may result in a previous logo lying around as an "orphaned" bitstream.

Parameters:

is - the stream to use as the new logo

Returns:

the new logo bitstream, or null if there is no logo (null was passed in)

Throws:

AuthorizeException

java.io.IOException

java.sql.SQLException

createWorkflowGroup

public Group createWorkflowGroup(int step)
                          throws java.sql.SQLException,
                                 AuthorizeException

Create a workflow group for the given step if one does not already exist. Returns either the newly created group or the previously existing one. Note that while the new group is created in the database, the association between the group and the collection is not written until update is called.

Parameters:

step - the step (1-3) of the workflow to create or get the group for

Returns:

the workflow group associated with this collection

Throws:

java.sql.SQLException

AuthorizeException

setWorkflowGroup

public void setWorkflowGroup(int step,
                    Group g)

Set the workflow group corresponding to a particular workflow step. null can be passed in if there should be no associated group for that workflow step; any existing group is NOT deleted.

Parameters:

step - the workflow step (1-3)

g - the new workflow group, or null

getWorkflowGroup

public Group getWorkflowGroup(int step)

Get the the workflow group corresponding to a particular workflow step. This returns null if there is no group associated with this collection for the given step.

Parameters:

step - the workflow step (1-3)

Returns:

the group of reviewers or null

createSubmitters

public Group createSubmitters()
                       throws java.sql.SQLException,
                              AuthorizeException

Create a default submitters group if one does not already exist. Returns either the newly created group or the previously existing one. Note that other groups may also be allowed to submit to this collection by the authorization system.

Returns:

the default group of submitters associated with this collection

Throws:

java.sql.SQLException

AuthorizeException

removeSubmitters

public void removeSubmitters()
                      throws java.sql.SQLException,
                             AuthorizeException

Remove the submitters group, if no group has already been created then return without error. This will merely dereference the current submitters group from the collection so that it may be deleted without violating database constraints.

Throws:

java.sql.SQLException

AuthorizeException

getSubmitters

public Group getSubmitters()

Get the default group of submitters, if there is one. Note that the authorization system may allow others to submit to the collection, so this is not necessarily a definitive list of potential submitters.

The default group of submitters for collection 100 is the one called collection_100_submit.

Returns:

the default group of submitters, or null if there is no default group.

createAdministrators

public Group createAdministrators()
                           throws java.sql.SQLException,
                                  AuthorizeException

Create a default administrators group if one does not already exist. Returns either the newly created group or the previously existing one. Note that other groups may also be administrators.

Returns:

the default group of editors associated with this collection

Throws:

java.sql.SQLException

AuthorizeException

removeAdministrators

public void removeAdministrators()
                          throws java.sql.SQLException,
                                 AuthorizeException

Remove the administrators group, if no group has already been created then return without error. This will merely dereference the current administrators group from the collection so that it may be deleted without violating database constraints.

Throws:

java.sql.SQLException

AuthorizeException

getAdministrators

public Group getAdministrators()

Get the default group of administrators, if there is one. Note that the authorization system may allow others to be administrators for the collection.

The default group of administrators for collection 100 is the one called collection_100_admin.

Returns:

group of administrators, or null if there is no default group.

getLicense

public java.lang.String getLicense()

Get the license that users must grant before submitting to this collection. If the collection does not have a specific license, the site-wide default is returned.

Returns:

the license for this collection

getLicenseCollection

public java.lang.String getLicenseCollection()

Get the license that users must grant before submitting to this collection.

Returns:

the license for this collection

hasCustomLicense

public boolean hasCustomLicense()

Find out if the collection has a custom license

Returns:

true if the collection has a custom license

setLicense

public void setLicense(java.lang.String license)

Set the license for this collection. Passing in null means that the site-wide default will be used.

Parameters:

license - the license, or null

getTemplateItem

public Item getTemplateItem()
                     throws java.sql.SQLException

Get the template item for this collection. null is returned if the collection does not have a template. Submission mechanisms may copy this template to provide a convenient starting point for a submission.

Returns:

the item template, or null

Throws:

java.sql.SQLException

createTemplateItem

public void createTemplateItem()
                        throws java.sql.SQLException,
                               AuthorizeException

Create an empty template item for this collection. If one already exists, no action is taken. Caution: Make sure you call update on the collection after doing this, or the item will have been created but the collection record will not refer to it.

Throws:

java.sql.SQLException

AuthorizeException

removeTemplateItem

public void removeTemplateItem()
                        throws java.sql.SQLException,
                               AuthorizeException,
                               java.io.IOException

Remove the template item for this collection, if there is one. Note that since this has to remove the old template item ID from the collection record in the database, the collection record will be changed, including any other changes made; in other words, this method does an update.

Throws:

java.sql.SQLException

AuthorizeException

java.io.IOException

addItem

public void addItem(Item item)
             throws java.sql.SQLException,
                    AuthorizeException

Add an item to the collection. This simply adds a relationship between the item and the collection - it does nothing like set an issue date, remove a personal workspace item etc. This has instant effect; update need not be called.

Parameters:

item - item to add

Throws:

java.sql.SQLException

AuthorizeException

removeItem

public void removeItem(Item item)
                throws java.sql.SQLException,
                       AuthorizeException,
                       java.io.IOException

Remove an item. If the item is then orphaned, it is deleted.

Parameters:

item - item to remove

Throws:

java.sql.SQLException

AuthorizeException

java.io.IOException

update

public void update()
            throws java.sql.SQLException,
                   AuthorizeException

Update the collection metadata (including logo and workflow groups) to the database. Inserts if this is a new collection.

Specified by:

update in class DSpaceObject

Throws:

java.sql.SQLException

java.io.IOException

AuthorizeException

canEditBoolean

public boolean canEditBoolean()
                       throws java.sql.SQLException

Throws:

java.sql.SQLException

canEditBoolean

public boolean canEditBoolean(boolean useInheritance)
                       throws java.sql.SQLException

Throws:

java.sql.SQLException

canEdit

public void canEdit()
             throws AuthorizeException,
                    java.sql.SQLException

Throws:

AuthorizeException

java.sql.SQLException

canEdit

public void canEdit(boolean useInheritance)
             throws AuthorizeException,
                    java.sql.SQLException

Throws:

AuthorizeException

java.sql.SQLException

getCommunities

public Community[] getCommunities()
                           throws java.sql.SQLException

Get the communities this collection appears in

Returns:

array of Community objects

Throws:

java.sql.SQLException

equals

public boolean equals(java.lang.Object other)

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

Overrides:

equals in class java.lang.Object

Parameters:

other - object to compare to

Returns:

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

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

getType

public int getType()

return type found in Constants

Specified by:

getType in class DSpaceObject

Returns:

int Constants.COLLECTION

findAuthorized

public static Collection[] findAuthorized(Context context,
                          Community comm,
                          int actionID)
                                   throws java.sql.SQLException

return an array of collections that user has a given permission on (useful for trimming 'select to collection' list) or figuring out which collections a person is an editor for.

Parameters:

context -

comm - (optional) restrict search to a community, else null

actionID - of the action

Returns:

Collection [] of collections with matching permissions

Throws:

java.sql.SQLException

countItems

public int countItems()
               throws java.sql.SQLException

counts items in this collection

Returns:

total items

Throws:

java.sql.SQLException

getAdminObject

public DSpaceObject getAdminObject(int action)
                            throws java.sql.SQLException

Description copied from class: DSpaceObject

Return the dspace object where an ADMIN action right is sufficient to grant the initial authorize check.

Default behaviour is ADMIN right on the object grant right on all other action on the object itself. Subclass should override this method as needed.

Overrides:

getAdminObject in class DSpaceObject

Parameters:

action - ID of action being attempted, from org.dspace.core.Constants. The ADMIN action is not a valid parameter for this method, an IllegalArgumentException should be thrown

Returns:

the dspace object, if any, where an ADMIN action is sufficient to grant the original action

Throws:

java.sql.SQLException

getParentObject

public DSpaceObject getParentObject()
                             throws java.sql.SQLException

Description copied from class: DSpaceObject

Return the dspace object that "own" the current object in the hierarchy. Note that this method has a meaning slightly different from the getAdminObject because it is independent of the action but it is in a way related to it. It defines the "first" dspace object OTHER then the current one, where allowed ADMIN actions imply allowed ADMIN actions on the object self.

Overrides:

getParentObject in class DSpaceObject

Returns:

the dspace object that "own" the current object in the hierarchy

Throws:

java.sql.SQLException

updateLastModified

public void updateLastModified()

Specified by:

updateLastModified in class DSpaceObject