com.xerox.bantam
Interface Storage

All Known Implementing Classes:

AbstractStorage

public interface Storage

Interface to a property store.

Version:

$Revision: 1.7 $, $Date: 2000/11/17 03:04:40 $

Author:

Keith Edwards

Field Summary

static String	FilesystemRepo Standard ID for the local filesystem repository
static String	InternalRepo Standard ID for the implementation internal repository
static String	WebRepo Standard ID for the generic web repository

Method Summary

int	countDocuments(Query q) Find the number of documents that match a query.
Document	createDocument(DocumentType docType) Create a document.
Document	createDocument(DocumentType docType, Schema schema, Map props) Create a document with a particular schema enforced.
boolean	documentExists(String id) Determine whether the named document exists.
DocumentList	find(Query query) Find the documents that match a query.
Document	getDocument(String id) Return the named document.
Object	getExtension(Class ifclass) Get an object implementing an extension interface on this storage.
String	getInfo() Get a description of this storage instance.
String	getName() Get the name of this storage implementation.
QueryFactory	getQueryFactory() Produce a QueryFactory for this storage implementation.
Map	getValueDistribution(String propertyName) Find the distribution of values of the specified property.
Map	getValueDistribution(String propertyName, Query query) Find the distribution of values of the specified property over the set of documents matching the query.
Map	getValueMap(String propertyName) Find the documents with the specified property organized by value of that property.
Map	getValueMap(String propertyName, Query query) Find the documents matching the query organized by value of the specified property as for the simple form of getValueMap().
String	getVersion() Get the version of this storage implementation.
Document	importDocument(DocumentType docType, String repo, Object repoParams) Import an existing document from an external repository.
Document	importDocument(DocumentType docType, String repo, Object repoParams, Schema schema, Map props) Import an existing document from an external repository with a particular schema enforced.
void	shutdown() Cleanly terminate operation of this storage.
void	validateSchema(Schema schema) Validate a schema, verifying that the supplied schema definition is consistent with the current stored data.

Field Detail

InternalRepo

public static final String InternalRepo

Standard ID for the implementation internal repository

FilesystemRepo

public static final String FilesystemRepo

Standard ID for the local filesystem repository

WebRepo

public static final String WebRepo

Standard ID for the generic web repository

Method Detail

validateSchema

public void validateSchema(Schema schema)
                    throws StorageException

Validate a schema, verifying that the supplied schema definition is consistent with the current stored data. An application program written against a particular schema should call this method to verify that the schema definition is known to the Storage implementation and is compatible with any previously known definition of the same schema that is already enforced on documents. Schemas are uniquely identified by name, and when a new definition is presented for a given schema, a Storage implementation may reject it if the old definition is enforced on any existing documents. Alternatively, an implementation may only reject a new definition if it conflicts with the existing enforced definition. When a Schema or FieldDescriptor is rejected an exception will be thrown. This method provides a way for a program to trigger the exception at a reasonable time (such as on startup) rather than waiting until real data manipulations are being performed.

Parameters:

schema - the schema definition to be validated

Throws:

StorageException - if the supplied definition is incompatible with existing enforced definitions

documentExists

public boolean documentExists(String id)
                       throws StorageException

Determine whether the named document exists.

Parameters:

id - document ID to test

Returns:

true iff ID is valid for this storage implementation and identifies a document that presently exists

getDocument

public Document getDocument(String id)
                     throws StorageException

Return the named document.

Returns:

the document named by the id

Throws:

StorageException - if ID is invalid or document does not exist

createDocument

public Document createDocument(DocumentType docType)
                        throws StorageException

Create a document.

Parameters:

docType - the kind of document to create

Returns:

the new document

createDocument

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

Create a document with a particular schema enforced.

Parameters:

docType - the kind of document to create

schema - a schema to be enforced upon creation

props - Map supplying property name,value pairs to satisfy the requirements of the enforced schema, where name is a String.

Returns:

the new document

Throws:

StorageException - if document would not conform to the schema with supplied property values

importDocument

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

Import an existing document from an external repository. This creates a document within the property store that is linked to the repository document. The precise semantics of that link depends upon the type of document and the implementation. For content documents, the repository document will be the holder of the content.

