XMLConnection


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  /**
26   * This interface represents a connection with a specific XML data source.
27   * Within the context of an XMLConnection, XQuery or XPath statements are executed
28   * and XML results are returned.<BR>
29   * This interface is used by both read-only connections and storage connections,
30   * which require access to a larger set of interfaces, such as interfaces representing
31   * XML collections and documents. Classes providing read-only access to XML data sources
32   * can avoid implementing the optional interfaces for XML storage management, by deriving
33   * from the abstract class DefautReadOnlyXMLConnection.
34   *
35   */
36  public interface XMLConnection {
37  
38      /*********************************************************************/
39      /*************************** Constants declaration *******************/
40      /*********************************************************************/
41   
42  
43  
44      /** Indicates that transactions are not supported. */
45      public static final short TRANSACTION_NONE = 0;
46  
47      /** Indicates that transactions are supported but dirty reads, non-repeatable reads and phantom reads can occur. */
48      public static final short TRANSACTION_READ_UNCOMMITTED = 1;
49  
50      /** Indicates that transactions are supported and dirty reads are prevented but non-repeatable reads and phantom reads can occur. */
51      public static final short TRANSACTION_READ_COMMITTED = 2;
52  
53      /** Indicates that transactions are supported, dirty reads and non-repeatable reads are prevented but phantom reads can occur. */
54      public static final short TRANSACTION_REPEATABLE_READ = 4;
55  
56      /** Indicates that transactions are supported but and dirty reads, non-repeatable reads and phantom reads are prevented. */
57      public static final short TRANSACTION_SERIALIZABLE = 8;
58  
59      /** Defines type for queries: XQuery in a String. */
60      public static final short XQUERY_STRING_TYPE = 0;
61  
62      /** Defines type for queries: XPath in a String. */
63      public static final short XPATH_STRING_TYPE = 1;
64  
65      /*********************************************************************/
66      /*************************** Connection management *******************/
67      /*********************************************************************/
68  
69      /**
70       * To close the current data source connection.
71       * @throws XMLDBCException if a data source access error occurs.
72       */
73      public void close() throws XMLDBCException;
74  
75      /**
76       * To know the connection state (opened or closed).
77       * @return true if the current connection is closed, else false.
78       * @throws XMLDBCException if a data source access error occurs.
79       */
80      public boolean isClosed() throws XMLDBCException;
81  
82      /**
83       * To know the read/write mode of the current connection.
84       * @return true if connection is read-only, else false.
85       * @throws XMLDBCException if a data source access error occurs.
86       */
87      public boolean isReadOnly() throws XMLDBCException;
88  
89      /**
90       * To change the read/write mode of the connection. Some data sources can
91       * make optimisations if the connection is in read-only mode.
92       * @param readOnlyMode if true, the connection will pass in read-only mode, else in read/write mode.
93       * @throws XMLDBCException if a data source access error occurs.
94       * @throws XMLDBCNotSupportedException if the data source is read-only and the parameter is false.
95       */
96      public void setReadOnly(boolean readOnlyMode) throws XMLDBCException, XMLDBCNotSupportedException;
97  
98      /**
99       * Gets the metadata regarding this connection's data source. A
100      * connection's data source is able to provide information
101      * describing itself. By default, metadata is loaded one time and cached.
102      * Use {@link #getMetaData(boolean) getMetaData(boolean)} to enforce refresh.
103      * @return an XMLDataSourceMetaData object for this connection.
104      * #see #getMetaData(boolean)
105      * @throws XMLDBCException if a data source access error occurs.
106      */
107     public XMLDataSourceMetaData getMetaData() throws XMLDBCException;
108 
109     /**
110      * Gets the metadata regarding this connection's data source. A
111      * connection's data source is able to provide information
112      * describing itself.
113      * @param refresh if true, reload metadata.
114      * @return an XMLDataSourceMetaData object for this connection.
115      * @throws XMLDBCException if a data source access error occurs.
116      */
117     public XMLDataSourceMetaData getMetaData(boolean refresh) throws XMLDBCException;
118 
119     /**
120      * To get the current user name.
121      * @return the current user name.
122      * @throws XMLDBCException if a data source access error occurs.
123      */
124     public String   getUserName() throws XMLDBCException;
125 
126     /**
127      * To get the current URL of this connection.
128      * @return the current URL of this connection.
129      * @throws XMLDBCException if a data source access error occurs.
130      */
131     public String   getURL() throws XMLDBCException;
132 
133     /*********************************************************************/
134     /*************************** Create/prepare statements ***************/
135     /*********************************************************************/
136 
137     /**
138      * Creates a statement object for sending XQuery (query type by default)
139      * statements to the data source.
140      * @return a new statement.
141      * @throws XMLDBCException if a data source access error occurs.
142      */
143     public XMLStatement createStatement() throws XMLDBCException;
144 
145     /**
146      * Creates a statement object for sending XQuery or XPath (according to the
147      * specified type) statements to the data source.
148      * @param queryType the type of query for this statement (see constants in this interface).
149      * @return a new statement.
150      * @throws XMLDBCException if a data source access error occurs.
151      */
152     public XMLStatement createStatement(short queryType) throws XMLDBCException;
153 
154     /**
155      * Creates a prepared statement object for sending parameterized XQuery
156      * (query type by default) statements to the data source.
157      * The advantage of prepared statements over statements is that the request
158      * may be precompiled once and executed several times.
159      * Note: this interface is optional.
160      * @param query a parameterized XQuery.
161      * @return a new prepared statement containing the pre-compiled statement.
162      * @throws XMLDBCException if a data source access error occurs.
163      * @throws XMLDBCNotSupportedException if the method is not supported.
164      */
165     public PreparedXMLStatement prepareStatement(String   query) throws XMLDBCException, XMLDBCNotSupportedException;
166 
167     /*********************************************************************/
168     /*************************** XML collection management ***************/
169     /*********************************************************************/
170 
171     /**
172      * Creates a new XML Collection configuration for set features and properties before create a XML Collection.
173      * @return a Configurable object which properties and features are vendor-dependant.
174      * @throws XMLDBCException if a data source access error occurs.
175      * @throws XMLDBCNotSupportedException if the data source does not support this operation (typically, when the data source is read-only)
176      */
177     public Configurable createCollectionConfig() throws XMLDBCException, XMLDBCNotSupportedException;
178 
179     /**
180      * Creates a new XML collection. Each XML collections can be configured.
181      * @param name the unique name of the new XML collection.
182      * @param description the description of the new XML collection (optional).
183      * @param config a XML collection configuration. If null, the XML collection will be created with default configuration.
184      * @return an instance of XML collection.
185      * @throws XMLDBCException if a data source access error occurs or if the XML collection name already exists.
186      * @throws XMLDBCNotSupportedException if the data source does not support this operation (typically, when the data source is read-only)
187      */
188     public XMLCollection createCollection(String   name, String   description, Configurable config) throws XMLDBCException, XMLDBCNotSupportedException;
189 
190     /**
191      * Deletes an XML collection by its name.
192      * @param name the unique name of an existing XML collection.
193      * @throws XMLDBCException if a data source access error occurs or if the XML collection does not exist.
194      * @throws XMLDBCNotSupportedException if the data source does not support this operation (typically, when the data source is read-only)
195      */
196     public void deleteCollection(String   name) throws XMLDBCException, XMLDBCNotSupportedException;
197 
198     /**
199      * Renames an XML collection by its name.
200      * @param oldname the unique name of an existing XML collection.
201      * @param newname the new unique name of an existing XML collection.
202      * @throws XMLDBCException if a data source access error errors, if the collection does not exist, or if the new name is not unique.
203      * @throws XMLDBCNotSupportedException if the data source does not support this operation (typically, when the data source is read-only)
204      */
205     public void renameCollection(String   oldname, String   newname) throws XMLDBCException, XMLDBCNotSupportedException;
206 
207     /**
208      * Deletes all XML collections of this connection.
209      * @return the number of XML collections deleted.
210      * @throws XMLDBCException if a data source access error occurs.
211      * @throws XMLDBCNotSupportedException if the data source does not support this operation (typically, when the data source is read-only)
212      */
213     public int deleteAllCollections() throws XMLDBCException, XMLDBCNotSupportedException;
214 
215     /**
216      * Creates an XMLcollection object featuring the XML documents collection.
217      * <p>The returned object may hold resources and should be closed after
218      * use.</p>
219      * @param name a name of an XML documents collection.
220      * @return the XML collection that has the specified name or 'null' if there is no XML collection with this name.
221      * @throws XMLDBCException if a data source access error occurs.
222      * @throws XMLDBCNotSupportedException if the data source does not support this operation (typically, when the data source is read-only)
223      */
224     public XMLCollection getCollection(String   name) throws XMLDBCException, XMLDBCNotSupportedException;
225 
226     /*********************************************************************/
227     /*************************** Transaction management ******************/
228     /*********************************************************************/
229 
230     /**
231      * Makes all changes made since the previous commit/rollback
232      * permanent and releases any data source locks currently
233      * held by the Connection. This method has no effect when
234      * auto-commit mode has been enabled.
235      * @throws XMLDBCException if a data source access error occurs.
236      * @throws XMLDBCNotSupportedException if the data source does not support transactions
237      */
238     public void commit() throws XMLDBCException, XMLDBCNotSupportedException;
239 
240     /**
241      * Sets this connection's auto-commit mode. If the parameter is true, a commit will be done after each statement execution, else
242      * otherwise a commit will have to be made explicitly by calling the commit method.
243      * @param autoCommitMode if true, the connection will pass in auto-commit mode, else in manual commit mode.
244      * @throws XMLDBCException if a data source access error occurs.
245      * @throws XMLDBCNotSupportedException if the data source does not support transactions
246      */
247     public void setAutoCommit(boolean autoCommitMode) throws XMLDBCException, XMLDBCNotSupportedException;
248 
249     /**
250      * To know the current auto-commit state.
251      * @return true if the current connection is in auto-commit mode, else false.
252      * @throws XMLDBCException if a data source access error occurs.
253      * @throws XMLDBCNotSupportedException if the data source does not support transactions
254      */
255     public boolean getAutoCommit() throws XMLDBCException, XMLDBCNotSupportedException;
256 
257     /**
258      * Drops all changes made since the previous commit/rollback and releases any data source locks currently held by
259      * this Connection. This method should be used only when auto-commit has been disabled.
260      * @throws XMLDBCException if a data source access error occurs.
261      * @throws XMLDBCNotSupportedException if the data source does not support transactions
262      */
263     public void rollback() throws XMLDBCException, XMLDBCNotSupportedException;
264 
265     /**
266      * Gets this Connection's current transaction isolation level.
267      * @return the current TRANSACTION_* mode value (see fields summary).
268      * @throws XMLDBCException if a data source access error occurs.
269      * @throws XMLDBCNotSupportedException if the data source does not support transactions
270      */
271     public short getTransactionIsolation() throws XMLDBCException, XMLDBCNotSupportedException;
272 
273     /**
274      * Attempts to change the transaction isolation level to the one given. The constants defined in the interface
275      * Connection are the possible transaction isolation levels.
276      * This method cannot be called while in the middle of a transaction.
277      * @param level one of the TRANSACTION_* (see field summary) isolation values with the exception of
278      * TRANSACTION_NONE; some data sources may not support other values.
279      * @throws XMLDBCException if a data source access error occurs.
280      * @throws XMLDBCNotSupportedException if the data source does not support transactions
281      */
282     public void setTransactionIsolation(short level) throws XMLDBCException, XMLDBCNotSupportedException;
283 
284     /**
285      * Sets the base URI for documents.
286      * @return nothing 
287      */
288     public void setBaseURI(String   baseURI);
289 }
290 
291
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags