org.ispheres.server.core
Class ISphere

java.lang.Object
  org.ispheres.server.core.ISphere

All Implemented Interfaces:

ISphereAdminInterface, ISpherePublicInterface

public class ISphere
extends java.lang.Object
implements ISpherePublicInterface, ISphereAdminInterface

This object defines the external interface of an "iSphere" and is reponsible for maintaining collections of information. An iSphere is a piece of middleware which sits between a repository and an application. It provides a layer of communication which is common across many differing repositories. The iSphere also allows a user to "drill down" and retrieve objects and metadata in their original form.

Author:

Clinton Freeman mochumbo@users.sourceforge.net, Owen Jones, Jonathan Mezach

Field Summary

static java.lang.String

DATETIME_FORMAT The date and time format that is used by the iSphere application.

Fields inherited from interface org.ispheres.shared.core.ISpherePublicInterface

LOCAL_SCHEMA, UNIVERSAL_SCHEMA

Constructor Summary

ISphere(java.lang.String configFile)
Constructs an Isphere from a specific configuration file.

Method Summary

ProcessPublicInterface	add(int collectionId, MetadataObject localMetadata, DigitalObject digitalObject) Add the metadata and digital object to the local repository.
LogFile	consistancyCheck() Checks the consistancy of the ISphere.
TransformInterface[]	getCapabilities(int collectionId) Returns the list of transforms that can be performed on the objects stored in the specified collection.
protected Collection	getCollection(int collectionId) Returns the collection identified by the specified collection identifier.
MetadataObject	getCollectionMetadata(int collectionId) Returns the metadata for the collection with the specified identifier.
java.util.Vector	getCollections() Returns the list of collections that are registered with this iSphere as a list.
ProcessHandle	getHandle(int hi) This returns a handle to a process running within iSpheres.
MetadataObject	getISphereMetadata() Returns the metadata object describing the iSphere.
protected ThreadPool	getISpherePool()
static java.lang.String	getISphereURL() Returns the full URL where the iSphere is located.
Schema	getLocalSchema(int collectionId) Returns the local schema used for a particular collection.
ProcessPublicInterface	getMetadata(int collectionId, int sri, boolean schema) Retrieve the specified metadata record from the collection.
int	getNumCollections() This function returns the number of collections held by this iSphere.
ProcessPublicInterface	getObject(int collectionId, int sri) Retrieve the specified ISphereObject from the collection.
ProcessPublicInterface	getTransformedObject(int collectionId, int sri, TransformInterface[] trans) Retrieves a transformed object using the object in the specified collection at the specified record index as the source and using the supplied array of transforms as input for the transformation process.
ProcessPublicInterface	numSearchCollectionResults(int collectionId, java.lang.String searchTerm) Returns the total number of objects that match the specified search term.
ProcessPublicInterface	registerCollectionWithAuthorityServer(int collectionId) Registers a collection within this iSphere with the central authority server.
ProcessPublicInterface	registerWithAuthorityServer() Registers this iSphere with the central authority server.
ProcessPublicInterface	remove(int collectionId, int sri) Remove the specified record from the collection.
ProcessPublicInterface	searchCollection(int collectionId, java.lang.String searchTerm, int offSet, int num, boolean universal) Searches the local collection for objects that match the specified search term and are within the specified bounds and optionally returns results in the universal schema rather than the local schema.
SearchPublicInterface	searchForCollections(java.lang.String searchTerm, int num) Search for a specific collection, this function will search the authority isphere for collections which match the specified search term.
SearchPublicInterface	searchForISpheres(java.lang.String searchTerm, int num) Searches for a specific iSphere, this function will search the authority server for iSpheres.
SearchPublicInterface	searchLocalCollection(int collectionId, java.lang.String searchTerm, int num) Spawns a search process which will search a local collection for objects that match the specified search parameters.
ProcessPublicInterface	setMetadata(int collectionId, int sri, MetadataObject localMetadata) Replace the current records metadata with the new metadata.
void	shutDownISphere() This function shutsdown the HTTP server (and ISphere).
void	writeConfiguration() Writes out the current in-memory configuration to the configuration file from where the ISphere was configured.

