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  ;
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   getInput();
46  
47      /**
48       * Gets the output specification as an XPath expression.
49       */
50      public java.lang.String   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   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   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  [] 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   getProperty(String   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   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   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   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   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   getCapabilities();
181 }
182 
183
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags