org.exist.collections
Class Collection

java.lang.Object
  java.util.Observable
      org.exist.collections.Collection

All Implemented Interfaces:

Comparable, Cacheable, EntityResolver

Direct Known Subclasses:

ClusterCollection

public class Collection
extends Observable
implements Comparable, EntityResolver, Cacheable

This class represents a collection in the database. A collection maintains a list of sub-collections and documents, and provides the methods to store/remove resources. Collections are shared between DBBroker instances. The caller is responsible to lock/unlock the collection. Call DBBroker.openCollection(XmldbURI, int) to get a collection with a read or write lock and release(int) to release the lock.

Author:

wolf

Field Summary

static int	LENGTH_COLLECTION_ID
static short	UNKNOWN_COLLECTION_ID

Fields inherited from interface org.exist.storage.cache.Cacheable

MAX_REF

Constructor Summary

Collection()

Collection(XmldbURI path)

Method Summary

BinaryDocument	addBinaryResource(Txn transaction, DBBroker broker, XmldbURI docUri, byte[] data, String mimeType)
BinaryDocument	addBinaryResource(Txn transaction, DBBroker broker, XmldbURI docUri, byte[] data, String mimeType, Date created, Date modified)
BinaryDocument	addBinaryResource(Txn transaction, DBBroker broker, XmldbURI docUri, InputStream is, String mimeType, int size)
BinaryDocument	addBinaryResource(Txn transaction, DBBroker broker, XmldbURI docUri, InputStream is, String mimeType, int size, Date created, Date modified)
void	addCollection(DBBroker broker, Collection child, boolean isNew) Add a new sub-collection to the collection.
void	addDocument(Txn transaction, DBBroker broker, DocumentImpl doc) Add a document to the collection.
void	addObserver(Observer o)
DocumentSet	allDocs(DBBroker broker, DocumentSet docs, boolean recursive, boolean checkPermissions) Retrieve all documents contained in this collections.
boolean	allowUnload() Check if this collection may be safely removed from the cache.
Iterator	collectionIterator() Return an iterator over all subcollections.
int	compareTo(Object obj)
int	decReferenceCount() Decrease the reference count of this object by one and return it.
void	deleteObservers()
boolean	equals(Object obj)
long	getAddress()
int	getChildCollectionCount() Return the number of child-collections managed by this collection.
CollectionConfiguration	getConfiguration(DBBroker broker)
long	getCreationTime()
List	getDescendants(DBBroker broker, User user) Load all collections below this collections and return them in a List.
DocumentImpl	getDocument(DBBroker broker, XmldbURI path) Get a child resource as identified by path.
int	getDocumentCount() Returns the number of documents in this collection.
DocumentSet	getDocuments(DBBroker broker, DocumentSet docs, boolean checkPermissions) Add all documents to the specified document set.
DocumentImpl	getDocumentWithLock(DBBroker broker, XmldbURI name) Deprecated. Use other method
DocumentImpl	getDocumentWithLock(DBBroker broker, XmldbURI uri, int lockMode) Retrieve a child resource after putting a read lock on it.
FulltextIndexSpec	getFulltextIndexConfiguration(DBBroker broker)
short	getId() Get the internal id.
GeneralRangeIndexSpec	getIndexByPathConfiguration(DBBroker broker, NodePath path)
QNameRangeIndexSpec	getIndexByQNameConfiguration(DBBroker broker, QName qname)
IndexSpec	getIndexConfiguration(DBBroker broker) Deprecated. Make private ASAP
long	getKey() Get a unique key for the object.
Lock	getLock()
int	getMemorySize() Returns the estimated amount of memory used by this collection and its documents.
XmldbURI	getParentURI() Returns the parent-collection.
Permission	getPermissions() Gets the permissions attribute of the Collection object
int	getReferenceCount() Get the current reference count.
int	getTimestamp() Get the current timestamp marker.
XmldbURI	getURI() Get the name of this collection.
boolean	hasChildCollection(XmldbURI path)
boolean	hasDocument(XmldbURI uri) Check if the collection has a child document.
boolean	hasSubcollection(XmldbURI name) Check if the collection has a sub-collection.
int	incReferenceCount() Increase the reference count of this object by one and return it.
void	invalidateConfiguration()
boolean	isDirty()
boolean	isTempCollection() Returns true if this is a temporary collection.
Iterator	iterator(DBBroker broker) Returns an iterator on the child-documents in this collection.
void	read(DBBroker broker, VariableByteInput istream) Read collection contents from the stream.
void	release(int mode) Closes the collection, i.e.
void	releaseDocument(DocumentImpl doc) Deprecated. Use other method
void	releaseDocument(DocumentImpl doc, int mode) Release any locks held on the document.
void	removeBinaryResource(Txn transaction, DBBroker broker, DocumentImpl doc)
void	removeBinaryResource(Txn transaction, DBBroker broker, XmldbURI uri)
void	removeCollection(XmldbURI name) Remove the specified sub-collection.
void	removeXMLResource(Txn transaction, DBBroker broker, XmldbURI docUri) Remove the specified document from the collection.
InputSource	resolveEntity(String publicId, String systemId) Try to resolve external entities.
void	setAddress(long addr) Set the internal storage address of the collection data.
void	setConfigEnabled(boolean enabled) Should the collection configuration document be enabled for this collection? Called by NativeBroker before doing a reindex.
void	setCreationTime(long ms)
void	setId(short id)
void	setPath(XmldbURI path)
void	setPermissions(int mode)
void	setPermissions(Permission permissions) Set permissions for the collection.
void	setPermissions(String mode)
void	setReader(XMLReader reader) set user-defined Reader
void	setReferenceCount(int count) Set the reference count of this object.
void	setTimestamp(int timestamp) Set the timestamp marker.
void	setTriggersEnabled(boolean enabled)
void	store(Txn transaction, DBBroker broker, IndexInfo info, InputSource source, boolean privileged) Stores an XML document in the database.
void	store(Txn transaction, DBBroker broker, IndexInfo info, Node node, boolean privileged) Stores an XML document in the database.
void	store(Txn transaction, DBBroker broker, IndexInfo info, String data, boolean privileged) Stores an XML document in the database.
boolean	sync(boolean syncJournal) Called before the object is released by the cache.
String	toString()
void	unlinkDocument(DocumentImpl doc) Removes the document from the internal list of resources, but doesn't delete the document object itself.
void	update(Collection child) Update the specified child-collection.
IndexInfo	validateXMLResource(Txn transaction, DBBroker broker, XmldbURI docUri, InputSource source) Validates an XML document et prepares it for further storage.
IndexInfo	validateXMLResource(Txn transaction, DBBroker broker, XmldbURI docUri, Node node) Validates an XML document et prepares it for further storage.
IndexInfo	validateXMLResource(Txn transaction, DBBroker broker, XmldbURI docUri, String data) Validates an XML document et prepares it for further storage.
void	write(DBBroker broker, VariableByteOutputStream ostream) Write collection contents to stream.

