eu.planets_project.ifr.core.storage.api
Interface DigitalObjectManager

All Known Subinterfaces:

DataRegistry

All Known Implementing Classes:

DigitalObjectManagerBase

public interface DigitalObjectManager

Interface for storage and retrieval of Digital Objects in an IF Data Registry.

Nested Class Summary

static class	DigitalObjectManager.DigitalObjectNotFoundException Exception thrown when a DigitalObject requested by URI cannot be found in the Data Registry.
static class	DigitalObjectManager.DigitalObjectNotRemovedException Exception thrown when a DigitalObject cannot be removed in the Data Registry.
static class	DigitalObjectManager.DigitalObjectNotStoredException Exception thrown when a DigitalObject cannot be stored in the Data Registry.
static class	DigitalObjectManager.DigitalObjectTooLargeException Exception thrown when a DigitalObject is too large.
static class	DigitalObjectManager.DigitalObjectUpdateException Exception thrown when a DigitalObject cann't be updated in JCR.

Method Summary

java.util.List<java.lang.Class<? extends Query>>	getQueryTypes()
boolean	isWritable(java.net.URI pdURI) Test if Digital Objects can be persisted.
java.util.List<java.net.URI>	list(java.net.URI pdURI) Returns the URIs of Digital Objects matching the given parent pdURI.
java.util.List<java.net.URI>	list(java.net.URI pdURI, Query q) Execute a more complex query, at some point in the URI tree.
DigitalObject	retrieve(java.net.URI pdURI) Retrieve a DigitalObject from the DataRegistry.
java.net.URI	storeAsNew(DigitalObject digitalObject) Persist a DigitalObject to the Data Registry as a new object
java.net.URI	storeAsNew(java.net.URI pdURI, DigitalObject digitalObject) Persist a DigitalObject to the Data Registry as a new object, associated the suggested URI if possible.
java.net.URI	updateExisting(java.net.URI pdURI, DigitalObject digitalObject) Updates an existing object in the repository to contain the given digital object.

Method Detail

storeAsNew

java.net.URI storeAsNew(DigitalObject digitalObject)
                        throws DigitalObjectManager.DigitalObjectNotStoredException

Persist a DigitalObject to the Data Registry as a new object

Parameters:

digitalObject - The object to store

Returns:

the pdURI where the object was stored.

Throws:

DigitalObjectManager.DigitalObjectNotStoredException - if the storing somehow failed

storeAsNew

java.net.URI storeAsNew(java.net.URI pdURI,
                        DigitalObject digitalObject)
                        throws DigitalObjectManager.DigitalObjectNotStoredException

Persist a DigitalObject to the Data Registry as a new object, associated the suggested URI if possible. If a particular implementation does not permit the caller to dictate the store layout, the URI may be overridden. Consequently, the returned URI should be retained as the object reference, not the passed one.

Parameters:

pdURI - The suggested URI to associate with the stored object.

digitalObject - The object to store.

Returns:

the pdURI A URI associated with the newly-stored object and which could be used to recover it via the .read(URI) method.

Throws:

DigitalObjectManager.DigitalObjectNotStoredException - if the storing somehow failed

updateExisting

java.net.URI updateExisting(java.net.URI pdURI,
                            DigitalObject digitalObject)
                            throws DigitalObjectManager.DigitalObjectNotStoredException,
                                   DigitalObjectManager.DigitalObjectNotFoundException

Updates an existing object in the repository to contain the given digital object. The repository might create a new object for the new version. This method returns the uri of the updated object.

Parameters:

pdURI - the object to update

digitalObject - the information to update with

Returns:

the id of the updated object

Throws:

DigitalObjectManager.DigitalObjectNotStoredException - if the storing somehow failed

DigitalObjectManager.DigitalObjectNotFoundException

isWritable

boolean isWritable(java.net.URI pdURI)

Test if Digital Objects can be persisted.

Parameters:

pdURI - The URI that we wish to write to, or NULL to test if the whole repository is read-only.

Returns:

false if the 'store' method should work for this URI. If the whole DOM is a read-only system, then return false when pdURI == NULL. If some parts are writable, return true when pdURI == NULL.

list

java.util.List<java.net.URI> list(java.net.URI pdURI)

Returns the URIs of Digital Objects matching the given parent pdURI. If the pdURI points to a 'file' (A Digital Object) then this should return null. If the pdURI points to a 'directory', then this should return a valid List object, with zero or more entries. If the Query has been set, only return matching Digital Objects.

Parameters:

pdURI - URI that identifies an Digital Object or folder

Returns:

an array of all child URIs. Empty folders return an empty list, and files return null.

retrieve

DigitalObject retrieve(java.net.URI pdURI)
                       throws DigitalObjectManager.DigitalObjectNotFoundException

Retrieve a DigitalObject from the DataRegistry. Implementations of this method are currently expected to set the Title of the DigitalObject to a sensible filename, as this information may be used to write the data to temporary storage systems. TODO Perhaps remove the above, as persisted files should really use the leafname from the URI?

Parameters:

pdURI - URI that uniquely identifies the DigitalObject

Returns:

the DigitalObject retrieved from the registry

Throws:

DigitalObjectManager.DigitalObjectNotFoundException - If the digital object with this URI is not found in the repository

getQueryTypes

java.util.List<java.lang.Class<? extends Query>> getQueryTypes()

Returns:

An array of the types of query that are supported. If your interface does not support queries, please return null.

list

java.util.List<java.net.URI> list(java.net.URI pdURI,
                                  Query q)
                                  throws QueryValidationException

Execute a more complex query, at some point in the URI tree. If the query does not make sense, throw an exception. Ideally, include a message in said exception that can be shown to the user so that they might improve their query.

Parameters:

pdURI - The URI in the repository at which the query should be executed. Can be null, meaning at the top-level.

q - The Query to be executed.

Returns:

the List of Digital Object URIs that matched the query

Throws:

eu.planets_project.ifr.core.storage.api.query.QueryValidationException - if the query does not make sense

QueryValidationException