View Javadoc

1   /*
2    * ModeShape (http://www.modeshape.org)
3    * See the COPYRIGHT.txt file distributed with this work for information
4    * regarding copyright ownership.  Some portions may be licensed
5    * to Red Hat, Inc. under one or more contributor license agreements.
6    * See the AUTHORS.txt file in the distribution for a full listing of 
7    * individual contributors. 
8    *
9    * ModeShape is free software. Unless otherwise indicated, all code in ModeShape
10   * is licensed to you under the terms of the GNU Lesser General Public License as
11   * published by the Free Software Foundation; either version 2.1 of
12   * the License, or (at your option) any later version.
13   *
14   * ModeShape is distributed in the hope that it will be useful,
15   * but WITHOUT ANY WARRANTY; without even the implied warranty of
16   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17   * Lesser General Public License for more details.
18   *
19   * You should have received a copy of the GNU Lesser General Public
20   * License along with this software; if not, write to the Free
21   * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
22   * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
23   */
24  package org.modeshape.connector.meta.jdbc;
25  
26  import java.sql.Connection;
27  import java.sql.DatabaseMetaData;
28  import java.util.List;
29  
30  /**
31   * The {@code MetadataCollector} provides hooks for DBMS-specific implementations of metadata retrieval methods. These methods
32   * largely duplicate what is provided in {@link DatabaseMetaData the JDBC metadata interface}, but allow a pluggable way to work
33   * around JDBC driver-specific shortcomings.
34   * <p>
35   * For convenience, a {@link JdbcMetadataCollector} default implementation} of this interface is provided that is based on
36   * {@link DatabaseMetaData}.
37   * </p>
38   * 
39   * @see JdbcMetadataCollector
40   */
41  public interface MetadataCollector {
42  
43      /**
44       * Return the list of catalog names that currently exist in the database to which {@code connection} is connected. The names
45       * must be sorted in a manner that is stable between successive calls to this method.
46       * 
47       * @param conn the connection to the database; must not be non-null and must be open. This connection should not be closed by
48       *        this method.
49       * @return An ordered list of the catalogs in the database, or an empty list if no catalogs exist; may not be null
50       * @throws JdbcMetadataException if the catalog names cannot be retrieved
51       * @see DatabaseMetaData#getCatalogs()
52       */
53      List<String> getCatalogNames( Connection conn ) throws JdbcMetadataException;
54  
55      /**
56       * Return the list of schema names that currently exist in the database to which {@code connection} is connected within the
57       * named catalog. If {@code catalogName} is null, then all schema names should be returned regardless of the catalog with
58       * which they are associated. The schema names must be sorted in a manner that is stable between successive calls to this
59       * method.
60       * 
61       * @param conn the connection to the database; must not be non-null and must be open. This connection should not be closed by
62       *        this method.
63       * @param catalogName the name of the catalog to which returned schemas must belong, or null if all schemas are to be returned
64       * @return An ordered list of the schemas in the database, or an empty list if no schemas exist; may not be null
65       * @throws JdbcMetadataException if the schema names cannot be retrieved
66       * @see DatabaseMetaData#getSchemas()
67       */
68      List<String> getSchemaNames( Connection conn,
69                                   String catalogName ) throws JdbcMetadataException;
70  
71      /**
72       * Return the list of tables that currently exist in the database to which {@code connection} is connected within the named
73       * catalog (if {@code catalogName} is non-null) and named schema (if {@code schemaName} is non-null). If {@code tableName} is
74       * null, then all tables which conform to the catalog and schema restriction noted previously should be returned. If {@code
75       * tableName} is non-null, then only the table(s) that exactly match that name should be returned. The table metadata must be
76       * sorted in a manner that is stable between successive calls to this method.
77       * 
78       * @param conn the connection to the database; must not be non-null and must be open. This connection should not be closed by
79       *        this method.
80       * @param catalogName the name of the catalog to which returned tables must belong, or null if tables are to be returned
81       *        without regard to their catalog
82       * @param schemaName the name of the schema to which returned tables must belong, or null if tables are to be returned without
83       *        regard to their schema
84       * @param tableName the name of the table to be returned, or null if all tables within the given catalog and schema are to be
85       *        returned
86       * @return An ordered list of the tables in the database that match the given constraints, or an empty list if no tables exist
87       *         that match the given constraints; may not be null
88       * @throws JdbcMetadataException if the table metadata cannot be retrieved
89       * @see DatabaseMetaData#getTables(String, String, String, String[])
90       */
91      List<TableMetadata> getTables( Connection conn,
92                                     String catalogName,
93                                     String schemaName,
94                                     String tableName ) throws JdbcMetadataException;
95  
96      /**
97       * Return the list of columns that currently exist in the database to which {@code connection} is connected within the named
98       * catalog (if {@code catalogName} is non-null), named schema (if {@code schemaName} is non-null), and named table. If {@code
99       * columnName} is null, then all columns which conform to the catalog, schema, and table restrictions noted previously should
100      * be returned. If {@code columnName} is non-null, then only the column that exactly matches that name should be returned. The
101      * column metadata must be sorted in a manner that is stable between successive calls to this method.
102      * 
103      * @param conn the connection to the database; must not be non-null and must be open. This connection should not be closed by
104      *        this method.
105      * @param catalogName the name of the catalog to which returned columns must belong, or null if columns are to be returned
106      *        without regard to their catalog
107      * @param schemaName the name of the schema to which returned columns must belong, or null if columns are to be returned
108      *        without regard to their schema
109      * @param tableName the name of the table to which returned columns must belong; may not be null
110      * @param columnName the name of the column to be returned, or null if all columns within the given catalog, schema, and table
111      *        are to be returned
112      * @return An ordered list of the columns in the database that match the given constraints, or an empty list if no columns
113      *         exist that match the given constraints; may not be null
114      * @throws JdbcMetadataException if the column metadata cannot be retrieved
115      * @see DatabaseMetaData#getColumns(String, String, String, String)
116      */
117     List<ColumnMetadata> getColumns( Connection conn,
118                                      String catalogName,
119                                      String schemaName,
120                                      String tableName,
121                                      String columnName ) throws JdbcMetadataException;
122 
123     /**
124      * Return the list of procedures that currently exist in the database to which {@code connection} is connected within the
125      * named catalog (if {@code catalogName} is non-null) and named schema (if {@code schemaName} is non-null). If {@code
126      * procedureName} is null, then all procedures which conform to the catalog and schema restriction noted previously should be
127      * returned. If {@code procedureName} is non-null, then only the procedure(s) that exactly match that name should be returned.
128      * The procedure metadata must be sorted in a manner that is stable between successive calls to this method.
129      * 
130      * @param conn the connection to the database; must not be non-null and must be open. This connection should not be closed by
131      *        this method.
132      * @param catalogName the name of the catalog to which returned procedures must belong, or null if procedures are to be
133      *        returned without regard to their catalog
134      * @param schemaName the name of the schema to which returned procedures must belong, or null if procedures are to be returned
135      *        without regard to their schema
136      * @param procedureName the name of the procedure(s) to be returned, or null if all procedures within the given catalog and
137      *        schema are to be returned
138      * @return An ordered list of the procedures in the database that match the given constraints, or an empty list if no
139      *         procedures exist that match the given constraints; may not be null
140      * @throws JdbcMetadataException if the procedure metadata cannot be retrieved
141      */
142     List<ProcedureMetadata> getProcedures( Connection conn,
143                                            String catalogName,
144                                            String schemaName,
145                                            String procedureName ) throws JdbcMetadataException;
146 
147 }