KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xquark > xml > xdbc > XMLDataSourceMetaData


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 JavaDoc;
26
27 /**
28  * This interface provides comprehensive information about the "data source".
29  * Since this interface accesses all sorts of data sources, the term data source is loosely applied.
30  * Information provided depend on driver vendors implementation.<BR>
31  * An XMLDBCNotSupportedException will be thrown if a driver does not support a metadata method.<BR><BR>
32  */

33 public interface XMLDataSourceMetaData {
34  
35
36
37     /**
38      * Inner interface of XMLDataSourceMetaData interface.<BR><BR>
39      */

40     public static interface Entry {
41
42     /**
43      * Gets the input specification as an XPath expression.
44      */

45     public java.lang.String JavaDoc getInput();
46
47     /**
48      * Gets the output specification as an XPath expression.
49      */

50     public java.lang.String JavaDoc getOutput();
51
52     /**
53      * Sets the input specification
54      * @param xpath XPath expression that is valid over the schema
55      */

56     public void setInput(java.lang.String JavaDoc xpath);
57
58     /**
59      * Sets the output specification
60      * @param xpath XPath expression that is valid over the schema
61      */

62     public void setOutput(java.lang.String JavaDoc xpath);
63     }
64
65     /**
66      * Get the properties that describe this data source.
67      * <p>
68      * Valid properties are listed in the table.<br>
69      * The type "int" means the property value string is a valid
70      * integer.<br>
71      * The type "string" means the property value is a string.<br>
72      * The type "boolean" means the property value is "true" or "false".<br>
73      * <p>
74      * <table border=1>
75      * <tr> <td><b>Property</b></td><td><b>Definition</b></td><td><b>Type</b></td></tr>
76      * <tr> <td>xmldbc.maxConnections</td> <td>Maximum active connections</td> <td>int</td> </tr>
77      * <tr> <td>xmldbc.maxStatementLength</td> <td>Maximum length for a statement</td> <td>int</td> </tr>
78      * <tr> <td>xmldbc.maxActiveStatements</td> <td>Maximum number of active statements</td> <td>int</td> </tr>
79      * <tr> <td>xmldbc.maxResultSetLength</td> <td>Maximum length of a result set</td> <td>int</td> </tr>
80      * <tr> <td>xmldbc.maxUserNameLength</td> <td>Maximum length of a user name</td> <td>int</td> </tr>
81      * <tr> <td>xmldbc.dataSourceVersion</td> <td>Version number of the data source</td> <td>string</td> </tr>
82      * <tr> <td>xmldbc.vendor.name</td> <td>Name of vendor of underlying source</td> <td>string</td> </tr>
83      * <tr> <td>xmldbc.vendor.product</td> <td>Product name of vendor of underlying source</td> <td>string</td> </tr>
84      * <tr> <td>xmldbc.vendor.version</td> <td>Version string of vendor of underlying source</td> <td>string</td> </tr>
85      * <tr> <td>xmldbc.driver.version</td> <td>Version string of this XMLDBC driver</td> <td>string</td> </tr>
86      * <tr> <td>xmldbc.driver.product</td> <td>Product name of this XMLDBC driver</td> <td>string</td> </tr>
87      * <tr> <td>xmldbc.xpath</td> <td>Supports XPath</td> <td>boolean</td> </tr>
88      * <tr> <td>xmldbc.xpath.version</td> <td>Version of XPath supported</td> <td>string</td> </tr>
89      * <tr> <td>xmldbc.xquery</td> <td>Supports XQuery</td> <td>boolean</td> </tr>
90      * <tr> <td>xmldbc.xquery.version</td> <td>Version of XQuery supported</td> <td>string</td> </tr>
91      * <tr> <td>xmldbc.xquery.outerJoin</td> <td>Supports XQuery outer join</td> <td>boolean</td> </tr>
92      * <tr> <td>xmldbc.twoPhaseCommit</td> <td>Supports two phase commit</td> <td>boolean</td> </tr>
93      * <tr> <td>xmldbc.xquery.equality</td> <td>Supports equality operator in WHERE clause</td> <td>boolean</td> </tr>
94      * <tr> <td>xmldbc.xquery.result</td> <td>Supports construction in RESULT clause</td> <td>boolean</td> </tr>
95      * <tr> <td>xmldbc.xmlCollection</td> <td>Supports at least part of XMLCollection</td> <td>boolean</td> </tr>
96      * <tr> <td>xmldbc.xmlCollection.id</td> <td>Supports methods that use XML ID String</td> <td>boolean</td> </tr>
97      * <tr> <td>xmldbc.xmlCollection.iterator</td> <td>Supports iterator() method</td> <td>boolean</td> </tr>
98      * <tr> <td>xmldbc.xquery.multiCollection</td> <td>An XQUERY expression may reference multiple XMLCollections</td> <td>boolean</td> </tr>
99      * <tr> <td></td> <td></td> <td></td> </tr>
100      * </table>
101      * <p>
102      * For example, a data source that supports all of XQuery without restriction
103      * would define true for the xmldb.xquery property. This property implies all other xmldbc.xquery.*
104      * properties are supported. A data source
105      * that provided no query functionality at all and simply dumped
106      * its contents (e.g. an XML file), would not provide any
107      * properties at all. A data source may return other properties not listed.
108      * For developers, note that no set of capabilities can completely describe all data sources,
109      * so a particular data source may throw XMLDBCNotSupportedException in rare circumstances.
110      * @return the property set describing this data source
111      */

112     String JavaDoc[] getPropertyList();
113
114     /**
115      * Get the property with the specified name
116      * @return the value of the property
117      * @throws XMLDBCNotRecognizedException if the property is not known
118      */

119     Object JavaDoc getProperty(String JavaDoc propertyId) throws XMLDBCNotRecognizedException;
120     
121     //*************************** Connection informations:
122

123     /**
124      * To get the XMLConnection object that produced this XMLDataSourceMetaData object.
125      * @return the XMLConnection object that produced this object.
126      * @throws XMLDBCException if a data source access error occurs.
127      */

128     public XMLConnection getConnection() throws XMLDBCException;
129
130     //*************************** Other metadata informations
131

132     /**
133      * Retrieves the name of all XML collections in this data source.
134      * @return a list of all XML collection names as String objects.
135      * @throws XMLDBCException if a data source access error occurs.
136      * @throws XMLDBCNotSupportedException if the data source does not support this operation (typically, when the data source is read-only)
137      */

138     public List JavaDoc getCollectionNames() throws XMLDBCException, XMLDBCNotSupportedException;
139
140     /**
141      * Retrieves the available schema namespaces in the data source.
142      * @return the target namespaces of all schemas available in the data source
143      * in a list of String objects.
144      * @throws XMLDBCException if a data source access error occurs.
145      */

146     public List JavaDoc getSchemaNamespaces() throws XMLDBCException;
147
148     /**
149      * Retrieves the XML document describing all existing paths in all documents
150      * of the specified XML collection.
151      * @param colName the name of the XML collection.
152      * @return an XML document containing the path set.
153      * @throws XMLDBCException if a data source access error occurs.
154      */

155     public XMLDocument getPathSet(String JavaDoc colName) throws XMLDBCException;
156
157     /**
158      * Retrieves the XML document describing the XML schema for the given namespace.
159      * @param targetNamespace the target namespace of the schema.
160      * @return an XML document containing the XML schema.
161      * @throws XMLDBCException if a data source access error occurs.
162      */

163     public XMLDocument getSchema(String JavaDoc targetNamespace) throws XMLDBCException;
164
165     /**
166      * Retrieves the XML document describing the complete metadata of the data source.
167      * This includes all available schemas and the path set of all available XML collections.
168      * @return an XML document containing the data source metadata.
169      * @throws XMLDBCException if a data source access error occurs.
170      */

171     public XMLDocument getMetaData() throws XMLDBCException;
172
173     /**
174      * To get the set of capabilities of the data source. Each element is a
175      * DataSourceMetaData.Entry object. The input is an XPath
176      * expression that requires a value in the
177      * WHERE clause. The output is an XPath expression describing the
178      * output. An empty set indicates no retrictions on the queries.
179      */

180     public java.util.Set JavaDoc getCapabilities();
181 }
182
183
Popular Tags