Methods inherited from class java.util.Observable

countObservers, deleteObserver, hasChanged, notifyObservers, notifyObservers

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

LENGTH_COLLECTION_ID

public static int LENGTH_COLLECTION_ID

UNKNOWN_COLLECTION_ID

public static final short UNKNOWN_COLLECTION_ID

See Also:

Constant Field Values

Constructor Detail

Collection

public Collection()

Collection

public Collection(XmldbURI path)

Method Detail

setPath

public void setPath(XmldbURI path)

getLock

public Lock getLock()

addCollection

public void addCollection(DBBroker broker,
                          Collection child,
                          boolean isNew)

Add a new sub-collection to the collection.

hasChildCollection

public boolean hasChildCollection(XmldbURI path)

isTempCollection

public boolean isTempCollection()

Returns true if this is a temporary collection. By default, the temporary collection is in /db/system/temp.

Returns:

A boolean where true means the collection is temporary.

release

public void release(int mode)

Closes the collection, i.e. releases the lock held by the current thread. This is a shortcut for getLock().release().

update

public void update(Collection child)

Update the specified child-collection.

Parameters:

child -

addDocument

public void addDocument(Txn transaction,
                        DBBroker broker,
                        DocumentImpl doc)

Add a document to the collection.

Parameters:

doc -

unlinkDocument

public void unlinkDocument(DocumentImpl doc)

Removes the document from the internal list of resources, but doesn't delete the document object itself.

Parameters:

doc -

collectionIterator

public Iterator collectionIterator()

Return an iterator over all subcollections. The list of subcollections is copied first, so modifications via the iterator have no affect.

Returns:

Description of the Return Value

getDescendants

public List getDescendants(DBBroker broker,
                           User user)

Load all collections below this collections and return them in a List.

Returns:

List

allDocs

public DocumentSet allDocs(DBBroker broker,
                           DocumentSet docs,
                           boolean recursive,
                           boolean checkPermissions)

Retrieve all documents contained in this collections. If recursive is true, documents from sub-collections are included.

Parameters:

broker -

docs -

recursive -

