## 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(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.