Methods inherited from class java.lang.Object

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

Field Detail

DATETIME_FORMAT

public static final java.lang.String DATETIME_FORMAT

The date and time format that is used by the iSphere application.

See Also:

Constant Field Values

Constructor Detail

ISphere

public ISphere(java.lang.String configFile)
        throws java.lang.Exception

Constructs an Isphere from a specific configuration file.

Parameters:

configFile - A File object representing the XML configuration file.

Throws:

java.lang.Exception - Thrown when the iSphere cannot be initialised.

Method Detail

add

public final ProcessPublicInterface add(int collectionId,
                                        MetadataObject localMetadata,
                                        DigitalObject digitalObject)
                                 throws ISphereException

Add the metadata and digital object to the local repository.

Specified by:

add in interface ISpherePublicInterface

Parameters:

collectionId - the collection to add the new digital object too.

localMetadata - The metadata of the digtial object being added to the local repository.

digitalObject - The ISphereObject that is being added to the local repository.

Returns:

A reference to the Process that will perform this action.

Throws:

ISphereException - When unable to create add process.

See Also:

Add

consistancyCheck

public final LogFile consistancyCheck()
                               throws ISphereException

Checks the consistancy of the ISphere. A consistancy report is generated by this function.

Specified by:

consistancyCheck in interface ISphereAdminInterface

Returns:

A LogFile detailing the results of the consistancy check.

Throws:

ISphereException - Thrown when unable to check consistancy of the the iSphere.

getCapabilities

public final TransformInterface[] getCapabilities(int collectionId)
                                           throws ISphereException

Returns the list of transforms that can be performed on the objects stored in the specified collection. When the specified collection does not exist, an ISphereException is thrown.

Specified by:

getCapabilities in interface ISpherePublicInterface

Parameters:

collectionId - The collection identifier of the collection to get the capabilities for.

Returns:

The TransformInterface of the objects contained in this collection.

Throws:

ISphereException - If the specified collection does not exist.

getCollection

protected final Collection getCollection(int collectionId)

Returns the collection identified by the specified collection identifier.

Parameters:

collectionId - An int specifying the index of the collection in the list of collections.

Returns:

A Collection object, or null when the specified collection identifier does not exist.

getCollections

public final java.util.Vector getCollections()

Returns the list of collections that are registered with this iSphere as a list.

Returns:

An Vector containing Collection objects.

getCollectionMetadata

public final MetadataObject getCollectionMetadata(int collectionId)
                                           throws ISphereException

Returns the metadata for the collection with the specified identifier.

Specified by:

getCollectionMetadata in interface ISpherePublicInterface

Parameters:

collectionId - The unique identifier of the collection to get the metadata for.

Returns:

The metadata of the specified collection.

Throws:

ISphereException - If the specified collection does not exist.

See Also:

org.ispheres.server.core.process.GetCollectionMetadata

getISphereMetadata

public final MetadataObject getISphereMetadata()

Returns the metadata object describing the iSphere.

Specified by:

getISphereMetadata in interface ISpherePublicInterface

Returns:

The metadata describing the iSphere.

getISpherePool

protected final ThreadPool getISpherePool()

Returns:

the ThreadPool managing all the tasks that this iSphere is performing on behalf of client applications.

getISphereURL

public static final java.lang.String getISphereURL()

Returns the full URL where the iSphere is located.

Returns:

A String containing the full URL of the iSphere.

getLocalSchema

public final Schema getLocalSchema(int collectionId)
                            throws ISphereException

Returns the local schema used for a particular collection.

Specified by:

getLocalSchema in interface ISpherePublicInterface

Parameters:

collectionId - The id of the collection.

Returns:

The Schema of the specified collection.

Throws:

ISphereException - If the specified collection does not exist.

getMetadata