checkPermissions -

Returns:

The set of documents.

getDocuments

public DocumentSet getDocuments(DBBroker broker,
                                DocumentSet docs,
                                boolean checkPermissions)

Add all documents to the specified document set.

Parameters:

docs -

allowUnload

public boolean allowUnload()

Check if this collection may be safely removed from the cache. Returns false if there are ongoing write operations, i.e. one or more of the documents is locked for write.

Specified by:

allowUnload in interface Cacheable

Returns:

A boolean value where true indicates it may be unloaded.

compareTo

public int compareTo(Object obj)

Specified by:

compareTo in interface Comparable

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

getMemorySize

public int getMemorySize()

Returns the estimated amount of memory used by this collection and its documents. This information is required by the CollectionCacheManager to be able to resize the caches.

Returns:

estimated amount of memory in bytes

getChildCollectionCount

public int getChildCollectionCount()

Return the number of child-collections managed by this collection.

Returns:

The childCollectionCount value

getDocument

public DocumentImpl getDocument(DBBroker broker,
                                XmldbURI path)

Get a child resource as identified by path. This method doesn't put a lock on the document nor does it recognize locks held by other threads. There's no guarantee that the document still exists when accessing it.

Parameters:

broker -

path - The name of the document (without collection path)

Returns:

the document

getDocumentWithLock

public DocumentImpl getDocumentWithLock(DBBroker broker,
                                        XmldbURI name)
                                 throws LockException

Deprecated. Use other method

Retrieve a child resource after putting a read lock on it. With this method, access to the received document object is safe.

Parameters:

broker -

name -

Returns:

The document that was locked.

Throws:

LockException

getDocumentWithLock

public DocumentImpl getDocumentWithLock(DBBroker broker,
                                        XmldbURI uri,
                                        int lockMode)
                                 throws LockException

Retrieve a child resource after putting a read lock on it. With this method, access to the received document object is safe.

Parameters:

broker -

uri -

lockMode -

Returns:

The document that was locked.

Throws:

LockException

releaseDocument

public void releaseDocument(DocumentImpl doc)

Deprecated. Use other method

Release any locks held on the document.

Parameters:

doc -

releaseDocument

public void releaseDocument(DocumentImpl doc,
                            int mode)

Release any locks held on the document.

Parameters:

doc -

getDocumentCount

public int getDocumentCount()

Returns the number of documents in this collection.

Returns:

The documentCount value

getId

public short getId()

Get the internal id.

Returns:

The id value

getURI

public XmldbURI getURI()

Get the name of this collection.

Returns:

The name value

getParentURI

public XmldbURI getParentURI()

Returns the parent-collection.

Returns:

The parent-collection or null if this is the root collection.

getPermissions

public Permission getPermissions()

Gets the permissions attribute of the Collection object

Returns:

The permissions value

hasDocument

public boolean hasDocument(XmldbURI uri)

Check if the collection has a child document.

Parameters:

uri - the name (without path) of the document

Returns:

A value of true when the collection has the document identified.

hasSubcollection

public boolean hasSubcollection(XmldbURI name)

Check if the collection has a sub-collection.

Parameters:

name - the name of the subcollection (without path).

Returns:

A value of true when the subcollection exists.

iterator

public Iterator iterator(DBBroker broker)

Returns an iterator on the child-documents in this collection.

Returns:

A iterator of all the documents in the collection.

read

public void read(DBBroker broker,
                 VariableByteInput istream)
          throws IOException

Read collection contents from the stream.

Parameters:

istream -

Throws:

IOException

removeCollection

public void removeCollection(XmldbURI name)
                      throws LockException

Remove the specified sub-collection.

Parameters:

name - Description of the Parameter

Throws:

LockException

removeXMLResource

public void removeXMLResource(Txn transaction,
                              DBBroker broker,
                              XmldbURI docUri)
                       throws PermissionDeniedException,
                              TriggerException,
                              LockException

Remove the specified document from the collection.

Parameters:

transaction -

broker -

docUri -

Throws:

PermissionDeniedException

TriggerException

LockException

removeBinaryResource

public void removeBinaryResource(Txn transaction,
                                 DBBroker broker,
                                 XmldbURI uri)
                          throws PermissionDeniedException,
                                 LockException,
                                 TriggerException

Throws:

PermissionDeniedException

LockException

TriggerException

removeBinaryResource

public void removeBinaryResource(Txn transaction,
                                 DBBroker broker,
                                 DocumentImpl doc)
                          throws PermissionDeniedException,
                                 LockException,
                                 TriggerException

