org.xquark.xml.xdbc
Interface XMLCollection

All Superinterfaces:

Configurable

public interface XMLCollection

extends Configurable

This interface describes a XML collection of XML documents.

Note:

This object is likely to use resources that can be released using the close() method.

Method Summary

void	close() Closes this XMLCollection.
boolean	containsDocument(java.lang.String documentID) Checks if a named XML document exists in this XML collection.
XMLConnection	getConnection() Retrieves the XMLConnection object that produced this XMLCollection.
java.lang.String	getDescription() Retrieves the description of the XML collection.
XMLDocument	getDocument(java.lang.String documentID) Retrieves an XML document in the XML collection.
long	getDocumentCount() Retrieves the XML collection size (number of documents).
XMLDocumentFiler	getDocumentFiler() Creates a "filer" object that can be used to insert a new XML document into the XML collection.
java.util.List	getIdentifierList() Returns a list of documents identifiers available in the XML collection.
java.lang.String	getName() Retrieves the unique name of the XML collection.
boolean	isReadOnly() Returns true if the XML collection is read-only mode.
int	removeAllDocuments() Removes all XML documents from the XML collection.
boolean	removeDocument(java.lang.String documentID) Removes the named XML document from the XML collection.
boolean	renameDocument(java.lang.String oldID, java.lang.String newID) Renames a document.
void	setDescription(java.lang.String description) Sets the description of the XML collection.
void	setReadOnly(boolean readOnly) Changes the read-only mode for this XML collection.

Methods inherited from interface org.xquark.xml.xdbc.Configurable

getFeature, getFeatureList, getProperty, getPropertyList, setFeature, setProperty

Method Detail

close

public void close()
           throws XMLDBCException

Closes this XMLCollection. Once a collection is closed, it should not be accessed any more.

Throws:

XMLDBCException - if a data source access error occurs.

getName

public java.lang.String getName()
                         throws XMLDBCException

Retrieves the unique name of the XML collection.

Returns:

the unique name of the XML collection.

Throws:

XMLDBCException - if a data source access error occurs.

getDescription

public java.lang.String getDescription()
                                throws XMLDBCException

Retrieves the description of the XML collection.

Returns:

the description of the XML collection.

Throws:

XMLDBCException - if a data source access error occurs.

setDescription

public void setDescription(java.lang.String description)
                    throws XMLDBCException

Sets the description of the XML collection.

Parameters:

description - the description of the XML collection.

Throws:

XMLDBCException - if a data source access error occurs.

getDocumentCount

public long getDocumentCount()
                      throws XMLDBCException

Retrieves the XML collection size (number of documents).

Returns:

the XML collection size.

Throws:

XMLDBCException - if a data source access error occurs.

isReadOnly

public boolean isReadOnly()
                   throws XMLDBCException

Returns true if the XML collection is read-only mode.

Returns:

true if read-only, false otherwise.

Throws:

XMLDBCException - if a data source access error occurs.

setReadOnly

public void setReadOnly(boolean readOnly)
                 throws XMLDBCException

Changes the read-only mode for this XML collection.

Parameters:

readOnly - true to change mode to read-only, false otherwise.

Throws:

XMLDBCException - if a data source access error occurs.

getConnection

public XMLConnection getConnection()
                            throws XMLDBCException

Retrieves the XMLConnection object that produced this XMLCollection.

Returns:

the XMLConnection object that produced this XMLCollection.

Throws:

XMLDBCException - if a data source access error occurs.

getDocumentFiler

public XMLDocumentFiler getDocumentFiler()
                                  throws XMLDBCException

Creates a "filer" object that can be used to insert a new XML document into the XML collection. A single filer can store several documents sequentially, however it is an error to try to use a filer before the current storage is finished.

Warning: Asuming an XMLConnection is monothread, being able to create multiple XMLDocumentFiler does not mean one can use XMLDocumentFiler created from the same XMLCollection in different threads.

Returns:

an XMLDocumentFiler object.

Throws:

XMLDBCException - if a database access error occurs.

getDocument

public XMLDocument getDocument(java.lang.String documentID)
                        throws XMLDBCException

Retrieves an XML document in the XML collection.

Note: implementations may accept for performance reasons the XMLDocument creation even if the document does not really exist. In that situation, an exception will be raised on subsequent operations.

Parameters:

documentID - the string used to identify the XML document in the collection.

Returns:

an object representing the XML document, or null if not found.

Throws:

XMLDBCException - if a data source access error occurs.

removeDocument

public boolean removeDocument(java.lang.String documentID)
                       throws XMLDBCException

Removes the named XML document from the XML collection.

Parameters:

documentID - the string used to identify the XML document in the collection.

Returns:

true if the XML document has been found, false otherwise.

Throws:

XMLDBCException - if a data source access error occurs.

removeAllDocuments

public int removeAllDocuments()
                       throws XMLDBCException

Removes all XML documents from the XML collection.

Returns:

the number of XML documents removed.

Throws:

XMLDBCException - if a data source access error occurs.

containsDocument

public boolean containsDocument(java.lang.String documentID)
                         throws XMLDBCException

Checks if a named XML document exists in this XML collection.

Parameters:

documentID - the string used to identify the XML document in the collection.

Returns:

true if the document exists in this XML collection, false otherwise.

Throws:

XMLDBCException - if a data source access error occurs.

renameDocument

public boolean renameDocument(java.lang.String oldID,
                              java.lang.String newID)
                       throws XMLDBCException

Renames a document.

Parameters:

oldID - the old string used to identify the XML document in the collection.

newID - the new string used to identify the XML document in the collection.

Returns:

true if the document has been found, false otherwise.

Throws:

XMLDBCException - if an error or operation not supported.

getIdentifierList

public java.util.List getIdentifierList()
                                 throws XMLDBCException

Returns a list of documents identifiers available in the XML collection. Because of potential updates to the data source, the iterator does not necessarily return valid identifiers, nor does it necessarily return all the documents in the collection.

Returns:

a list of documents identifiers as String objects.

Throws:

XMLDBCException - if data source access error occurs or operation not supported.