Package org.dspace.content

package org.dspace.content
Provides an API for reading and manipulating content in the DSpace system.

The DSpace Data Model

Data in DSpace is stored in the model below. Multiple inclusion is permitted at every level; the documentation for each class describes the system's behaviour for coping with this.
Community Communities correspond to organisational units within an institution.
Collection Collections are groupings of related content. Each collection may have an associated workflow; this is the review process that submissions go through before being included in the archive.
Item Items are the basic archival units. An item corresponds to a single logical piece of content and associated metadata.
Bundle Bundles are groupings of Bitstreams that make no sense in isolation; for example, the files making up an HTML document would all go in one Bundle. A PDF version of the same Item, or a dataset stored with the Item, would go in a separate Bundle.
Bitstream Bitstreams are sequences of bits, typically files, that make up the raw content of Items.
Additionally, each Bitstream is associated with one Bitstream Format; this describes information about the format and encoding of the Bitstream, including a name (for example "Adobe PDF"), a MIME type and a support level.

Submissions are created as Workspace Items. A Workspace Item is an Item in progress. Once item assembly is complete, one of two things may happen:

  • If the Collection being submitted to has an associated workflow, it is started. At this point the Workspace Item becomes a Workflow Item.
  • If the Collection has no associated workflow, the Workspace Item is removed and the assembled Item is included in the Collection.
Workspace Items and Workflow Items may both be manipulated as In Progress Submissions.

Using the Content Management API

The general paradigm for using DSpace is to create a Context; this is akin to opening a connection to a database (which, coincidentally, is one of the things that happens.)

The classes in this package are then used to create in-memory snapshots that represent the corresponding logical objects stored in the system. When the reading or manipulating is done, the Context may either be aborted, in which case any changes made are discarded, or completed, in which case any changes made are committed to main DSpace storage.

If any error occurs if you are making changes, you should abort the current context, since the in-memory snapshots might be in an inconsistent state.

Typically, when changing a particular object in the system, the changes will not be written to main DSpace storage unless update is called on the object prior to Context completion. Where this is not the case, it is stated in the method documentation.

Instances of the classes in this package are tied to that Context; when the Context has been finished with the objects essentially become invalid.

An example use of the Content Management API is shown below: 

try
{
    // Create a DSpace context
    context = new org.dspace.core.Context();

    // Set the current user
    context.setCurrentUser(authenticatedUser)

    // Create my new collection
    Collection c = Collection.create(context);
    c.setMetadata("name", "My New Collection");
    c.update();   // Updates the metadata within the context

    // Find an item
    item = Item.find(context, 1234);
    
    // Remove it from its old collections
    Collection[] colls = item.getCollections();
    colls[0].removeItem(item);
    
    // Add it to my new collection
    c.addItem(item);
   
    // All went well; complete the context so changes are written
    context.complete();
}
catch (SQLException se)
{
    // Something went wrong with the database; abort the context so
    // no changes are written
    context.abort();
}
catch (AuthorizeException ae)
{
    // authenticatedUser does not have permission to perform one of the
    // above actions, so no changes should be made at all.
    context.abort();
}

// The context will have been completed or aborted here, so it may
// no longer be used, nor any objects that were created with it (e.g. item)
See Also: