001:
002: /*
003: * GeoTools - OpenSource mapping toolkit
004: * http://geotools.org
005: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation;
010: * version 2.1 of the License.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: */
017: package org.geotools.data.jdbc.datasource;
018:
019: import java.io.IOException;
020: import java.util.Map;
021:
022: import javax.sql.DataSource;
023:
024: import org.geotools.data.DataStoreFactorySpi.Param;
025: import org.geotools.factory.Factory;
026:
027: /**
028: * Constructs a live DataSource from a set of parameters.
029: *
030: * <p>
031: * An instance of this interface should exist for all DataSource providers, common examples being JNDI, DBCP, C3P0. In addition to implementing
032: * this interface data source providers should have a services file:
033: * </p>
034: *
035: * <p>
036: * <code>META-INF/services/org.geotools.data.DataSourceFactorySpi</code>
037: * </p>
038: *
039: * <p>
040: * The file should contain a single line which gives the full name of the
041: * implementing class.
042: * </p>
043: *
044: * <p>
045: * example:<br/><code>e.g.
046: * org.geotools.data.dbpc.DBCPDataSourceFactory</code>
047: * </p>
048: *
049: * <p>
050: * The factories are never called directly by client code, instead the
051: * DataSourceFinder class is used.
052: * </p>
053: *
054: * <p>
055: * The following example shows how a user might setup a DBCP connection pool::
056: * </p>
057: *
058: * <p>
059: * <pre><code>
060: * HashMap params = new HashMap();
061: * params.put("url","jdbc:postgresql://localhost/dbname");
062: * params.put("driverClassName","org.postgresql.Driver");
063: * params.put("username", "5432");
064: * params.put("password","postgis_test");
065: * params.put("maxActive", "10");
066: *
067: * DataSource ds = DataSourceFinder.getDataSource(params);
068: * </code></pre>
069: * </p>
070:
071: * @author Andrea Aime - TOPP
072: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/jdbc/src/main/java/org/geotools/data/jdbc/datasource/DataSourceFactorySpi.java $
073: */
074: public interface DataSourceFactorySpi extends Factory {
075: /**
076: * Construct a live data source using the params specifed. The returned DataSource may be pooled.
077:
078: * @param params The full set of information needed to construct a live
079: * DataSource.
080: *
081: * @return The created DataSource, this may be null if the required resource
082: * was not found or if insufficent parameters were given. Note
083: * that canProcess() should have returned false if the problem is
084: * to do with insuficent parameters.
085: *
086: * @throws IOException if there were any problems setting up (creating or
087: * connecting) the datasource.
088: */
089: DataSource createDataSource(Map params) throws IOException;
090:
091: /**
092: * Same as {@link #createDataSource(Map)}, but forces the creation of a new DataSource
093: * @param params
094: * @return
095: * @throws IOException
096: */
097: DataSource createNewDataSource(Map params) throws IOException;
098:
099: /**
100: * Name suitable for display to end user.
101: *
102: * <p>
103: * A non localized display name for this data source type.
104: * </p>
105: *
106: * @return A short name suitable for display in a user interface.
107: */
108: String getDisplayName();
109:
110: /**
111: * Describe the nature of the data source constructed by this factory.
112: *
113: * <p>
114: * A non localized description of this data store type.
115: * </p>
116: *
117: * @return A human readable description that is suitable for inclusion in a
118: * list of available datasources.
119: */
120: String getDescription();
121:
122: /**
123: * MetaData about the required Parameters (for {@link #createDataSource(Map)}).
124: * @return Param array describing the Map for createDataStore
125: */
126: Param[] getParametersInfo();
127:
128: /**
129: * Test to see if this factory is suitable for processing the data pointed
130: * to by the params map.
131: *
132: * <p>
133: * If this data source requires a number of parameters then this mehtod
134: * should check that they are all present and that they are all valid.
135: * </p>
136: *
137: * @param params The full set of information needed to construct a live
138: * data source.
139: *
140: * @return booean true if and only if this factory can process the resource
141: * indicated by the param set and all the required params are
142: * pressent.
143: */
144: boolean canProcess(Map params);
145:
146: /**
147: * Test to see if this data source is available, if it has all the
148: * appropriate libraries to construct a datastore.
149: *
150: * @return <tt>true</tt> if and only if this factory has all the
151: * appropriate jars on the classpath to create DataSource.
152: */
153: boolean isAvailable();
154: }
|