/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 *
 *    (C) 2005-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.
 */
package org.geotools.referencing.factory;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.*;
import java.util.logging.Level;
import java.util.logging.LogRecord;
import javax.measure.unit.Unit;
import javax.measure.quantity.Angle;
import javax.measure.quantity.Length;

import org.opengis.metadata.Identifier;
import org.opengis.referencing.datum.*;
import org.opengis.referencing.IdentifiedObject;
import org.opengis.referencing.FactoryException;
import org.opengis.util.GenericName;
import org.opengis.util.ScopedName;

import org.geotools.util.LocalName;
import org.geotools.util.NameFactory;
import org.geotools.resources.XArray;
import org.geotools.resources.i18n.Loggings;
import org.geotools.resources.i18n.LoggingKeys;
import org.geotools.referencing.ReferencingFactoryFinder;


/**
 * A datum factory that add {@linkplain IdentifiedObject#getAlias aliases} to a datum name before to
 * delegates the {@linkplain org.geotools.referencing.datum.AbstractDatum#AbstractDatum(Map) datum
 * creation} to an other factory. Aliases are especially important for {@linkplain Datum datum}
 * since their {@linkplain IdentifiedObject#getName name} are often the only way to differentiate
 * them. Two datum with different names are considered incompatible, unless some datum shift method
 * are specified (e.g. {@linkplain org.geotools.referencing.datum.BursaWolfParameters Bursa-Wolf
 * parameters}). Unfortunatly, different softwares often use different names for the same datum,
 * which result in {@link org.opengis.referencing.operation.OperationNotFoundException} when
 * attempting to convert coordinates from one {@linkplain CoordinateReferenceSystem coordinate
 * reference system} to an other one. For example "<cite>Nouvelle Triangulation Française (Paris)</cite>"
 * and "<cite>NTF (Paris meridian)</cite>" are actually the same datum. This {@code DatumAliases}
 * class provides a way to handle that.
 * <p>
 * {@code DatumAliases} is a class that determines if a datum name is in our list of aliases and
 * constructs a value for the {@linkplain IdentifiedObject#ALIAS_KEY aliases property} (as
 * {@linkplain GenericName generic names}) for a name. The default implementation is backed by
 * the text file "{@code DatumAliasesTable.txt}". The first line in this text file must be the
 * authority names. All other lines are the aliases.
 * <p>
 * Since {@code DatumAliases} is a datum factory, any {@linkplain AuthorityFactory authority
 * factory} or any {@linkplain org.geotools.referencing.wkt.Parser WKT parser} using this
 * factory will takes advantage of the aliases table.
 *
 * @since 2.1
 *
 * @source $URL$
 * @version $Id$
 * @author Rueben Schulz
 * @author Martin Desruisseaux
 *
 * @todo Invokes {@link #freeUnused} automatically after some amount of time, in order to release
 *       memory for unusued aliases. A timer should be set in {@code reload()} method.
 *
 * @see <A HREF="http://gdal.velocet.ca/~warmerda/wktproblems.html">WKT problems</A>
 */
public class DatumAliases extends ReferencingFactory implements DatumFactory {
    /**
     * The default file for alias table.
     */
    private static final String ALIAS_TABLE = "DatumAliasesTable.txt";

    /**
     * The column separators in the file to parse.
     */
    private static final String SEPARATORS = ";";

    /**
     * Array used as a marker for alias that has been discarted because never used.
     * This array may appears in {@link #aliasMap} values.
     *
     * @see #freeUnused
     */
    private static final Object[] NEED_LOADING = new Object[0];

    /**
     * The URL of the alias table. This file is read by {@link #reload} when first needed.
     */
    private final URL aliasURL;

    /**
     * A map of our datum aliases. Keys are alias names in lower-case, and values are
     * either {@code String[]} or {@code GenericName[]}. In order to reduce the amount
     * of objects created, all values are initially {@code String[]} objects. They are
     * converted to {@code GenericName[]} only when first needed.
     */
    private final Map<String,Object[]> aliasMap = new HashMap<String,Object[]>();

    /**
     * The authorities. This is the first line in the alias table.
     * This array is constructed by {@link #reload} when first needed.
     */
    private LocalName[] authorities;