Throws:

PermissionDeniedException

LockException

TriggerException

store

public void store(Txn transaction,
                  DBBroker broker,
                  IndexInfo info,
                  InputSource source,
                  boolean privileged)
           throws EXistException,
                  PermissionDeniedException,
                  TriggerException,
                  SAXException,
                  LockException

Stores an XML document in the database. validateXMLResourceInternal(Txn, DBBroker, XmldbURI, org.exist.collections.Collection.ValidateBlock) should have been called previously in order to acquire a write lock for the document. Launches the finish trigger.

Parameters:

transaction -

broker -

info -

source -

privileged -

Throws:

EXistException

PermissionDeniedException

TriggerException

SAXException

LockException

store

public void store(Txn transaction,
                  DBBroker broker,
                  IndexInfo info,
                  String data,
                  boolean privileged)
           throws EXistException,
                  PermissionDeniedException,
                  TriggerException,
                  SAXException,
                  LockException

Stores an XML document in the database. validateXMLResourceInternal(Txn, DBBroker, XmldbURI, org.exist.collections.Collection.ValidateBlock) should have been called previously in order to acquire a write lock for the document. Launches the finish trigger.

Parameters:

transaction -

broker -

info -

data -

privileged -

Throws:

EXistException

PermissionDeniedException

TriggerException

SAXException

LockException

store

public void store(Txn transaction,
                  DBBroker broker,
                  IndexInfo info,
                  Node node,
                  boolean privileged)
           throws EXistException,
                  PermissionDeniedException,
                  TriggerException,
                  SAXException,
                  LockException

Stores an XML document in the database. validateXMLResourceInternal(Txn, DBBroker, XmldbURI, org.exist.collections.Collection.ValidateBlock) should have been called previously in order to acquire a write lock for the document. Launches the finish trigger.

Parameters:

transaction -

broker -

info -

node -

privileged -

Throws:

EXistException

PermissionDeniedException

TriggerException

SAXException

LockException

validateXMLResource

public IndexInfo validateXMLResource(Txn transaction,
                                     DBBroker broker,
                                     XmldbURI docUri,
                                     String data)
                              throws EXistException,
                                     PermissionDeniedException,
                                     TriggerException,
                                     SAXException,
                                     LockException,
                                     IOException

Validates an XML document et prepares it for further storage. Launches prepare and postValidate triggers. Since the process is dependant from the collection configuration, the collection acquires a write lock during the process.

Parameters:

transaction -

broker -

docUri -

data -

Returns:

An IndexInfo with a write lock on the document.

Throws:

EXistException

PermissionDeniedException

TriggerException

SAXException

LockException

IOException

validateXMLResource

public IndexInfo validateXMLResource(Txn transaction,
                                     DBBroker broker,
                                     XmldbURI docUri,
                                     InputSource source)
                              throws EXistException,
                                     PermissionDeniedException,
                                     TriggerException,
                                     SAXException,
                                     LockException,
                                     IOException

Validates an XML document et prepares it for further storage. Launches prepare and postValidate triggers. Since the process is dependant from the collection configuration, the collection acquires a write lock during the process.

Parameters:

transaction -

broker -

docUri -

source -

Returns:

An IndexInfo with a write lock on the document.

Throws:

EXistException

PermissionDeniedException

TriggerException

SAXException

LockException

IOException

validateXMLResource

public IndexInfo validateXMLResource(Txn transaction,
                                     DBBroker broker,
                                     XmldbURI docUri,
                                     Node node)
                              throws EXistException,
                                     PermissionDeniedException,
                                     TriggerException,
                                     SAXException,
                                     LockException,
                                     IOException

Validates an XML document et prepares it for further storage. Launches prepare and postValidate triggers. Since the process is dependant from the collection configuration, the collection acquires a write lock during the process.

Parameters:

transaction -

broker -

docUri -

node -

Returns:

An IndexInfo with a write lock on the document.

Throws:

EXistException

PermissionDeniedException

TriggerException

SAXException

LockException

IOException

addBinaryResource

public BinaryDocument addBinaryResource(Txn transaction,
                                        DBBroker broker,
                                        XmldbURI docUri,
                                        byte[] data,
                                        String mimeType)
                                 throws EXistException,
                                        PermissionDeniedException,
                                        LockException,
                                        TriggerException

Throws:

EXistException

PermissionDeniedException

LockException

TriggerException

addBinaryResource

public BinaryDocument addBinaryResource(Txn transaction,
                                        DBBroker broker,
                                        XmldbURI docUri,
                                        byte[] data,
                                        String mimeType,
                                        Date created,
                                        Date modified)
                                 throws EXistException,
                                        PermissionDeniedException,
                                        LockException,
                                        TriggerException