public final ProcessPublicInterface getMetadata(int collectionId,
                                                int sri,
                                                boolean schema)
                                         throws ISphereException

Retrieve the specified metadata record from the collection.

Specified by:

getMetadata in interface ISpherePublicInterface

Parameters:

collectionId - The collection containing the record

sri - The simple repository index of the record we want to retrieve.

schema - Return the metadata object in the universal or local schema. Use either UNIVERSAL_SCHEMA(true) or LOCAL_SCHEMA(false).

Returns:

A reference to the Process that will perform this action.

Throws:

ISphereException - When unable to spawn the process which fetches the metadata.

See Also:

GetMetadata

getNumCollections

public final int getNumCollections()

This function returns the number of collections held by this iSphere.

Returns:

A positive integer of the number of collections held within this iSphere.

getHandle

public final ProcessHandle getHandle(int hi)
                              throws ISphereException

This returns a handle to a process running within iSpheres.

Parameters:

hi - The index of the Process.

Returns:

A handle to a proecess running within iSpheres.

Throws:

ISphereException - When unable to find the Process identified by hi.

getObject

public final ProcessPublicInterface getObject(int collectionId,
                                              int sri)
                                       throws ISphereException

Retrieve the specified ISphereObject from the collection.

Specified by:

getObject in interface ISpherePublicInterface

Parameters:

collectionId - The collection containing the digital object.

sri - The simple repository index of the object we wish to fetch from the local repository.

Returns:

A reference to the Process that will perform this action.

Throws:

ISphereException - When unable to spawn the process which fetches the digital object.

See Also:

GetObject

getTransformedObject

public final ProcessPublicInterface getTransformedObject(int collectionId,
                                                         int sri,
                                                         TransformInterface[] trans)
                                                  throws ISphereException

Retrieves a transformed object using the object in the specified collection at the specified record index as the source and using the supplied array of transforms as input for the transformation process.

Specified by:

getTransformedObject in interface ISpherePublicInterface

Parameters:

collectionId - The collection to retrieve a transformed object from.

sri - The simple repository index of the original digital object.

trans - An array of TransformInterfaces that holds the information for each of the transformations to apply.

Returns:

A reference to the Process that will perform this action.

Throws:

ISphereException - When unable to spawn the process which fetches the transformed digital object.

See Also:

GetTransformedObject

registerCollectionWithAuthorityServer

public final ProcessPublicInterface registerCollectionWithAuthorityServer(int collectionId)
                                                                   throws ISphereException

Registers a collection within this iSphere with the central authority server. TODO Change this to be a simple synchronised function that accesses volatile variables. see Bug ID 0000010.

Specified by:

registerCollectionWithAuthorityServer in interface ISphereAdminInterface

Parameters:

collectionId - The unique identifier of the collection to register.

Returns:

A reference to the Process that will perform this action.

Throws:

ISphereException - If the specified collection does not exist.

See Also:

AuthorityServer

registerWithAuthorityServer

public final ProcessPublicInterface registerWithAuthorityServer()

Registers this iSphere with the central authority server. TODO Change this to be a simple synchronised function that accesses volatile variables. see Bug ID 0000010.

Specified by:

registerWithAuthorityServer in interface ISphereAdminInterface

Returns:

A reference to the Process that will perform this action.

See Also:

RegisterISphere

remove

public final ProcessPublicInterface remove(int collectionId,
                                           int sri)
                                    throws ISphereException

Remove the specified record from the collection.

Specified by:

remove in interface ISpherePublicInterface

Parameters:

collectionId - The collection to remove the digital object and metadata from.

sri - The simple repository index of the digital object you wish to remove.

Returns:

A reference to the Process that will perform this action.

Throws:

ISphereException - When unable to spawn the process that will remove the entry.

See Also:

Remove

searchForCollections

public final SearchPublicInterface searchForCollections(java.lang.String searchTerm,
                                                        int num)
                                                 throws ISphereException

Search for a specific collection, this function will search the authority isphere for collections which match the specified search term.

Specified by:

