com.xerox.bantam.util
Class AbstractStorage

java.lang.Object
  |
  +--com.xerox.bantam.util.AbstractStorage

All Implemented Interfaces:

com.xerox.bantam.ext.Notification, Storage

public abstract class AbstractStorage

extends Object

implements Storage, com.xerox.bantam.ext.Notification

This is a base class for working up a storage. It has some basic functionality, but also implements Storage forcing all of its subclasses to implement that.

Version:

$Revision: 1.7 $, $Date: 2000/07/06 21:40:44 $

Author:

Keith Edwards

Fields inherited from interface com.xerox.bantam.Storage

FilesystemRepo, InternalRepo, WebRepo

Constructor Summary

AbstractStorage()

Method Summary

void	addQueryListener(Query q, com.xerox.bantam.ext.QueryListener ql) Add a query listener to a given storage, listening for a change in the results of query q.
protected static void	addToMap(Map map, Object key, Document doc) Used by the map creation routines.
int	countDocuments(Query query) Count how many documents match a given query.
Document	createDocument(DocumentType docType) This factory method is for creating documents from scratch.
abstract Document	createDocument(DocumentType docType, Schema schema, Map props) This factory method is for creating documents from scratch.
boolean	documentExists(String id) Determine whether the document named by 'id' exists.
abstract DocumentList	find(Query query) Find all documents that match a given query.
abstract Document	getDocument(String id) Get a document, given an ID.
Object	getExtension(Class ifclass) Get an object implementing an extension interface on this storage.
abstract String	getInfo() Get a description of this storage instance.
abstract String	getName() Get the name of this storage implementation.
Map	getValueDistribution(String propertyName) Returns a set of all of the values for the specified property.
Map	getValueDistribution(String propertyName, Query query) Returns a set of all the values for the specified property, but only over the documents matching the specified query.
Map	getValueMap(String propertyName) Get a value map that maps values to the documents with those values.
Map	getValueMap(String propertyName, Query query) Get a value map that maps values to the documents with those values.
abstract String	getVersion() Get the version of this storage implementation.
Document	importDocument(DocumentType docType, String repo, Object repoParams) Import a document from a given repository.
abstract Document	importDocument(DocumentType docType, String repoType, Object repoParams, Schema schema, Map props) Import a document from a given repository.
protected static void	incrementCount(HashMap map, Object key) Increment a counter in a given map.
void	register()
void	removeQueryListener(Query q, com.xerox.bantam.ext.QueryListener ql) Remove a query listener from a given storage.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.xerox.bantam.Storage

getQueryFactory, shutdown, validateSchema

Constructor Detail

AbstractStorage

public AbstractStorage()

Method Detail

getDocument

public abstract Document getDocument(String id)
                              throws StorageException

Get a document, given an ID. Some implementations may make the assumption that this call's conversion result should be cached. If the document cannot be found, this returns null.

XXX This really is bogus that it allows you to return null isn't this likely to be a programming error? Couldn't documentExists be made into abstract method that could handle this issue? XXX

Specified by:

getDocument in interface Storage

Parameters:

String - id the document ID to be converted into a document

Returns:

Document a reference to that document

Throws:

StorageException - something went wrong during the lookup

documentExists

public boolean documentExists(String id)
                       throws StorageException

Determine whether the document named by 'id' exists.

Specified by:

documentExists in interface Storage

Parameters:

String - id the document id of interest

Returns:

boolean true if the document is currently in the master document list, false otherwise.

createDocument

public Document createDocument(DocumentType docType)
                        throws StorageException

This factory method is for creating documents from scratch. We create subclasses of the class Document.

Specified by:

createDocument in interface Storage

Parameters:

DocumentType - type what kind of doc you want

Returns:

Document the freshly minted document

Throws:

SchemaException - something went wrong during the creation phase

See Also:

DocumentType, Document

createDocument

public abstract Document createDocument(DocumentType docType,
                                        Schema schema,
                                        Map props)
                                 throws StorageException

This factory method is for creating documents from scratch. We create subclasses of the class Document.

Specified by:

createDocument in interface Storage

Parameters:

DocumentType - type what kind of doc you want

Schema - a schema to immediately apply to the document

props - the properties to set so document conforms to schema

Returns:

Document the freshly minted document

Throws:

SchemaException - something went wrong during the creation phase

See Also:

DocumentType, Document

importDocument

public Document importDocument(DocumentType docType,
                               String repo,
                               Object repoParams)
                        throws StorageException

Import a document from a given repository.

Specified by:

importDocument in interface Storage

Parameters:

docType - what kind of doc you want

Throws:

StorageException - this is thrown if something goes wrong during the import.

See Also:

DocumentType, Document

importDocument

public abstract Document importDocument(DocumentType docType,
                                        String repoType,
                                        Object repoParams,
                                        Schema schema,
                                        Map props)
                                 throws StorageException

Import a document from a given repository.

Specified by:

importDocument in interface Storage

Parameters:

docType - what kind of doc you want

repoType - what repository you want

repoParams - XXX

Schema - schema the schema you want applied to the document

props - properties to set so schema can be immediately enforced