    /**
     * The underlying datum factory. If {@code null}, a default factory will be fetch from
     * {@link ReferencingFactoryFinder} when first needed. A default value can't be set at
     * construction time, since all factories may not be registered at this time.
     */
    private DatumFactory factory;

    /**
     * Constructs a new datum factory with the default backing factory and alias table.
     */
    public DatumAliases() {
        // Uses a slightly higher priority than the default factory, in order
        // to get WKT parser and authorities factories to use the aliases table.
        super(NORMAL_PRIORITY + 10);
        aliasURL = DatumAliases.class.getResource(ALIAS_TABLE);
        if (aliasURL == null) {
            throw new NoSuchElementException(ALIAS_TABLE);
        }
    }

    /**
     * Constructs a new datum factory using the specified factory and the default alias table.
     *
     * @param factory The factory to use for datum creation.
     */
    public DatumAliases(final DatumFactory factory) {
        this();
        this.factory = factory;
        ensureNonNull("factory", factory);
    }

    /**
     * Constructs a new datum factory which delegates its work to the specified factory.
     * The aliases table is read from the specified URL. The fist line in this file most
     * be the authority names. All other names are aliases.
     *
     * @param factory  The factory to use for datum creation.
     * @param aliasURL The url to the alias table.
     */
    public DatumAliases(final DatumFactory factory, final URL aliasURL) {
        super(NORMAL_PRIORITY + 10);
        this.factory  = factory;
        this.aliasURL = aliasURL;
        ensureNonNull("factory",  factory );
        ensureNonNull("aliasURL", aliasURL);
    }

    /**
     * Returns the backing datum factory. If no factory were explicitly specified
     * by the user, selects the first datum factory other than {@code this}.
     * <p>
     * <strong>Note:</strong> We can't invoke this method in the constructor, because the
     * constructor is typically invoked during {@code FactoryFinder.scanForPlugins()} execution.
     * {@code scanForPlugins} is looking for {@link DatumFactory} instances, it has not finished
     * to search them, and invoking this method in the constructor would prematurely ask an other
     * {@link DatumFactory} instance while the list is incomplete. Instead, we will invoke this
     * method when the first {@code createXXX} method is invoked, which typically occurs after
     * all factories have been initialized.
     *
     * @return The backing datum factory.
     * @throws NoSuchElementException if there is no such factory.
     */
    private DatumFactory getDatumFactory() throws NoSuchElementException {
        assert Thread.holdsLock(this);
        if (factory == null) {
            DatumFactory candidate;
            final Iterator<DatumFactory> it = ReferencingFactoryFinder.getDatumFactories(null).iterator();
            do candidate = it.next();
            while (candidate == this);
            factory = candidate;
        }
        return factory;
    }

    /**
     * Returns a caseless version of the specified key, to be stored in the map.
     */
    private static String toCaseless(final String key) {
        return key.replace('_', ' ').trim().toLowerCase();
    }

    /**
     * Read the next line from the specified input stream, skipping all blank
     * and comment lines. Returns {@code null} on end of stream.
     */
    private static String readLine(final BufferedReader in) throws IOException {
        String line;
        do line = in.readLine();
        while (line!=null && ((line=line.trim()).length()==0 || line.charAt(0)=='#'));
        return line;
    }

