    001    //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/branches/2.4_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: 23198 $, $Date: 2010-03-23 08:40:31 +0100 (Di, 23. Mär 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    }