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.


Copyright © 2004 Université de Versailles Saint-Quentin, XQuark Group. All rights reserved.