*    GeoTools - The Open Source Java GIS Toolkit

*    http://geotools.org

*

*    (C) 2003-2008, Open Source Geospatial Foundation (OSGeo)

*   

*    This library is free software; you can redistribute it and/or

*    modify it under the terms of the GNU Lesser General Public

*    License as published by the Free Software Foundation;

*    version 2.1 of the License.

*

*    This library is distributed in the hope that it will be useful,

*    but WITHOUT ANY WARRANTY; without even the implied warranty of

*    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

*    Lesser General Public License for more details.

*/

* Utility functions for use with GeoTools with data classes.

* <p>

* These methods fall into several categories:

* <p>

* Conversion between common data structures.

* <ul>

* <li>{@link #collection} methods: creating/converting a {@link SimpleFeatureCollection} from a range of input.</li>

* <li>{@link #simple} methods: adapting from generic Feature use to SimpleFeature. Used to convert to SimpleFeature,

* SimpleFeatureCollection,SimpleFeatureSource</li>

* <li>{@link #list} to quickly copy features into a memory based list</li>

* <li>{@link #reader} methods to convert to FeatureReader</li>

* <li>{@link #expression} setup a FeatureSource wrapper around the provided data</li>

* </ul>

* </p>

* <p>

* SimpleFeatureType and SimpleFeature encoding/decoding from String as used by the PropertyDataStore tutorials.

* <ul>

* <li>{@link #createType} methods: to create a SimpleFeatureType from a one line text string</li>

* <li>{@link #encodeType}: text string representation of a SimpleFeaturerType</li>

* <li>{@link #createFeature}: create a SimpleFeature from a one line text String</li>

* <li>{@link #encodeFeature}: encode a feature as a single line text string</li>

* </ul>

* </p>

* <p>

* Working with SimpleFeatureType (this class is immutable so we always have to make a modified copy):

* <ul>

* <li>{@link #createSubType(SimpleFeatureType, String[])} methods return a modified copy of an origional feature type. Used to cut down an exsiting

* feature type to reflect only the attributes requested when using {@link SimpleFeatureSource#getFeatures(Filter)}.</li>

* <li>{@link #compare} and {@link #isMatch(AttributeDescriptor, AttributeDescriptor)} are used to check for types compatible with

* {@link #createSubType} used to verify that feature values can be copied across</li>

* </ul>

* </p>

* <p>

* Manipulating individual features and data values:

* <ul>

* <li>{@link #reType} generates a cut down version of an original feature in the same manners as {@link #createSubType}</li>

* <li>{@link #template} and {@link #defaultValue} methods which uses {@link AttributeDescriptor#getDefaultValue()} when creating new empty features</li>

* <li>{@link #duplicate(Object)} used for deep copy of feature data</li>

* <li>

* </ul>

* </p>

* And a grab bag of helpful utility methods for those implementing a DataStore:

* <ul>

* <li>{@link #urlToFile(URL)} and {@link #fileToURL(File)} and {@link #getParentUrl(URL)} used to work with files across platforms</li>

* <li>{@link #includeFilters} and {@link #excludeFilters} work as a compound {@link FileFilter} making {@link File#listFiles} easier to use</li>

* <li>{@link #propertyNames}, {@link #fidSet}, {@link #attributeNames} methods are used to double check a provided query and ensure

* it can be correctly handed.</li>

* </li>{@link #sortComparator}, {@link #resolvePropertyNames} and {@link #mixQueries} are used to prep a {@link Query} prior to use</li>

* </ul>

*

* @author Jody Garnett, Refractions Research

*

*

* @source $URL$ http://svn.osgeo.org/geotools/trunk/modules/library/main/src/main/java/org/geotools/ data/DataUtilities.java $

*/

    /** Typemap used by {@link #createType(String, String)} methods */

    static Map<String, Class> typeMap = new HashMap<String, Class>();

   

    /** Reverse type map used by {@link #encodeType(FeatureType)} */

    static Map<Class, String> typeEncode = new HashMap<Class, String>();

    static FilterFactory2 ff = CommonFactoryFinder.getFilterFactory2();

   

    static final boolean IS_WINDOWS_OS;

    static {

        typeEncode.put(String.class, "String");

        typeMap.put("String", String.class);

        typeMap.put("string", String.class);

        typeMap.put("\"\"", String.class);

        typeEncode.put(Integer.class, "Integer");

        typeMap.put("Integer", Integer.class);

        typeMap.put("int", Integer.class);

        typeMap.put("0", Integer.class);

        typeEncode.put(Double.class, "Double");

        typeMap.put("Double", Double.class);

        typeMap.put("double", Double.class);

        typeMap.put("0.0", Double.class);

        typeEncode.put(Float.class, "Float");

        typeMap.put("Float", Float.class);

        typeMap.put("float", Float.class);

        typeMap.put("0.0f", Float.class);

        typeEncode.put(Boolean.class, "Boolean");

        typeMap.put("Boolean", Boolean.class);

        typeMap.put("true", Boolean.class);

        typeMap.put("false", Boolean.class);

        typeEncode.put(UUID.class, "UUID");

        typeMap.put("UUID", UUID.class);

        typeEncode.put(Geometry.class, "Geometry");

        typeMap.put("Geometry", Geometry.class);

        typeEncode.put(Point.class, "Point");

        typeMap.put("Point", Point.class);

        typeEncode.put(LineString.class, "LineString");

        typeMap.put("LineString", LineString.class);

        typeEncode.put(Polygon.class, "Polygon");

        typeMap.put("Polygon", Polygon.class);

        typeEncode.put(MultiPoint.class, "MultiPoint");

        typeMap.put("MultiPoint", MultiPoint.class);

        typeEncode.put(MultiLineString.class, "MultiLineString");

        typeMap.put("MultiLineString", MultiLineString.class);

        typeEncode.put(MultiPolygon.class, "MultiPolygon");

        typeMap.put("MultiPolygon", MultiPolygon.class);

        typeEncode.put(GeometryCollection.class, "GeometryCollection");

        typeMap.put("GeometryCollection", GeometryCollection.class);

        typeEncode.put(Date.class, "Date");

        typeMap.put("Date", Date.class);

       

        // check if we are running on windows

        String os = System.getProperty("os.name");

        IS_WINDOWS_OS = os.toUpperCase().contains("WINDOWS");

    }

   

    /**

     * Retrieve the attributeNames defined by the featureType

     *

     * @param featureType

     * @return array of simple attribute names

     */

    public static String[] attributeNames(SimpleFeatureType featureType) {

        String[] names = new String[featureType.getAttributeCount()];

        final int count = featureType.getAttributeCount();

        for (int i = 0; i < count; i++) {

            names[i] = featureType.getDescriptor(i).getLocalName();

        }

        return names;

    }

    /**

     * A replacement for File.toURI().toURL().

     * <p>

     * The handling of file.toURL() is broken; the handling of file.toURI().toURL() is known to be

     * broken on a few platforms like mac. We have the urlToFile( URL ) method that is able to

     * untangle both these problems and we use it in the geotools library.

     * <p>

     * However occasionally we need to pick up a file and hand it to a third party library like EMF;

     * this method performs a couple of sanity checks which we can use to prepare a good URL

     * reference to a file in these situtations.

     *

     * @param file

     * @return URL

     */

    public static URL fileToURL(File file) {

        try {

            URL url = file.toURI().toURL();

            String string = url.toExternalForm();

            if (string.contains("+")) {

                // this represents an invalid URL created using either

                // file.toURL(); or

                // file.toURI().toURL() on a specific version of Java 5 on Mac

                string = string.replace("+", "%2B");

            }

            if (string.contains(" ")) {

                // this represents an invalid URL created using either

                // file.toURL(); or

                // file.toURI().toURL() on a specific version of Java 5 on Mac

                string = string.replace(" ", "%20");

            }

            return new URL(string);

        } catch (MalformedURLException e) {

            return null;

        }

    }

    /**

     * Takes a URL and converts it to a File. The attempts to deal with Windows UNC format specific

     * problems, specifically files located on network shares and different drives.

     *

     * If the URL.getAuthority() returns null or is empty, then only the url's path property is used

     * to construct the file. Otherwise, the authority is prefixed before the path.

     *

     * It is assumed that url.getProtocol returns "file".

     *

     * Authority is the drive or network share the file is located on. Such as "C:", "E:",

     * "\\fooServer"

     *

     * @param url

     *            a URL object that uses protocol "file"

     * @return a File that corresponds to the URL's location

     */

    public static File urlToFile(URL url) {

        if (!"file".equals(url.getProtocol())) {

            return null; // not a File URL

        }

        String string = url.toExternalForm();

        if (string.contains("+")) {

            // this represents an invalid URL created using either

            // file.toURL(); or

            // file.toURI().toURL() on a specific version of Java 5 on Mac

            string = string.replace("+", "%2B");

        }

        try {

            string = URLDecoder.decode(string, "UTF-8");

        } catch (UnsupportedEncodingException e) {

            throw new RuntimeException("Could not decode the URL to UTF-8 format", e);

        }

        String path3;

        String simplePrefix = "file:/";

        String standardPrefix = "file://";

        if (IS_WINDOWS_OS && string.startsWith(standardPrefix)) {

            // win32: host/share reference

            path3 = string.substring(standardPrefix.length() - 2);

        } else if (string.startsWith(standardPrefix)) {

            path3 = string.substring(standardPrefix.length());

        } else if (string.startsWith(simplePrefix)) {

            path3 = string.substring(simplePrefix.length() - 1);

        } else {

            String auth = url.getAuthority();

            String path2 = url.getPath().replace("%20", " ");

            if (auth != null && !auth.equals("")) {

                path3 = "//" + auth + path2;

            } else {

                path3 = path2;

            }

        }

        return new File(path3);

    }

    /**

     * Traverses the filter and returns any encountered property names.

     * <p>

     * The feature type is supplied as contexts used to lookup expressions in cases where the

     * attributeName does not match the actual name of the type.

     * </p>

     */

    public static String[] attributeNames(Filter filter, final SimpleFeatureType featureType) {

        if (filter == null) {

            return new String[0];

        }

        FilterAttributeExtractor attExtractor = new FilterAttributeExtractor(featureType);

        filter.accept(attExtractor, null);

        String[] attributeNames = attExtractor.getAttributeNames();

        return attributeNames;

    }

    /**

     * Traverses the filter and returns any encountered property names.

     * <p>

     * The feature type is supplied as contexts used to lookup expressions in cases where the

     * attributeName does not match the actual name of the type.

     * </p>

     */

    public static Set<PropertyName> propertyNames(Filter filter, final SimpleFeatureType featureType) {

        if (filter == null) {

            return Collections.emptySet();

        }

        FilterAttributeExtractor attExtractor = new FilterAttributeExtractor(featureType);

        filter.accept(attExtractor, null);

        Set<PropertyName> propertyNames = attExtractor.getPropertyNameSet();

        return propertyNames;

    }

    /**

     * Traverses the filter and returns any encountered property names.

     */

    public static String[] attributeNames(Filter filter) {

        return attributeNames(filter, null);

    }

    /**

     * Traverses the filter and returns any encountered property names.

     */

    public static Set<PropertyName> propertyNames(Filter filter) {

        return propertyNames(filter, null);

    }

    /**

     * Traverses the expression and returns any encountered property names.

     * <p>

     * The feature type is supplied as contexts used to lookup expressions in cases where the

     * attributeName does not match the actual name of the type.

     * </p>

     */

    public static String[] attributeNames(Expression expression, final SimpleFeatureType featureType) {

        if (expression == null) {

            return new String[0];

        }

        FilterAttributeExtractor attExtractor = new FilterAttributeExtractor(featureType);

        expression.accept(attExtractor, null);

        String[] attributeNames = attExtractor.getAttributeNames();

        return attributeNames;

    }

    /**

     * Traverses the expression and returns any encountered property names.

     * <p>

     * The feature type is supplied as contexts used to lookup expressions in cases where the

     * attributeName does not match the actual name of the type.

     * </p>

     */

    public static Set<PropertyName> propertyNames(Expression expression,

            final SimpleFeatureType featureType) {

        if (expression == null) {

            return Collections.emptySet();

        }

        FilterAttributeExtractor attExtractor = new FilterAttributeExtractor(featureType);

        expression.accept(attExtractor, null);

        Set<PropertyName> propertyNames = attExtractor.getPropertyNameSet();

        return propertyNames;

    }

    /**

     * Traverses the expression and returns any encountered property names.

     */

    public static String[] attributeNames(Expression expression) {

        return attributeNames(expression, null);

    }

    /**

     * Traverses the expression and returns any encountered property names.

     */

    public static Set<PropertyName> propertyNames(Expression expression) {

        return propertyNames(expression, null);

    }

    /**

     * Compare attribute coverage between two feature types (allowing the identification of subTypes).

     * <p>

     * The comparison results in a number with the following meaning:

     * </p>

     *

     * <ul>

     * <li>

     * 1: if typeA is a sub type/reorder/renamespace of typeB</li>

     * <li>

     * 0: if typeA and typeB are the same type</li>

     * <li>

     * -1: if typeA is not subtype of typeB</li>

     * </ul>

     *

     * <p>

     * Comparison is based on {@link AttributeDescriptor} - the {@link #isMatch(AttributeDescriptor, AttributeDescriptor)}

     * method is used to quickly confirm that the local name and java binding are compatible.

     * </p>

     *

     * <p>

     * Namespace is not considered in this opperations. You may still need to reType to get the

     * correct namesapce, or reorder.

     * </p>

     * <p>

     * Please note this method will not result in a stable sort if used in a {@link Comparator}

     * as -1 is used to indicate incompatiblity (rather than simply "before").

     *

     * @param typeA  FeatureType beind compared

     * @param typeB FeatureType being compared against

     */

    public static int compare(SimpleFeatureType typeA, SimpleFeatureType typeB) {

        if (typeA == typeB) {

            return 0;

        }

        if (typeA == null) {

            return -1;

        }

        if (typeB == null) {

            return -1;

        }

        int countA = typeA.getAttributeCount();

        int countB = typeB.getAttributeCount();

        if (countA > countB) {

            return -1;

        }

        // may still be the same featureType (Perhaps they differ on namespace?)

        AttributeDescriptor a;

        int match = 0;

        for (int i = 0; i < countA; i++) {

            a = typeA.getDescriptor(i);

            if (isMatch(a, typeB.getDescriptor(i))) {

                match++;

            } else if (isMatch(a, typeB.getDescriptor(a.getLocalName()))) {