001    //$HeadURL: svn+ssh://jwilden@svn.wald.intevation.org/deegree/base/branches/2.5_testing/src/org/deegree/crs/configuration/CRSProvider.java $
002    /*----------------------------------------------------------------------------
003     This file is part of deegree, http://deegree.org/
004     Copyright (C) 2001-2009 by:
005     Department of Geography, University of Bonn
006     and
007     lat/lon GmbH
008    
009     This library is free software; you can redistribute it and/or modify it under
010     the terms of the GNU Lesser General Public License as published by the Free
011     Software Foundation; either version 2.1 of the License, or (at your option)
012     any later version.
013     This library is distributed in the hope that it will be useful, but WITHOUT
014     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
015     FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
016     details.
017     You should have received a copy of the GNU Lesser General Public License
018     along with this library; if not, write to the Free Software Foundation, Inc.,
019     59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
020    
021     Contact information:
022    
023     lat/lon GmbH
024     Aennchenstr. 19, 53177 Bonn
025     Germany
026     http://lat-lon.de/
027    
028     Department of Geography, University of Bonn
029     Prof. Dr. Klaus Greve
030     Postfach 1147, 53001 Bonn
031     Germany
032     http://www.geographie.uni-bonn.de/deegree/
033    
034     e-mail: info@deegree.org
035     ----------------------------------------------------------------------------*/
036    
037    package org.deegree.crs.configuration;
038    
039    import java.util.List;
040    
041    import org.deegree.crs.Identifiable;
042    import org.deegree.crs.coordinatesystems.CoordinateSystem;
043    import org.deegree.crs.exceptions.CRSConfigurationException;
044    import org.deegree.crs.transformations.Transformation;
045    
046    /**
047     * The <code>CRSProvider</code> will allow the support for different crs-definitions formats within the crs package.
048     * All implementation should consider the fact that the deegree-crs package will assume all incoming and outgoing
049     * latitude/longitude coordinates in <u>radians</u>.
050     * 
051     * @author <a href="mailto:bezema@lat-lon.de">Rutger Bezema</a>
052     * 
053     * @author last edited by: $Author: lbuesching $
054     * 
055     * @version $Revision: 27765 $, $Date: 2010-11-04 07:50:32 +0100 (Do, 04 Nov 2010) $
056     * 
057     */
058    
059    public interface CRSProvider {
060    
061        /**
062         * This method is should retrieve a transformation (chain) which transforms coordinates from the given source into
063         * the given target crs. If no such transformation could be found or the implementation does not support inverse
064         * lookup of transformations <code>null<code> should be returned.
065    
066         * @param sourceCRS start of the transformation (chain)
067         * @param targetCRS end point of the transformation (chain).
068         * 
069         * @return the {@link Transformation} Object or <code>null</code> if no such Object was found.
070         * @throws CRSConfigurationException
071         *             if the implementation was confronted by an exception and could not deliver the requested Object. This
072         *             exception should not be thrown no Transformation was found, in this case <code>null</code> should
073         *             be returned.
074         */
075        public Transformation getTransformation( CoordinateSystem sourceCRS, CoordinateSystem targetCRS )
076                                throws CRSConfigurationException;
077    
078        /**
079         * This method is more general than the {@link #getCRSByID(String)}, because it represents a possibility to return
080         * an arbitrary {@link Identifiable} Object from the providers backend.
081         * 
082         * 
083         * @param id
084         *            string representation of the resource to retrieve
085         * @return the {@link Identifiable} Object or <code>null</code> if no such Object was found.
086         * @throws CRSConfigurationException
087         *             if the implementation was confronted by an exception and could not deliver the requested Object. This
088         *             exception should not be thrown if the given id wasn't found, in this case <code>null</code> should
089         *             be returned.
090         */
091        public Identifiable getIdentifiable( String id )
092                                throws CRSConfigurationException;
093    
094        /**
095         * @param id
096         *            string representation of the CoordinateSystem
097         * @return the identified CRS or <code>null</code> if no such CRS was found.
098         * @throws CRSConfigurationException
099         *             if the implementation was confronted by an exception and could not deliver the requested crs. This
100         *             exception should not be thrown if the given id wasn't found, in this case <code>null</code> should
101         *             be returned.
102         */
103        public CoordinateSystem getCRSByID( String id )
104                                throws CRSConfigurationException;
105    
106        /**
107         * This method should be called to see if the provider is able to create all defined crs's, thus verifying the
108         * correctness of the configuration.
109         * 
110         * @return all configured CRSs.
111         * @throws CRSConfigurationException
112         *             if the implementation was confronted by an exception and could not deliver the requested crs. This
113         *             exception should not be thrown if no CoordinateSystems were found, in the latter case an empty List (
114         *             a list with size == 0 ) should be returned.
115         */
116        public List<CoordinateSystem> getAvailableCRSs()
117                                throws CRSConfigurationException;
118    
119        /**
120         * This method should be called if one is only interested in the available identifiers and not in the
121         * coordinatesystems themselves.
122         * 
123         * @return a list of string arrays. Each string array contains the identifiers of one configured CRS.
124         * @throws CRSConfigurationException
125         *             if the implementation was confronted by an exception and could not deliver the requested crs. This
126         *             exception should not be thrown if no CoordinateSystems were found, in the latter case an empty List (
127         *             a list with size == 0 ) should be returned.
128         */
129        public List<String[]> getSortedAvailableCRSIds()
130                                throws CRSConfigurationException;
131    
132        /**
133         * This method should be called if one is only interested in the available identifiers and not in the
134         * coordinatesystems themselves.
135         * 
136         * @return the identifiers of all configured CRSs.
137         * @throws CRSConfigurationException
138         *             if the implementation was confronted by an exception and could not deliver the requested crs. This
139         *             exception should not be thrown if no CoordinateSystems were found, in the latter case an empty List (
140         *             a list with size == 0 ) should be returned.
141         */
142        public List<String> getAvailableCRSIds()
143                                throws CRSConfigurationException;
144    
145        /**
146         * Exports the crs to the implemented format. Try calling {@link #canExport()} before executing this method.
147         * 
148         * @param sb
149         *            the StringBuilder which will contain the exported version of the given crs.
150         * @param crsToExport
151         *            the CoordinateSystems to export.
152         * @see #canExport()
153         */
154        public void export( StringBuilder sb, List<CoordinateSystem> crsToExport );
155    
156        /**
157         * @return true if this provider can export a given crs.
158         */
159        public boolean canExport();
160    
161        /**
162         * 
163         */
164        public void clearCache();
165    
166        /**
167         * @return a list of all available transformations
168         */
169        public List<Transformation> getTransformations();
170    
171    }