01: /*
02: * GeoTools - OpenSource mapping toolkit
03: * http://geotools.org
04: * (C) 2005-2006, GeoTools Project Managment Committee (PMC)
05: * (C) 2005, Institut de Recherche pour le Développement
06: *
07: * This library is free software; you can redistribute it and/or
08: * modify it under the terms of the GNU Lesser General Public
09: * License as published by the Free Software Foundation;
10: * version 2.1 of the License.
11: *
12: * This library is distributed in the hope that it will be useful,
13: * but WITHOUT ANY WARRANTY; without even the implied warranty of
14: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15: * Lesser General Public License for more details.
16: */
17: package org.geotools.referencing.factory.epsg;
18:
19: // J2SE dependencies
20: import java.sql.SQLException;
21:
22: // Geotools dependencies
23: import org.geotools.factory.Hints;
24: import org.geotools.factory.AbstractFactory;
25: import org.geotools.referencing.ReferencingFactoryFinder;
26: import org.geotools.referencing.factory.AbstractAuthorityFactory;
27:
28: /**
29: * A marker interface for data source to an EPSG database. This sub-interface of J2SE's
30: * {@code DataSource} is used as a category for {@link javax.imageio.spi.ServiceRegistry}.
31: * EPSG data sources should be registered in the following file:
32: *
33: * <blockquote><pre>META-INF/services/org.geotools.referencing.factory.epsg.DataSource</pre></blockquote>
34: *
35: * For an example, see {@link org.geotools.referencing.factory.epsg.AccessDataSource}
36: * and its {@code META-INF/services/} registration in the {@code plugin/epsg-access}
37: * module. This is a very small module which can be used as a starting point for custom
38: * EPSG data sources.
39: * <p>
40: * <h3>How EPSG factory are found</h3>
41: * By default, only one {@link ThreadedEpsgFactory} is registered and returned by {@link ReferencingFactoryFinder}.
42: * We don't need to register any other implementation for an EPSG factory backed by a SQL database.
43: * However, {@code ThreadedEpsgFactory} alone is not suffisient for querying the database. It needs one
44: * more "plugable" information: the <cite>connection</cite> to the EPSG database. This
45: * {@code DataSource} interface is there for providing such connection to {@code ThreadedEpsgFactory}.
46: * <p>
47: * Some time after {@code ThreadedEpsgFactory} is registered as an EPSG factory, it looks for a
48: * {@code DataSource} using the same plugins mechanism than for factories. In other words,
49: * {@code DataSource} is a second level of plugins used internally by {@link ThreadedEpsgFactory}.
50: *
51: * @since 2.1
52: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/referencing/src/main/java/org/geotools/referencing/factory/epsg/DataSource.java $
53: * @version $Id: DataSource.java 25972 2007-06-21 13:38:35Z desruisseaux $
54: * @author Martin Desruisseaux
55: *
56: * @deprecated Experience suggests that subclassing {@code javax.sql.DataSource} is a cause of
57: * troubles in JEE environments. Subclass directly {@link ThreadedEpsgFactory} instead.
58: * NOTE: After the removal of this interface, we will need to unregister
59: * {@link ThreadedEpsgFactory} from {@code META-INF/services}.
60: */
61: public interface DataSource extends javax.sql.DataSource {
62: /**
63: * The minimum priority for a data source, which is {@value}.
64: * Data sources with lowest priority will be used only if there is no other source available.
65: */
66: int MINIMUM_PRIORITY = AbstractFactory.MINIMUM_PRIORITY;
67:
68: /**
69: * The default priority, which is {@value}.
70: */
71: int NORMAL_PRIORITY = AbstractFactory.NORMAL_PRIORITY;
72:
73: /**
74: * The maximum priority for a data source, which is {@value}.
75: * Data sources with highest priority will be preferred to any other data sources.
76: */
77: int MAXIMUM_PRIORITY = AbstractFactory.MAXIMUM_PRIORITY;
78:
79: /**
80: * Returns the priority for this data source, as a number between
81: * {@link #MINIMUM_PRIORITY} and {@link #MAXIMUM_PRIORITY} inclusive.
82: */
83: int getPriority();
84:
85: /**
86: * Opens a connection and creates an EPSG factory for it. This method may returns a
87: * sub-class of {@link DirectEpsgFactory} if it wants to use slightly different SQL queries.
88: *
89: * @param hints A map of hints, including the low-level factories to use for CRS creation.
90: * This argument should be given unchanged to {@code DirectEpsgFactory} constructor.
91: * @return The {@linkplain DirectEpsgFactory EPSG factory} using SQL queries appropriate
92: * for this data source.
93: * @throws SQLException if connection to the database failed.
94: */
95: AbstractAuthorityFactory createFactory(final Hints hints)
96: throws SQLException;
97: }
|