com.xerox.bantam
Interface CollectionDocument

All Superinterfaces:

Collection, Document, Set

public interface CollectionDocument

extends Document, Set

An interface for a Document containing other documents. In addition to properties, a CollectionDocument contains by reference an arbitrary number of other documents. The document collection has the semantics of a set: a document is either present or absent but never appears more than once, and no ordering is preserved among the documents in the collection. For convenience, the CollectionDocument interface extends java.util.Set, although invoking any Set method with an object that is not a Document will cause a ClassCastException. The Set functionality should be used carefully and a CollectionDocument should not be passed to any code that expects a generic Set capable of containing any type of object. Bantam applications should typically use the type-specific CollectionDocument methods.

CollectionDocument membership may be specified by query (intensional) or explicit addition and removal of members (extensional) or by a combination of a query and explicit inclusion or exclusion of specific members. Note that query specification implies that the membership of the collection may change without any operation on the CollectionDocument itself.

Version:

$Revision: 1.3 $, $Date: 2000/03/13 19:59:52 $

Author:

Keith Edwards

Method Summary

boolean	add(Object obj) Set method for explicitly adding documents with the same semantics as addDocument.
boolean	addAll(Collection col) Set method for explicitly adding a number of documents with the same net effect as invoking addDocument on each individually.
boolean	addDocument(Document doc) Add the specified document.
boolean	addDocument(String id) Version of addDocument that takes an ID rather than a Document object.
void	clear() Clear collection membership.
void	clearQuery() Clear the query associated with the collection.
boolean	contains(Object obj) Set method for testing for presence of a particular document.
boolean	containsAll(Collection col) Set method for testing for presence of particular documents.
boolean	containsDocument(Document doc) Returns true if the collection contains the specified document.
boolean	containsDocument(String id) Returns true if the collection contains the document specified by its ID.
boolean	equals(Object col) Should return true IFF the target collection is of the same class, shares the same Storage() object, and represents the same entity in the Storage repository.
DocumentList	getDocuments() Return all of the documents contained in the collection.
Query	getQuery() Returns the query associated with the collection.
int	hashCode() Returns an implementation-dependent hash code.
boolean	isEmpty() Returns true if the collection contains no members.
Iterator	iterator() Return a set-style iterator over the collection.
boolean	remove(Object obj) Set method for explicitly removing documents with the same semantics as removeDocument.
boolean	removeAll(Collection col) Set method for explicitly removing documents with the same semantics as removeDocuments.
boolean	removeDocument(Document doc) Remove the specified document.
boolean	removeDocument(String id) Version of removeDocument that takes an ID rather than a Document object.
boolean	removeDocuments(Collection c) Remove all the specified documents.
void	reset() Reverse all explicit addition and removal operations so that the membership is reset to the set of documents matching the query.
boolean	retainAll(Collection col) Set method for explicitly removing documents with the same semantics as removeDocuments.
void	setQuery(Query query) Sets the query associated with the collection.
int	size() Returns the number of elements in the collection.
Object[]	toArray() Returns an array of Document objects.
Object[]	toArray(Object[] a)

Methods inherited from interface com.xerox.bantam.Document

addMultiValue, addMultiValue, clearProperty, clearProperty, conformsTo, containsValue, containsValue, delete, enforceSchema, enforceSchema, flush, get_all_property_names, getDescriptors, getEnforcedSchemas, getID, getMultiValues, getMultiValues, getName, getPropertyNames, getPropertyNames, getPropertyValue, getPropertyValue, getStorage, getUnenforcedPropertyNames, isEnforced, propertyExists, propertyExists, removeValue, removeValue, setMultiValues, setMultiValues, setName, setPropertyValue, setPropertyValue, unenforceSchema

Method Detail

getDocuments

public DocumentList getDocuments()
                          throws StorageException

Return all of the documents contained in the collection.

addDocument

public boolean addDocument(Document doc)
                    throws StorageException

Add the specified document. Returns true if the collection membership changed as a result of the operation. When a document is explicitly added through addDocument it will remain a member of the collection until it is explicitly removed or the collection is reset. Since the document to be added might already match the query, however, the operation might not change the membership and in that case addDocument returns false.

Parameters:

doc - the Document to be explicitly a member of the collection

Returns:

true if the operation changes the set of documents in the collection

addDocument

public boolean addDocument(String id)
                    throws StorageException

Version of addDocument that takes an ID rather than a Document object.

Parameters:

id - the id of the Document to be explicitly a member of the collection.

Returns:

true if the operation changes the set of documents in the collection.

removeDocument

public boolean removeDocument(Document doc)
                       throws StorageException

Remove the specified document. Returns true if the collection membership changed as a result of the operation. When a document is explicitly removed through removeDocument it will not be a member of the collection until it is explicitly added or the collection is reset. Since the document to be removed might already be excluded by the query, however, the operation might not change the immediate membership and in that case removeDocument returns false.