    /**
     * Read again the "{@code DatumAliasesTable.txt}" file into {@link #aliasMap}.
     * This method may be invoked more than once in order to reload entries that
     * have been discarted by {@link #freeUnused}. This method assumes that the
     * file content didn't change between two calls.
     *
     * @throws IOException if the loading failed.
     */
    private void reload() throws IOException {
        assert Thread.holdsLock(this);
        final LogRecord record = Loggings.format(Level.FINE,
                LoggingKeys.LOADING_DATUM_ALIASES_$1, aliasURL);
        record.setLoggerName(LOGGER.getName());
        LOGGER.log(record);
        final BufferedReader in = new BufferedReader(new InputStreamReader(aliasURL.openStream()));
        /*
         * Parses the title line. This line contains authority names as column titles.
         * The authority names will be used as the scope for each identifiers to be
         * created.
         */
        String line = readLine(in);
        if (line != null) {
            final List<Object> elements = new ArrayList<Object>();
            StringTokenizer st = new StringTokenizer(line, SEPARATORS);
            while (st.hasMoreTokens()) {
                final String name = st.nextToken().trim();
                elements.add(name.length()!=0 ? new LocalName(name) : null);
            }
            authorities = elements.toArray(new LocalName[elements.size()]);
            final Map<String,String> canonical = new HashMap<String,String>();
            /*
             * Parses all aliases. They are stored as arrays of strings for now, but will be
             * converted to array of generic names by {@link #getAliases} when first needed.
             * If the alias belong to an authority (which should be true in most cases), a
             * scoped name will be created at this time.
             */
            while ((line=readLine(in)) != null) {
                elements .clear();
                canonical.clear();
                st = new StringTokenizer(line, SEPARATORS);
                while (st.hasMoreTokens()) {
                    String alias = st.nextToken().trim();
                    if (alias.length() != 0) {
                        final String previous = canonical.put(alias, alias);
                        if (previous != null) {
                            canonical.put(previous, previous);
                            alias = previous;
                        }
                    } else {
                        alias = null;
                    }
                    elements.add(alias);
                }
                // Trim trailing null values only (we must keep other null values).
                for (int i=elements.size(); --i>=0;) {
                    if (elements.get(i) != null) break;
                    elements.remove(i);
                }
                if (!elements.isEmpty()) {
                    /*
                     * Copies the aliases array in the aliases map for all local names. If a
                     * previous value is found as an array of GenericName objects, those generic
                     * names are conserved in the map (instead of the string values parsed above)
                     * in order to avoid constructing them again when they will be needed.
                     */
                    final String[] names = elements.toArray(new String[elements.size()]);
                    for (int i=0; i<names.length; i++) {
                        final String name = names[i];
                        final String key  = toCaseless(name);
                        final Object[] previous = aliasMap.put(key, names);
                        if (previous!=null && previous!=NEED_LOADING) {
                            if (previous instanceof GenericName[]) {
                                aliasMap.put(key, previous);
                            } else if (!Arrays.equals(previous, names)) {
                                // TODO: localize
                                LOGGER.warning("Inconsistent aliases for datum \""+name+"\".");
                            }
                        }
                    }
                }
            }
        }
        in.close();
    }

    /**
     * Logs an {@link IOException}.
     */
    private void log(final IOException exception) {
        LogRecord record = Loggings.format(Level.WARNING, LoggingKeys.CANT_READ_FILE_$1, aliasURL);
        record.setSourceClassName(DatumAliases.class.getName());
        record.setSourceMethodName("reload");
        record.setThrown(exception);
        record.setLoggerName(LOGGER.getName());
        LOGGER.log(record);
    }

    /**
     * Returns the aliases, as a set of {@link GenericName}, for the given name.
     * This method returns an internal array; do not modify the returned value.
     *
     * @param name Datum alias name to lookup.
     * @return A set of datum aliases as {@link GenericName} objects for the given name,
     *         or {@code null} if the name is not in our list of aliases.
     *
     * @see #addAliases
     * @see #reload
     */
    private GenericName[] getAliases(String name) {
        assert Thread.holdsLock(this);
        if (aliasMap.isEmpty()) try {
            reload();
        } catch (IOException exception) {
            log(exception);
            // Continue in case the requested alias has been read before the failure occured.
        }
        /*
         * Gets the aliases for the specified name.  If an entry exists for this name with a null
         * value, this means that 'freeUnused()' has been invoked previously. Reload the file and
         * try again since the requested name may be one of the set of discarted aliases.
         */
        name = toCaseless(name);
        Object[] aliases = aliasMap.get(name);
        if (aliases == null) {
            // Unknow name. We are done.
            return null;
        }
        if (aliases == NEED_LOADING) {
            // Known name, but the list of alias has been previously
            // discarted because never used. Reload the file.
            try {
                reload();
            } catch (IOException exception) {
                log(exception);
                // Continue in case the requested alias has been read before the failure occured.
            }
            aliases = aliasMap.get(name);
            if (aliases == NEED_LOADING) {
                // Should never happen, unless reloading failed or some lines have
                // been deleted in the file since last time the file has been loaded.
                return null;
            }
        }
        if (aliases instanceof GenericName[]) {
            return (GenericName[]) aliases;
        }
        /*
         * Aliases has been found, but available as an array of strings only. This means
         * that those aliases have never been requested before. Transforms the array of
         * strings into an array of generic names. The new array replaces the old one for
         * all aliases enumerated in the array (not just the requested one).
         */
        int count = 0;
        GenericName[] names = new GenericName[aliases.length];
        for (int i=0; i<aliases.length; i++) {
            final CharSequence alias = (CharSequence) aliases[i];
            if (alias != null) {
                if (count < authorities.length) {
                    final LocalName authority = authorities[count];
                    if (authority != null) {
                        names[count++] = new org.geotools.util.ScopedName(authority, alias);
                        continue;
                    }
                }
                names[count++] = new LocalName(alias);
            }
        }
        names = XArray.resize(names, count);
        for (int i=0; i<names.length; i++) {
            final String alias = names[i].tip().toString();
            final Object[] previous = aliasMap.put(toCaseless(alias), names);
            assert previous==names || Arrays.equals(aliases, previous) : alias;
        }
        return names;
    }