Throws:

StorageException - this is thrown if something goes wrong during the import.

See Also:

DocumentType, Document

countDocuments

public int countDocuments(Query query)
                   throws StorageException

Count how many documents match a given query.

Specified by:

countDocuments in interface Storage

Parameters:

Query - query to consider

Returns:

int the number of documents matching the query

Throws:

StorageException - something went wrong in the query evaluation

find

public abstract DocumentList find(Query query)
                           throws StorageException

Find all documents that match a given query.

Specified by:

find in interface Storage

Parameters:

Query - query query to run against the full document set. This cannot be null.

Returns:

DocumentList list of documents that meet the query and the schema. May be 0 sized, but will never be null.

Throws:

StorageException - something went wrong during the processing

getValueDistribution

public Map getValueDistribution(String propertyName)
                         throws StorageException

Returns a set of all of the values for the specified property.

Specified by:

getValueDistribution in interface Storage

Parameters:

String - propertyName the name of the property in question

Returns:

Map a map that maps values of the property asked for to number of documents that have that value

Throws:

StorageException - something went wrong computing the value map

getValueDistribution

public Map getValueDistribution(String propertyName,
                                Query query)
                         throws StorageException

Returns a set of all the values for the specified property, but only over the documents matching the specified query.

Currently this is implemented completely in the client and is slower than hell. Much of this computation could be profitably moved into the kernel...

Specified by:

getValueDistribution in interface Storage

Parameters:

String - propertyName the name of the property in question

Query - query the query to run to get the document set

Returns:

Map a map that maps values of the property asked for to number of documents with that property

Throws:

StorageException - something went wrong computing the value map

incrementCount

protected static void incrementCount(HashMap map,
                                     Object key)

Increment a counter in a given map. This is used by the getValues call when it wants to increment (or create) a counter in one of its maps.

Parameters:

HashMap - map the map to look in for the key value

Object - key the key to search for, whose value will be inceremented

getValueMap

public Map getValueMap(String propertyName)
                throws StorageException

Get a value map that maps values to the documents with those values.

Specified by:

getValueMap in interface Storage

Parameters:

String - propertyName the name of the property to partition on

Returns:

Map the map from values to ArrayLists

Throws:

StorageException - something went wrong computing the map

getValueMap

public Map getValueMap(String propertyName,
                       Query query)
                throws StorageException

Get a value map that maps values to the documents with those values. This search is restricted by a query.

Specified by:

getValueMap in interface Storage

Parameters:

String - propertyName the name of the property to partition on

Query - query the query to restrict this map to

Returns:

Map the map from values to ArrayLists

Throws:

StorageException - something went wrong computing the map

addToMap

protected static void addToMap(Map map,
                               Object key,
                               Document doc)

Used by the map creation routines. This routine updates the array list under key in map to include doc.

Parameters:

Map - map the map to update

Object - key the key value to update

Document - doc the document to add to the array list of documents

addQueryListener

public void addQueryListener(Query q,
                             com.xerox.bantam.ext.QueryListener ql)
                      throws StorageException

Add a query listener to a given storage, listening for a change in the results of query q.

Specified by:

addQueryListener in interface com.xerox.bantam.ext.Notification

Parameters:

Query - q the query to be evaluated

QueryListener - ql the object to get notified when the results of a query change

Throws:

StorageException - something went wrong trying to add the listener

removeQueryListener

public void removeQueryListener(Query q,
                                com.xerox.bantam.ext.QueryListener ql)
                         throws StorageException

Remove a query listener from a given storage. This listener is only stopped from listening on a given query.

Specified by:

removeQueryListener in interface com.xerox.bantam.ext.Notification

Parameters:

Query - q the query to be evaluated

QueryListener - ql the object to be removed

Throws:

StorageException - something went wrong trying to add the listener

getName

public abstract String getName()

Description copied from interface: Storage

Get the name of this storage implementation.

Specified by:

getName in interface Storage

Following copied from interface: com.xerox.bantam.Storage

Returns:

An implementation-dependent name.

getVersion

public abstract String getVersion()

Description copied from interface: Storage

Get the version of this storage implementation.

Specified by:

getVersion in interface Storage

Following copied from interface: com.xerox.bantam.Storage

Returns:

An implementation-dependent version identifier.

getInfo

public abstract String getInfo()

Description copied from interface: Storage

Get a description of this storage instance.

Specified by:

getInfo in interface Storage

Following copied from interface: com.xerox.bantam.Storage

Returns:

An implementation-dependent instance identifier.

register

public void register()

getExtension

public Object getExtension(Class ifclass)

Description copied from interface: Storage

Get an object implementing an extension interface on this storage. Clients should call this method rather than introspecting a particular Storage implementation object to find out whether a given extension interface is implemented. This method permits a given implementation to return a delegate object rather than implementing the extension interface directly in the Storage object. Support for extension interfaces is implementation dependent by definition.

Specified by:

getExtension in interface Storage

Following copied from interface: com.xerox.bantam.Storage

Parameters:

ifclass - Java interface

Returns:

object implementing the specified interface on this storage or null