Throws:

EXistException

PermissionDeniedException

LockException

TriggerException

addBinaryResource

public BinaryDocument addBinaryResource(Txn transaction,
                                        DBBroker broker,
                                        XmldbURI docUri,
                                        InputStream is,
                                        String mimeType,
                                        int size)
                                 throws EXistException,
                                        PermissionDeniedException,
                                        LockException,
                                        TriggerException

Throws:

EXistException

PermissionDeniedException

LockException

TriggerException

addBinaryResource

public BinaryDocument addBinaryResource(Txn transaction,
                                        DBBroker broker,
                                        XmldbURI docUri,
                                        InputStream is,
                                        String mimeType,
                                        int size,
                                        Date created,
                                        Date modified)
                                 throws EXistException,
                                        PermissionDeniedException,
                                        LockException,
                                        TriggerException

Throws:

EXistException

PermissionDeniedException

LockException

TriggerException

setId

public void setId(short id)

setPermissions

public void setPermissions(int mode)
                    throws LockException

Throws:

LockException

setPermissions

public void setPermissions(String mode)
                    throws SyntaxException,
                           LockException

Throws:

SyntaxException

LockException

setPermissions

public void setPermissions(Permission permissions)
                    throws LockException

Set permissions for the collection.

Parameters:

permissions -

Throws:

LockException

write

public void write(DBBroker broker,
                  VariableByteOutputStream ostream)
           throws IOException

Write collection contents to stream.

Parameters:

ostream -

Throws:

IOException

getConfiguration

public CollectionConfiguration getConfiguration(DBBroker broker)

setConfigEnabled

public void setConfigEnabled(boolean enabled)

Should the collection configuration document be enabled for this collection? Called by NativeBroker before doing a reindex.

Parameters:

enabled -

invalidateConfiguration

public void invalidateConfiguration()

setAddress

public void setAddress(long addr)

Set the internal storage address of the collection data.

Parameters:

addr -

getAddress

public long getAddress()

setCreationTime

public void setCreationTime(long ms)

getCreationTime

public long getCreationTime()

setTriggersEnabled

public void setTriggersEnabled(boolean enabled)

setReader

public void setReader(XMLReader reader)

set user-defined Reader

resolveEntity

public InputSource resolveEntity(String publicId,
                                 String systemId)
                          throws SAXException,
                                 IOException

Try to resolve external entities. This method forwards the request to the resolver. If that fails, the method replaces absolute file names with relative ones and retries to resolve. This makes it possible to use relative file names in the catalog.

Specified by:

resolveEntity in interface EntityResolver

Throws:

SAXException

IOException

See Also:

EntityResolver.resolveEntity(java.lang.String, java.lang.String)

addObserver

public void addObserver(Observer o)

Overrides:

addObserver in class Observable

deleteObservers

public void deleteObservers()

Overrides:

deleteObservers in class Observable

getKey

public long getKey()

Description copied from interface: Cacheable

Get a unique key for the object. Usually this is the page number.

Specified by:

getKey in interface Cacheable

Returns:

unique key

getReferenceCount

public int getReferenceCount()

Description copied from interface: Cacheable

Get the current reference count.

Specified by:

getReferenceCount in interface Cacheable

Returns:

The count value.

incReferenceCount

public int incReferenceCount()

Description copied from interface: Cacheable

Increase the reference count of this object by one and return it.

Specified by:

incReferenceCount in interface Cacheable

Returns:

the reference count

decReferenceCount

public int decReferenceCount()

Description copied from interface: Cacheable

Decrease the reference count of this object by one and return it.

Specified by:

decReferenceCount in interface Cacheable

Returns:

the reference count

setReferenceCount

public void setReferenceCount(int count)

Description copied from interface: Cacheable

Set the reference count of this object.

Specified by:

setReferenceCount in interface Cacheable

setTimestamp

public void setTimestamp(int timestamp)

Description copied from interface: Cacheable

Set the timestamp marker.

Specified by:

setTimestamp in interface Cacheable

getTimestamp

public int getTimestamp()

Description copied from interface: Cacheable

Get the current timestamp marker.

Specified by:

getTimestamp in interface Cacheable

Returns:

timestamp marker

sync

public boolean sync(boolean syncJournal)

Description copied from interface: Cacheable

Called before the object is released by the cache. The object should prepare to be garbage collected. All unwritten data should be flushed to disk.

Specified by:

sync in in