    /**
     * Completes the given map of properties. This method expects a map of properties to
     * be given to {@link AbstractDatum#AbstractDatum(Map)} constructor. The name is fetch
     * from the {@link IdentifiedObject#NAME_KEY NAME_KEY}.
     * The {@link AbstractIdentifiedObject#ALIAS_KEY ALIAS_KEY} is
     * completed with the aliases know to this factory.
     *
     * @param  properties The set of properties to complete.
     * @return The completed properties, or {@code properties} if no change were done.
     *
     * @see #getAliases
     */
    private Map<String,?> addAliases(Map<String,?> properties) {
        ensureNonNull("properties", properties);
        Object value = properties.get(IdentifiedObject.NAME_KEY);
        ensureNonNull("name", value);
        final String name;
        if (value instanceof Identifier) {
            name = ((Identifier) value).getCode();
        } else {
            name = value.toString();
        }
        GenericName[] aliases = getAliases(name);
        if (aliases != null) {
            /*
             * Aliases have been found. Before to add them to the properties map, overrides them
             * with the aliases already provided by the users, if any. The 'merged' map is the
             * union of aliases know to this factory and aliases provided by the user. User's
             * aliases will be added first, for preserving the user's order (the LinkedHashMap
             * acts as a FIFO queue).
             */
            int count = aliases.length;
            value = properties.get(IdentifiedObject.ALIAS_KEY);
            if (value != null) {
                final Map<String,GenericName> merged = new LinkedHashMap<String,GenericName>();
                putAll(NameFactory.toArray(value), merged);
                count -= putAll(aliases, merged);
                final Collection<GenericName> c = merged.values();
                aliases = c.toArray(new GenericName[c.size()]);
            }
            /*
             * Now set the aliases. This replacement will not be performed if
             * all our aliases were replaced by user's aliases (count <= 0).
             */
            if (count > 0) {
                final Map<String,Object> copy = new HashMap<String,Object>(properties);
                copy.put(IdentifiedObject.ALIAS_KEY, aliases);
                properties = copy;
            }
        }
        return properties;
    }

    /**
     * Puts all elements in the {@code names} array into the specified map. Order matter, since the
     * first element in the array should be the first element returned by the map if the map is
     * actually an instance of {@link LinkedHashMap}. This method returns the number of elements
     * ignored.
     */
    private static final int putAll(final GenericName[] names, final Map<String,GenericName> map) {
        int ignored = 0;
        for (int i=0; i<names.length; i++) {
            final GenericName   name = names[i];
            final GenericName scoped = name.toFullyQualifiedName();
            final String         key = toCaseless(scoped.toString());
            final GenericName    old = map.put(key, name);
            if (old instanceof ScopedName) {
                map.put(key, old); // Preserves the user value, except if it was unscoped.
                ignored++;
            }
        }
        return ignored;
    }

    /**
     * Creates an engineering datum.
     *
     * @param  properties Name and other properties to give to the new object.
     * @throws FactoryException if the object creation failed.
     */
    public synchronized EngineeringDatum createEngineeringDatum(final Map<String,?> properties)
            throws FactoryException
    {
        return getDatumFactory().createEngineeringDatum(addAliases(properties));
    }