Parameters:

docType - the kind of document to create or null to request that the kind of Bantam document be determined by the implementation based on the nature of the imported repository document.

repo - identifier of the external repository

repoParams - repository-specific object identifying the document to import and any options

Returns:

the new Bantam document

importDocument

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

Import an existing document from an external repository with a particular schema enforced. Since this is an import, the implementation may automatically set properties based on the repository document so it may not be necessary to supply all the schema property values to ensure that the document will conform to the schema.

Parameters:

docType - the kind of document to create or null to request that the kind of Bantam document be determined by the implementation based on the nature of the imported repository document.

repo - identifier of the external repository

repoParams - repository-specific object identifying the document to import and any options

props - Map supplying property name,value pairs to satisfy the requirements of the enforced schema.

Returns:

the new Bantam document

Throws:

StorageException - if document would not conform to the schema.

getQueryFactory

public QueryFactory getQueryFactory()

Produce a QueryFactory for this storage implementation.

Returns:

the query factory object used to construct queries

find

public DocumentList find(Query query)
                  throws StorageException

Find the documents that match a query.

Parameters:

query - a query object produced by the QueryFactory for this storage.

Returns:

list of documents matching the query

countDocuments

public int countDocuments(Query q)
                   throws StorageException

Find the number of documents that match a query. The value returned from this method is the same as the value of size() on the result of find(query) but this method may be a much more efficient way to obtain the number and so should be used whenever the count is all that is required.

Parameters:

query - a query object produced by the QueryFactory for this storage.

Returns:

the number of documents matching the query

getValueDistribution

public Map getValueDistribution(String propertyName)
                         throws StorageException

Find the distribution of values of the specified property. The result is a Map containing one key for each distinct value of the property where the value for a key is the number of documents having that value of the property.

Parameters:

propertyName - the property whose value distribution is requested

Returns:

a Map containing (property value, document count) pairs A NOTE ON SEMANTICS-- properties that have arrays as their values are treated as *multivalued* by this call. What this means is that all of the individual elements of the array are treated as separate values, rather than the array as a whole representing one distinguishable value. These are the semantics that are useful to me for the topical organization stuff...others might be useful to other people.

getValueDistribution

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

Find the distribution of values of the specified property over the set of documents matching the query. The result is the same as for the simple form of getValueDistribution() except that it is constrained to only those documents matching the query. Any document matching the query but not having the property will be counted under the key null.

Parameters:

propertyName - the property whose value distribution is requested

query - a query object produced by the QueryFactory for this storage.

Returns:

a Map containing (property value, document count) pairs

getValueMap

public Map getValueMap(String propertyName)
                throws StorageException

Find the documents with the specified property organized by value of that property. The result is a Map containing one key for each distinct value of the property where the value for a key is a DocumentList containing those documents having that value of the property.

Parameters:

propertyName - the property whose value distribution is requested

Returns:

a Map containing (property value, DocumentList) pairs

getValueMap

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

Find the documents matching the query organized by value of the specified property as for the simple form of getValueMap(). Any document matching the query but without the specified property will be included in the DocumentList for the key null

Parameters:

propertyName - the property whose value distribution is requested

query - a query object produced by the QueryFactory for this storage.

Returns:

a Map containing (property value, DocumentList) pairs

getName

public String getName()

Get the name of this storage implementation.

Returns:

An implementation-dependent name.

getVersion

public String getVersion()

Get the version of this storage implementation.

Returns:

An implementation-dependent version identifier.

getInfo

public String getInfo()

Get a description of this storage instance.

Returns:

An implementation-dependent instance identifier.

getExtension

public Object getExtension(Class ifclass)

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.

Parameters:

ifclass - Java interface

Returns:

object implementing the specified interface on this storage or null

shutdown

public void shutdown()

Cleanly terminate operation of this storage. No client program should terminate the VM without first calling shutdown, as implementations may rely on this call to flush dirty data or perform other bookkeeping. The result of any subsequent calls on this storage or any of its objects is undefined. Some implementations may actually terminate the VM so that this call does not ever return.