org.exist.collections
Class Collection

java.lang.Object
  extended by java.util.Observable
      extended by org.exist.collections.Collection
All Implemented Interfaces:
Comparable, Cacheable
Direct Known Subclasses:
ClusterCollection

public class Collection
extends Observable
implements Comparable, 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 int POOL_PARSER_THRESHOLD
           
static int 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)
           
 DocumentSet allDocs(DBBroker broker, DocumentSet docs, boolean recursive, boolean checkPermissions, LockedDocumentMap protectedDocs)
          Retrieve all documents contained in this collections.
 DocumentSet allDocs(DBBroker broker, DocumentSet docs, boolean recursive, LockedDocumentMap lockMap, int lockType)
           
 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.
 DocumentImpl getDocumentNoLock(String rawPath)
           
 DocumentSet getDocuments(DBBroker broker, DocumentSet docs, boolean checkPermissions)
          Add all documents to the specified document set.
 DocumentSet getDocuments(DBBroker broker, DocumentSet docs, LockedDocumentMap lockMap, int lockType)
           
 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)
           
 int 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
 Permission getPermissionsNoLock()
           
 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.
 boolean hasSubcollectionNoLock(XmldbURI name)
           
 int incReferenceCount()
          Increase the reference count of this object by one and return it.
 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.
 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(int 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

POOL_PARSER_THRESHOLD

public static final int POOL_PARSER_THRESHOLD
See Also:
Constant Field Values

UNKNOWN_COLLECTION_ID

public static final int 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)

allDocs

public DocumentSet allDocs(DBBroker broker,
                           DocumentSet docs,
                           boolean recursive,
                           boolean checkPermissions,
                           LockedDocumentMap protectedDocs)
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.

allDocs

public DocumentSet allDocs(DBBroker broker,
                           DocumentSet docs,
                           boolean recursive,
                           LockedDocumentMap lockMap,
                           int lockType)
                    throws LockException
Throws:
LockException

getDocuments

public DocumentSet getDocuments(DBBroker broker,
                                DocumentSet docs,
                                boolean checkPermissions)
Add all documents to the specified document set.

Parameters:
docs -

getDocuments

public DocumentSet getDocuments(DBBroker broker,
                                DocumentSet docs,
                                LockedDocumentMap lockMap,
                                int lockType)
                         throws LockException
Throws:
LockException

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

getDocumentNoLock

public DocumentImpl getDocumentNoLock(String rawPath)

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 int 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

getPermissionsNoLock

public Permission getPermissionsNoLock()

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.

hasSubcollectionNoLock

public boolean hasSubcollectionNoLock(XmldbURI name)

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(org.exist.storage.txn.Txn, org.exist.storage.DBBroker, org.exist.xmldb.XmldbURI, CollectionConfiguration, 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(org.exist.storage.txn.Txn, org.exist.storage.DBBroker, org.exist.xmldb.XmldbURI, CollectionConfiguration, 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(org.exist.storage.txn.Txn, org.exist.storage.DBBroker, org.exist.xmldb.XmldbURI, CollectionConfiguration, 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(int 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 -

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


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

isDirty

public boolean isDirty()
Specified by:
isDirty in interface Cacheable

toString

public String toString()
Overrides:
toString in class Object

getIndexConfiguration

public IndexSpec getIndexConfiguration(DBBroker broker)
Deprecated. Make private ASAP

Parameters:
broker -

getIndexByPathConfiguration

public GeneralRangeIndexSpec getIndexByPathConfiguration(DBBroker broker,
                                                         NodePath path)

getIndexByQNameConfiguration

public QNameRangeIndexSpec getIndexByQNameConfiguration(DBBroker broker,
                                                        QName qname)

getFulltextIndexConfiguration

public FulltextIndexSpec getFulltextIndexConfiguration(DBBroker broker)


Copyright (C) Wolfgang Meier. All rights reserved.