    /**
     * Creates geodetic datum from ellipsoid and (optionaly) Bursa-Wolf parameters.
     *
     * @param  properties Name and other properties to give to the new object.
     * @param  ellipsoid Ellipsoid to use in new geodetic datum.
     * @param  primeMeridian Prime meridian to use in new geodetic datum.
     * @throws FactoryException if the object creation failed.
     */
    public synchronized GeodeticDatum createGeodeticDatum(final Map<String,?> properties,
            final Ellipsoid ellipsoid, final PrimeMeridian primeMeridian) throws FactoryException
    {
        return getDatumFactory().createGeodeticDatum(addAliases(properties),
                                                     ellipsoid, primeMeridian);
    }

    /**
     * Creates an image datum.
     *
     * @param  properties Name and other properties to give to the new object.
     * @param  pixelInCell Specification of the way the image grid is associated
     *         with the image data attributes.
     * @throws FactoryException if the object creation failed.
     */
    public synchronized ImageDatum createImageDatum(final Map<String,?> properties,
            final PixelInCell pixelInCell) throws FactoryException
    {
        return getDatumFactory().createImageDatum(addAliases(properties), pixelInCell);
    }

    /**
     * Creates a temporal datum from an enumerated type value.
     *
     * @param  properties Name and other properties to give to the new object.
     * @param  origin The date and time origin of this temporal datum.
     * @throws FactoryException if the object creation failed.
     */
    public synchronized TemporalDatum createTemporalDatum(final Map<String,?> properties,
            final Date origin) throws FactoryException
    {
        return getDatumFactory().createTemporalDatum(addAliases(properties), origin);
    }

    /**
     * Creates a vertical datum from an enumerated type value.
     *
     * @param  properties Name and other properties to give to the new object.
     * @param  type The type of this vertical datum (often “geoidal”).
     * @throws FactoryException if the object creation failed.
     */
    public synchronized VerticalDatum createVerticalDatum(final Map<String,?> properties,
            final VerticalDatumType type) throws FactoryException
    {
        return getDatumFactory().createVerticalDatum(addAliases(properties), type);
    }

    /**
     * Creates an ellipsoid from radius values.
     *
     * @param  properties Name and other properties to give to the new object.
     * @param  semiMajorAxis Equatorial radius in supplied linear units.
     * @param  semiMinorAxis Polar radius in supplied linear units.
     * @param  unit Linear units of ellipsoid axes.
     * @throws FactoryException if the object creation failed.
     */
    public synchronized Ellipsoid createEllipsoid(final Map<String,?> properties,
            final double semiMajorAxis, final double semiMinorAxis, final Unit<Length> unit)
            throws FactoryException
    {
        return getDatumFactory().createEllipsoid(addAliases(properties),
                semiMajorAxis, semiMinorAxis, unit);
    }

    /**
     * Creates an ellipsoid from an major radius, and inverse flattening.
     *
     * @param  properties Name and other properties to give to the new object.
     * @param  semiMajorAxis Equatorial radius in supplied linear units.
     * @param  inverseFlattening Eccentricity of ellipsoid.
     * @param  unit Linear units of major axis.
     * @throws FactoryException if the object creation failed.
     */
    public synchronized Ellipsoid createFlattenedSphere(final Map<String,?> properties,
            final double semiMajorAxis, final double inverseFlattening, final Unit<Length> unit)
            throws FactoryException
    {
        return getDatumFactory().createFlattenedSphere(addAliases(properties),
                semiMajorAxis, inverseFlattening, unit);
    }

    /**
     * Creates a prime meridian, relative to Greenwich.
     *
     * @param  properties Name and other properties to give to the new object.
     * @param  longitude Longitude of prime meridian in supplied angular units East of Greenwich.
     * @param  angularUnit Angular units of longitude.
     * @throws FactoryException if the object creation failed.
     */
    public synchronized PrimeMeridian createPrimeMeridian(final Map<String,?> properties,
            final double longitude, final Unit<Angle> angularUnit) throws FactoryException
    {
        return getDatumFactory().createPrimeMeridian(addAliases(properties),
                longitude, angularUnit);
    }

    /**
     * Free all aliases that have been unused up to date. If one of those alias is needed at a
     * later time, the aliases table will be reloaded.
     */
    public synchronized void freeUnused() {
        if (aliasMap != null) {
            for (final Map.Entry<String,Object[]> entry : aliasMap.entrySet()) {
                final Object[] value = entry.getValue();
                if (!(value instanceof GenericName[])) {
                    entry.setValue(NEED_LOADING);
                }
            }
        }
    }
}