searchForCollections in interface ISpherePublicInterface

Parameters:

searchTerm - The term to use when searching for collections.

num - The number of results to return when calling getResults on the handle that is returned by this function.

Returns:

A reference to the Process that will perform the searching action.

Throws:

ISphereException - thrown when unable to create the search process.

See Also:

org.ispheres.server.core.process.CollectionSearch

searchForISpheres

public final SearchPublicInterface searchForISpheres(java.lang.String searchTerm,
                                                     int num)
                                              throws ISphereException

Searches for a specific iSphere, this function will search the authority server for iSpheres.

Specified by:

searchForISpheres in interface ISpherePublicInterface

Parameters:

searchTerm - The term to use when searching for iSpheres.

num - The number of results to return when calling getResults on the handle that is returned by this function.

Returns:

A reference to the search that will perform this action.

Throws:

ISphereException - thrown when unable to create the search process.

searchCollection

public final ProcessPublicInterface searchCollection(int collectionId,
                                                     java.lang.String searchTerm,
                                                     int offSet,
                                                     int num,
                                                     boolean universal)
                                              throws ISphereException

Searches the local collection for objects that match the specified search term and are within the specified bounds and optionally returns results in the universal schema rather than the local schema.

Specified by:

searchCollection in interface ISpherePublicInterface

Parameters:

collectionId - The unique identifier of the collection to search for objects.

searchTerm - The term to use when searching for digital objects.

offSet - The simple repository index to start searching from.

num - The number of results to return when calling getResults on the handle that is returned by this function.

universal - Set to true when results should be returned in the universal schema, rather than the local schema.

Returns:

A reference to the Process that will perform this action.

Throws:

ISphereException - Thrown when unable to fetch the collection and search it for metadata records.

See Also:

org.ispheres.server.core.process.LocalObjectSearch

numSearchCollectionResults

public final ProcessPublicInterface numSearchCollectionResults(int collectionId,
                                                               java.lang.String searchTerm)
                                                        throws ISphereException

Returns the total number of objects that match the specified search term.

Specified by:

numSearchCollectionResults in interface ISpherePublicInterface

Parameters:

collectionId - The unique identifier of the collection to search for objects.

searchTerm - The term to use when searching for digital objects.

Returns:

A reference to the Process that will perform this action.

Throws:

ISphereException - Thrown when unable to fetch the collection and count the number of metadatarecords that match the search term.

See Also:

NumSearchCollectionResults

searchLocalCollection

public final SearchPublicInterface searchLocalCollection(int collectionId,
                                                         java.lang.String searchTerm,
                                                         int num)
                                                  throws ISphereException

Spawns a search process which will search a local collection for objects that match the specified search parameters.

Specified by:

searchLocalCollection in interface ISpherePublicInterface

Parameters:

collectionId - The unique id of the local collection to search.

searchTerm - The term to use when searching for digital objects.

num - The number of results to return per page.

Returns:

A reference to the search that will perform the action.

Throws:

ISphereException - thrown when unable to create the searchProcess.

setMetadata

public final ProcessPublicInterface setMetadata(int collectionId,
                                                int sri,
                                                MetadataObject localMetadata)
                                         throws ISphereException

Replace the current records metadata with the new metadata.

Specified by:

setMetadata in interface ISpherePublicInterface

Parameters:

collectionId - The collection containing the record, you wish to update the metadata object of.

sri - The simple repository index of the metadata record to update.

localMetadata - The metadata to replace the old metadata with. (in the local schema).

Returns:

A index to the Process which is responsible for actually performing the setting of the metadata.

Throws:

ISphereException - When unable to fetch to spawn SetMetadata Process.

See Also:

SetMetadata

shutDownISphere

public final void shutDownISphere()

This function shutsdown the HTTP server (and ISphere).

Specified by:

shutDownISphere in interface ISphereAdminInterface

writeConfiguration

public final void writeConfiguration()

Writes out the current in-memory configuration to the configuration file from where the ISphere was configured.