org.exist.collections
Class Collection

java.lang.Object
  extended byjava.util.Observable
      extended byorg.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(XmldbURI, 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(XmldbURI path)
           
 
Method Summary
 BinaryDocument addBinaryResource(Txn transaction, DBBroker broker, XmldbURI docUri, byte[] data, java.lang.String mimeType)
           
 BinaryDocument addBinaryResource(Txn transaction, DBBroker broker, XmldbURI docUri, byte[] data, java.lang.String mimeType, java.util.Date created, java.util.Date modified)
           
 BinaryDocument addBinaryResource(Txn transaction, DBBroker broker, XmldbURI docUri, java.io.InputStream is, java.lang.String mimeType, int size)
           
 BinaryDocument addBinaryResource(Txn transaction, DBBroker broker, XmldbURI docUri, java.io.InputStream is, java.lang.String mimeType, int size, 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, 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)
          Retrieve a child resource after putting a read lock on it.
 DocumentImpl getDocumentWithLock(DBBroker broker, XmldbURI uri, 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()
           
 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.
 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, 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.
 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 setPath(XmldbURI path)
           
 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, XmldbURI docUri, org.xml.sax.InputSource source)
           
 IndexInfo validateXMLResource(Txn transaction, DBBroker broker, XmldbURI docUri, org.w3c.dom.Node node)
           
 IndexInfo validateXMLResource(Txn transaction, DBBroker broker, XmldbURI docUri, java.lang.String data)
           
 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

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)

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(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()
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:
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(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,
                                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
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)
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 java.util.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 java.io.IOException
Read collection contents from the stream.

Parameters:
istream -
Throws:
java.io.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,
                  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,
                                     XmldbURI docUri,
                                     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,
                                     XmldbURI docUri,
                                     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,
                                     XmldbURI docUri,
                                     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,
                                        XmldbURI docUri,
                                        byte[] data,
                                        java.lang.String mimeType)
                                 throws EXistException,
                                        PermissionDeniedException,
                                        LockException,
                                        TriggerException
Throws:
EXistException
PermissionDeniedException
LockException
TriggerException

addBinaryResource

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

addBinaryResource

public BinaryDocument addBinaryResource(Txn transaction,
                                        DBBroker broker,
                                        XmldbURI docUri,
                                        java.io.InputStream is,
                                        java.lang.String mimeType,
                                        int size)
                                 throws EXistException,
                                        PermissionDeniedException,
                                        LockException,
                                        TriggerException
Throws:
EXistException
PermissionDeniedException
LockException
TriggerException

addBinaryResource

public BinaryDocument addBinaryResource(Txn transaction,
                                        DBBroker broker,
                                        XmldbURI docUri,
                                        java.io.InputStream is,
                                        java.lang.String mimeType,
                                        int size,
                                        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:
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
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)


Copyright (C) Wolfgang Meier. All rights reserved.