Parameters:

doc - the Document to be explicitly excluded from the collection.

Returns:

true if the operation changes the set of documents in the collection.

removeDocument

public boolean removeDocument(String id)
                       throws StorageException

Version of removeDocument that takes an ID rather than a Document object.

Parameters:

id - the id of the Document to be explicitly excluded from the collection.

Returns:

true if the operation changes the set of documents in the collection.

removeDocuments

public boolean removeDocuments(Collection c)
                        throws StorageException

Remove all the specified documents. This has the same net effect as invoking removeDocument for each individual document.

Parameters:

c - Collection of Document objects for documents to be removed

Returns:

true if the operation changes the set of documents in the collection.

containsDocument

public boolean containsDocument(Document doc)
                         throws StorageException

Returns true if the collection contains the specified document.

containsDocument

public boolean containsDocument(String id)
                         throws StorageException

Returns true if the collection contains the document specified by its ID.

setQuery

public void setQuery(Query query)
              throws StorageException

Sets the query associated with the collection.

getQuery

public Query getQuery()
               throws StorageException

Returns the query associated with the collection.

clearQuery

public void clearQuery()
                throws StorageException

Clear the query associated with the collection. This operation leaves only the membership as explicitly specified.

reset

public void reset()
           throws StorageException

Reverse all explicit addition and removal operations so that the membership is reset to the set of documents matching the query. If no query is set, then this operation empties the collection.

equals

public boolean equals(Object col)

Should return true IFF the target collection is of the same class, shares the same Storage() object, and represents the same entity in the Storage repository.

Specified by:

equals in interface Set

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns an implementation-dependent hash code.

Specified by:

hashCode in interface Set

Overrides:

hashCode in class Object

size

public int size()

Returns the number of elements in the collection.

Specified by:

size in interface Set

add

public boolean add(Object obj)

Set method for explicitly adding documents with the same semantics as addDocument.

Specified by:

add in interface Set

Parameters:

obj - a Document object for the document to be added

Returns:

true if the operation changes the set of documents in the collection

Throws:

ClassCastException - if obj is not an instance of Document

addAll

public boolean addAll(Collection col)

Set method for explicitly adding a number of documents with the same net effect as invoking addDocument on each individually.

Specified by:

addAll in interface Set

Parameters:

col - a collection of Document objects for the documents to be added

Returns:

true if the operation changes the set of documents in the collection

Throws:

ClassCastException - if col contains an object that is not an instance of Document

clear

public void clear()

Clear collection membership. This method has the same effect as the combination of reset() and clearQuery(). After invoking this method the collection will be empty and will remain empty at least until some other operation is performed on the CollectionDocument.

Specified by:

clear in interface Set

remove

public boolean remove(Object obj)

Set method for explicitly removing documents with the same semantics as removeDocument.

Specified by:

remove in interface Set

Parameters:

obj - a Document object for the document to be removed

Returns:

true if the operation changes the set of documents in the collection

Throws:

ClassCastException - if obj is not an instance of Document

removeAll

public boolean removeAll(Collection col)

Set method for explicitly removing documents with the same semantics as removeDocuments.

Specified by:

removeAll in interface Set

Parameters:

col - a collection of Document objects for the documents to be removed

Returns:

true if the operation changes the set of documents in the collection

Throws:

ClassCastException - if col contains an object that is not an instance of Document

retainAll

public boolean retainAll(Collection col)

Set method for explicitly removing documents with the same semantics as removeDocuments. The difference is that the documents to be removed are any not in the specified collection.

Specified by:

retainAll in interface Set

Parameters:

col - a collection of Document objects for the member documents

Returns:

true if the operation changes the set of documents in the collection

Throws:

ClassCastException - if col contains an object that is not an instance of Document

contains

public boolean contains(Object obj)

Set method for testing for presence of a particular document.

Specified by:

contains in interface Set

Parameters:

obj - a Document object for the document to test

Returns:

true if obj is a member of the collection

Throws:

ClassCastException - if obj is not a Document object

containsAll

public boolean containsAll(Collection col)

Set method for testing for presence of particular documents.

Specified by:

containsAll in interface Set

Parameters:

col - a Collection of Document objects for documents to be tested

Returns:

true if all the documents are contained in the collection

Throws:

ClassCastException - if col contains an object that is not an instance of Document

isEmpty

public boolean isEmpty()

Returns true if the collection contains no members.

Specified by:

isEmpty in interface Set

toArray

public Object[] toArray()

Returns an array of Document objects.

Specified by:

toArray in interface Set

toArray

public Object[] toArray(Object[] a)

Specified by:

toArray in interface Set

iterator

public Iterator iterator()

Return a set-style iterator over the collection.

Specified by:

iterator in interface Set