org.exist.collections
Class Collection

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

All Implemented Interfaces:

Cacheable, java.lang.Comparable, org.xml.sax.EntityResolver

Direct Known Subclasses:

ClusterCollection

public class Collection

extends java.util.Observable

implements java.lang.Comparable, org.xml.sax.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(String, int) to get a collection with a read or write lock and release() to release the lock.

Author:

wolf

Field Summary

static short

UNKNOWN_COLLECTION_ID

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

MAX_REF

Constructor Summary

Collection()

Collection(java.lang.String name)

Method Summary

BinaryDocument	addBinaryResource(Txn transaction, DBBroker broker, java.lang.String name, byte[] data, java.lang.String mimeType)
BinaryDocument	addBinaryResource(Txn transaction, DBBroker broker, java.lang.String name, byte[] data, java.lang.String mimeType, java.util.Date created, java.util.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(java.util.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.
java.util.Iterator	collectionIterator() Return an iterator over all subcollections.
int	compareTo(java.lang.Object obj)
int	decReferenceCount() Decrease the reference count of this object by one and return it.
void	deleteObservers()
boolean	equals(java.lang.Object obj)
long	getAddress()
int	getChildCollectionCount() Return the number of child-collections managed by this collection.
CollectionConfiguration	getConfiguration(DBBroker broker)
long	getCreationTime()
java.util.List	getDescendants(DBBroker broker, User user) Load all collections below this collections and return them in a List.
DocumentImpl	getDocument(DBBroker broker, java.lang.String name) 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, java.lang.String name) Retrieve a child resource after putting a read lock on it.
DocumentImpl	getDocumentWithLock(DBBroker broker, java.lang.String name, int lockMode) Retrieve a child resource after putting a read lock on it.
short	getId() Get the internal id.
IndexSpec	getIdxConf(DBBroker broker)
long	getKey() Get a unique key for the object.
Lock	getLock()
Lock	getLockOld()
java.lang.String	getName() Get the name of this collection.
java.lang.String	getParentPath() 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.
boolean	hasChildCollection(java.lang.String name)
boolean	hasDocument(java.lang.String name) Check if the collection has a child document.
boolean	hasSubcollection(java.lang.String 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.
java.util.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() Closes the collection, i.e.
void	releaseDocument(DocumentImpl doc) Release any locks held on the document.
void	removeBinaryResource(Txn transaction, DBBroker broker, DocumentImpl doc)
void	removeBinaryResource(Txn transaction, DBBroker broker, java.lang.String docName)
void	removeCollection(java.lang.String name) Remove the specified sub-collection.
void	removeXMLResource(Txn transaction, DBBroker broker, java.lang.String docname) Remove the specified document from the collection.
org.xml.sax.InputSource	resolveEntity(java.lang.String publicId, java.lang.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	setName(java.lang.String name)
void	setPermissions(int mode)
void	setPermissions(Permission permissions) Set permissions for the collection.
void	setPermissions(java.lang.String mode)
void	setReader(org.xml.sax.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, org.xml.sax.InputSource source, boolean privileged)
void	store(Txn transaction, DBBroker broker, IndexInfo info, org.w3c.dom.Node node, boolean privileged)
void	store(Txn transaction, DBBroker broker, IndexInfo info, java.lang.String data, boolean privileged)
boolean	sync(boolean syncJournal) Called before the object is released by the cache.
java.lang.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, java.lang.String docName, org.xml.sax.InputSource source)
IndexInfo	validateXMLResource(Txn transaction, DBBroker broker, java.lang.String docName, org.w3c.dom.Node node)
IndexInfo	validateXMLResource(Txn transaction, DBBroker broker, java.lang.String docName, java.lang.String data)
void	write(DBBroker broker, VariableByteOutputStream ostream) Write collection contents to stream.

Methods inherited from class java.util.Observable

clearChanged, countObservers, deleteObserver, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

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

Field Detail

UNKNOWN_COLLECTION_ID

public static final short UNKNOWN_COLLECTION_ID

See Also:

Constant Field Values

Constructor Detail

Collection

public Collection()

Collection

public Collection(java.lang.String name)

Method Detail

setName

public void setName(java.lang.String name)

getLockOld

public Lock getLockOld()

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(java.lang.String name)

isTempCollection

public boolean isTempCollection()

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

Returns:

release

public void release()

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 java.util.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 java.util.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:

recursive -

Returns:

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:

compareTo

public int compareTo(java.lang.Object obj)

Specified by:

compareTo in interface java.lang.Comparable

equals

public boolean equals(java.lang.Object obj)

getChildCollectionCount

public int getChildCollectionCount()

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

Returns:

The childCollectionCount value

getDocument

public DocumentImpl getDocument(DBBroker broker,
                                java.lang.String name)

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:

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

Returns:

the document

getDocumentWithLock

public DocumentImpl getDocumentWithLock(DBBroker broker,
                                        java.lang.String name)
                                 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 -

name -

Returns:

Throws:

LockException

getDocumentWithLock

public DocumentImpl getDocumentWithLock(DBBroker broker,
                                        java.lang.String name,
                                        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 -

name -

Returns:

Throws:

LockException

releaseDocument

public void releaseDocument(DocumentImpl doc)

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

getName

public java.lang.String getName()

Get the name of this collection.

Returns:

The name value

getParentPath

public java.lang.String getParentPath()

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(java.lang.String name)

Check if the collection has a child document.

Parameters:

name - the name (without path) of the document

Returns:

hasSubcollection

public boolean hasSubcollection(java.lang.String name)

Check if the collection has a sub-collection.

Parameters:

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

Returns:

iterator

public java.util.Iterator iterator(DBBroker broker)

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

Returns:

read

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

Read collection contents from the stream.

Parameters:

istream -

Throws:

java.io.IOException

removeCollection

public void removeCollection(java.lang.String name)
                      throws LockException

Remove the specified sub-collection.

Parameters:

name - Description of the Parameter

Throws:

LockException

removeXMLResource

public void removeXMLResource(Txn transaction,
                              DBBroker broker,
                              java.lang.String docname)
                       throws PermissionDeniedException,
                              TriggerException,
                              LockException

Remove the specified document from the collection.

Throws:

PermissionDeniedException

TriggerException

LockException

removeBinaryResource

public void removeBinaryResource(Txn transaction,
                                 DBBroker broker,
                                 java.lang.String docName)
                          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,
                  org.xml.sax.InputSource source,
                  boolean privileged)
           throws EXistException,
                  PermissionDeniedException,
                  TriggerException,
                  org.xml.sax.SAXException,
                  LockException

Throws:

EXistException

PermissionDeniedException

TriggerException

org.xml.sax.SAXException

LockException

store

public void store(Txn transaction,
                  DBBroker broker,
                  IndexInfo info,
                  java.lang.String data,
                  boolean privileged)
           throws EXistException,
                  PermissionDeniedException,
                  TriggerException,
                  org.xml.sax.SAXException,
                  LockException

Throws:

EXistException

PermissionDeniedException

TriggerException

org.xml.sax.SAXException

LockException

store

public void store(Txn transaction,
                  DBBroker broker,
                  IndexInfo info,
                  org.w3c.dom.Node node,
                  boolean privileged)
           throws EXistException,
                  PermissionDeniedException,
                  TriggerException,
                  org.xml.sax.SAXException,
                  LockException

Throws:

EXistException

PermissionDeniedException

TriggerException

org.xml.sax.SAXException

LockException

validateXMLResource

public IndexInfo validateXMLResource(Txn transaction,
                                     DBBroker broker,
                                     java.lang.String docName,
                                     java.lang.String data)
                              throws EXistException,
                                     PermissionDeniedException,
                                     TriggerException,
                                     org.xml.sax.SAXException,
                                     LockException

Throws:

EXistException

PermissionDeniedException

TriggerException

org.xml.sax.SAXException

LockException

validateXMLResource

public IndexInfo validateXMLResource(Txn transaction,
                                     DBBroker broker,
                                     java.lang.String docName,
                                     org.xml.sax.InputSource source)
                              throws EXistException,
                                     PermissionDeniedException,
                                     TriggerException,
                                     org.xml.sax.SAXException,
                                     LockException

Throws:

EXistException

PermissionDeniedException

TriggerException

org.xml.sax.SAXException

LockException

validateXMLResource

public IndexInfo validateXMLResource(Txn transaction,
                                     DBBroker broker,
                                     java.lang.String docName,
                                     org.w3c.dom.Node node)
                              throws EXistException,
                                     PermissionDeniedException,
                                     TriggerException,
                                     org.xml.sax.SAXException,
                                     LockException

Throws:

EXistException

PermissionDeniedException

TriggerException

org.xml.sax.SAXException

LockException

addBinaryResource

public BinaryDocument addBinaryResource(Txn transaction,
                                        DBBroker broker,
                                        java.lang.String name,
                                        byte[] data,
                                        java.lang.String mimeType)
                                 throws EXistException,
                                        PermissionDeniedException,
                                        LockException,
                                        TriggerException

Throws:

EXistException

PermissionDeniedException

LockException

TriggerException

addBinaryResource

public BinaryDocument addBinaryResource(Txn transaction,
                                        DBBroker broker,
                                        java.lang.String name,
                                        byte[] data,
                                        java.lang.String mimeType,
                                        java.util.Date created,
                                        java.util.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(java.lang.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 java.io.IOException

Write collection contents to stream.

Parameters:

ostream -

Throws:

java.io.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(org.xml.sax.XMLReader reader)

set user-defined Reader

resolveEntity

public org.xml.sax.InputSource resolveEntity(java.lang.String publicId,
                                             java.lang.String systemId)
                                      throws org.xml.sax.SAXException,
                                             java.io.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 org.xml.sax.EntityResolver

Throws:

org.xml.sax.SAXException

java.io.IOException

See Also:

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

addObserver

public void addObserver(java.util.Observer o)

deleteObservers

public void deleteObservers()

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:

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

Parameters:

count -

setTimestamp

public void setTimestamp(int timestamp)

Description copied from interface: Cacheable

Set the timestamp marker.

Specified by:

setTimestamp in interface Cacheable

Parameters:

timestamp -

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 interface Cacheable

isDirty

public boolean isDirty()

Specified by:

isDirty in interface Cacheable

toString

public java.lang.String toString()

getIdxConf

public IndexSpec getIdxConf(DBBroker broker)