XMLCollection


1   /*
2    * This file belongs to the XQuark distribution.
3    * Copyright (C) 2003 Universite de Versailles Saint-Quentin.
4    * 
5    * This program is free software; you can redistribute it and/or
6    * modify it under the terms of the GNU Lesser General Public
7    * License as published by the Free Software Foundation; either
8    * version 2.1 of the License, or (at your option) any later version.
9    * 
10   * This program is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13   * Lesser General Public License for more details.
14   * 
15   * You should have received a copy of the GNU Lesser General Public
16   * License along with this program; if not, write to the Free Software
17   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307.
18   * You can also get it at http://www.gnu.org/licenses/lgpl.html
19   * 
20   * For more information on this software, see http://www.xquark.org.
21   */
22  
23  package org.xquark.xml.xdbc;
24  
25  import java.util.List  ;
26  
27  /**
28   * This interface describes a XML collection of XML documents.<BR><BR>
29   * <p><B>Note:</B></p>
30   * <p>This object is likely to use resources that can be released using the
31   * {@link #close()} method.</p>
32   */
33  public interface XMLCollection extends Configurable
34  {
35  
36      /****************************************************************/
37      /*************************** Constants declaration **************/
38      /****************************************************************/
39   
40  
41  
42      /****************************************************************/
43      /*************************** Collection management **************/
44      /****************************************************************/
45  
46      /**
47       * Closes this XMLCollection. Once a collection is closed, it should not 
48       * be accessed any more.
49       * @throws XMLDBCException if a data source access error occurs.
50       */
51      public void close() throws XMLDBCException;
52  
53      /****************************************************************/
54      /*************************** Fields management ******************/
55      /****************************************************************/
56  
57      /**
58       * Retrieves the unique name of the XML collection.
59       * @return the unique name of the XML collection.
60       * @throws XMLDBCException if a data source access error occurs.
61       */
62      public String   getName() throws XMLDBCException;
63  
64      /**
65       * Retrieves the description of the XML collection.
66       * @return the description of the XML collection.
67       * @throws XMLDBCException if a data source access error occurs.
68       */
69      public String   getDescription() throws XMLDBCException;
70  
71      /**
72       * Sets the description of the XML collection.
73       * @param description the description of the XML collection.
74       * @throws XMLDBCException if a data source access error occurs.
75       */
76      public void setDescription(String   description) throws XMLDBCException;
77  
78      /**
79       * Retrieves the XML collection size (number of documents).
80       * @return the XML collection size.
81       * @throws XMLDBCException if a data source access error occurs.
82       */
83      public long getDocumentCount() throws XMLDBCException;
84  
85      /**
86       * Returns true if the XML collection is read-only mode.
87       * @return true if read-only, false otherwise.
88       * @throws XMLDBCException if a data source access error occurs.
89       */
90      public boolean isReadOnly() throws XMLDBCException;
91  
92      /**
93       * Changes the read-only mode for this XML collection.
94       * @param readOnly true to change mode to read-only, false otherwise.
95       * @throws XMLDBCException if a data source access error occurs.
96       */
97      public void setReadOnly(boolean readOnly) throws XMLDBCException;
98  
99      /**
100      * Retrieves the XMLConnection object that produced this XMLCollection.
101      * @return the XMLConnection object that produced this XMLCollection.
102      * @throws XMLDBCException if a data source access error occurs.
103      */
104     public XMLConnection getConnection() throws XMLDBCException;
105 
106     /****************************************************************/
107     /*************************** Document management ***************/
108     /****************************************************************/
109 
110     /** Creates a "filer" object that can be used to insert a new XML document
111      * into the XML collection. A single filer can store several
112      * documents sequentially, however it is an error to try to use a filer
113      * before the current storage is finished.<BR>
114      * <p><B>Warning:</B> Asuming an {@link XMLConnection} is monothread,
115      * being able to create multiple XMLDocumentFiler does not mean one can use
116      * XMLDocumentFiler created from the same XMLCollection in different
117      * threads.</p>
118      * @return an XMLDocumentFiler object.
119      * @throws XMLDBCException if a database access error occurs.
120      */
121     public XMLDocumentFiler getDocumentFiler() throws XMLDBCException;
122 
123     /**
124      * Retrieves an XML document in the XML collection.
125      * <p>Note: implementations may accept for performance reasons the
126      * XMLDocument creation even if the document does not really exist. In that
127      * situation, an exception will be raised on subsequent operations.</p>
128      * @param documentID the string used to identify the XML document in the collection.
129      * @return an object representing the XML document, or null if not found.
130      * @throws XMLDBCException if a data source access error occurs.
131      */
132     public XMLDocument getDocument(String   documentID) throws XMLDBCException;
133 
134     /**
135      * Removes the named XML document from the XML collection.
136      * @param documentID the string used to identify the XML document in the collection.
137      * @return true if the XML document has been found, false otherwise.
138      * @throws XMLDBCException if a data source access error occurs.
139      */
140     public boolean removeDocument(String   documentID) throws XMLDBCException;
141 
142     /**
143      * Removes all XML documents from the XML collection.
144      * @return the number of XML documents removed.
145      * @throws XMLDBCException if a data source access error occurs.
146      */
147     public int removeAllDocuments() throws XMLDBCException;
148 
149     /**
150      * Checks if a named XML document exists in this XML collection.
151      * @param documentID the string used to identify the XML document in the collection.
152      * @return true if the document exists in this XML collection, false otherwise.
153      * @throws XMLDBCException if a data source access error occurs.
154      */
155     public boolean containsDocument(String   documentID) throws XMLDBCException;
156 
157     /**
158      * Renames a document.
159      * @param oldID the old string used to identify the XML document in the collection.
160      * @param newID the new string used to identify the XML document in the collection. 
161      * @return true if the document has been found, false otherwise.
162      * @throws XMLDBCException if an error or operation not supported.
163      */
164     public boolean renameDocument(String   oldID, String   newID) throws XMLDBCException;
165 
166     /**
167      * Returns a list of documents identifiers available in the XML collection.
168      * Because of potential updates to the data source, the iterator
169      * does not necessarily return valid identifiers, nor does it
170      * necessarily return all the documents in the collection.
171      * @return a list of documents identifiers as String objects.
172      * @throws XMLDBCException if data source access error occurs or operation not supported.
173      */
174     public List   getIdentifierList() throws XMLDBCException;
175 }
176
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags