/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.sis.referencing.factory;

import java.util.Set;
import java.util.Map;
import java.util.List;
import java.util.Deque;
import java.util.Iterator;
import java.util.ArrayList;
import java.util.LinkedList;
import java.util.WeakHashMap;
import java.util.IdentityHashMap;
import java.util.concurrent.Callable;
import java.util.concurrent.TimeUnit;
import java.util.logging.LogRecord;
import java.util.logging.Level;
import java.lang.ref.WeakReference;
import java.lang.ref.PhantomReference;
import java.io.PrintWriter;
import java.lang.reflect.Method;
import javax.measure.Unit;
import org.opengis.referencing.cs.*;
import org.opengis.referencing.crs.*;
import org.opengis.referencing.datum.*;
import org.opengis.referencing.operation.*;
import org.opengis.referencing.IdentifiedObject;
import org.opengis.referencing.NoSuchAuthorityCodeException;
import org.opengis.util.FactoryException;
import org.opengis.util.InternationalString;
import org.opengis.metadata.extent.Extent;
import org.opengis.metadata.citation.Citation;
import org.opengis.parameter.ParameterDescriptor;
import org.apache.sis.util.Classes;
import org.apache.sis.util.Debug;
import org.apache.sis.util.Disposable;
import org.apache.sis.util.ArgumentChecks;
import org.apache.sis.util.logging.Logging;
import org.apache.sis.util.collection.Cache;
import org.apache.sis.internal.simple.SimpleCitation;
import org.apache.sis.internal.system.ReferenceQueueConsumer;
import org.apache.sis.internal.system.DelayedExecutor;
import org.apache.sis.internal.system.DelayedRunnable;
import org.apache.sis.internal.system.Shutdown;
import org.apache.sis.internal.system.Loggers;
import org.apache.sis.internal.util.CollectionsExt;
import org.apache.sis.internal.util.StandardDateFormat;
import org.apache.sis.util.logging.PerformanceLevel;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.resources.Messages;


/**
 * A concurrent authority factory that caches all objects created by another factory.
 * All {@code createFoo(String)} methods first check if a previously created object exists for the given code.
 * If such object exists, it is returned. Otherwise, the object creation is delegated to another factory given
 * by {@link #newDataAccess()} and the result is cached in this factory.
 *
 * <p>{@code ConcurrentAuthorityFactory} delays the call to {@code newDataAccess()} until first needed,
 * and {@linkplain AutoCloseable#close() closes} the factory used as a <cite>Data Access Object</cite>
 * (DAO) after some timeout. This approach allows to establish a connection to a database (for example)
 * and keep it only for a relatively short amount of time.</p>
 *
 * <div class="section">Caching strategy</div>
 * Objects are cached by strong references, up to the amount of objects specified at construction time.
 * If a greater amount of objects are cached, then the oldest ones will be retained through a
 * {@linkplain WeakReference weak reference} instead of a strong one.
 * This means that this caching factory will continue to return those objects as long as they are in use somewhere
 * else in the Java virtual machine, but will be discarded (and recreated on the fly if needed) otherwise.
 *
 * <div class="section">Multi-threading</div>
 * The cache managed by this class is concurrent. However the Data Access Objects (DAO) are assumed non-concurrent.
 * If two or more threads are accessing this factory in same time, then two or more Data Access Object instances
 * may be created. The maximal amount of instances to create is specified at {@code ConcurrentAuthorityFactory}
 * construction time. If more Data Access Object instances are needed, some of the threads will block until an
 * instance become available.
 *
 * <div class="section">Note for subclasses</div>
 * This abstract class does not implement any of the {@link DatumAuthorityFactory}, {@link CSAuthorityFactory},
 * {@link CRSAuthorityFactory} and {@link CoordinateOperationAuthorityFactory} interfaces.
 * Subclasses should select the interfaces that they choose to implement.
 *
 * @author  Martin Desruisseaux (IRD, Geomatys)
 * @version 0.8
 *
 * @param <DAO>  the type of factory used as Data Access Object (DAO).
 *
 * @since 0.7
 * @module
 */
public abstract class ConcurrentAuthorityFactory<DAO extends GeodeticAuthorityFactory>
        extends GeodeticAuthorityFactory implements AutoCloseable
{
    /**
     * Duration of data access operations that should be logged, in nanoseconds.
     * Any operation that take longer than this amount of time to execute will have a message logged.
     * The log level depends on the execution duration as specified in {@link PerformanceLevel}.
     */
    private static final long DURATION_FOR_LOGGING = 10_000_000L;       // 10 milliseconds.

    /**
     * Sentinel value when {@link #authority} can not be determined because the data access object
     * can not be constructed.
     */
    private static final Citation UNAVAILABLE = new SimpleCitation("unavailable");

    /**
     * The authority, cached after first requested.
     */
    private transient volatile Citation authority;

    /**
     * The {@code createFoo(String)} methods that are <strong>not</strong> overridden in the Data Access Object (DAO).
     * This map is created at construction time and should not be modified after construction.
     *
     * @see #isDefault(Class)
     */
    private final Map<Class<?>,Boolean> inherited = new IdentityHashMap<>();

    /**
     * The pool of cached objects.
     */
    private final Cache<Key,Object> cache;

    /**
     * The pool of objects identified by {@link Finder#find(IdentifiedObject)}.
     * Values may be an empty set if an object has been searched but has not been found.
     *
     * <p>Every access to this pool must be synchronized on {@code findPool}.</p>
     */
    private final Map<IdentifiedObject,FindEntry> findPool = new WeakHashMap<>();

    /**
     * Holds the reference to a Data Access Object used by {@link ConcurrentAuthorityFactory}, together with
     * information about its usage. In a mono-thread application, there is typically only one {@code DataAccessRef}
     * instance at a given time. However if more than one than one thread are requesting new objects concurrently,
     * then many instances may exist for the same {@code ConcurrentAuthorityFactory}.
     *
     * <p>If the Data Access Object is currently in use, then {@code DataAccessRef} counts how many recursive
     * invocations of a {@link #factory} {@code createFoo(String)} method is under way in the current thread.
     * This information is used in order to reuse the same factory instead than creating new instances
     * when a {@code GeodeticAuthorityFactory} implementation invokes itself indirectly through the
     * {@link ConcurrentAuthorityFactory}. This assumes that factory implementations are reentrant.</p>
     *
     * <p>If the Data Access Object has been released, then {@code DataAccessRef} keep the release timestamp.
     * This information is used for prioritize the Data Access Objects to close.</p>
     */
    private static final class DataAccessRef<DAO extends GeodeticAuthorityFactory> {
        /**
         * The factory used for data access.
         */
        final DAO factory;

        /**
         * Incremented on every call to {@link ConcurrentAuthorityFactory#getDataAccess()} and decremented on every
         * call to {@link ConcurrentAuthorityFactory#release(String, Class, String)}. When this value reach zero,
         * the factory is really released.
         */
        int depth;

        /**
         * The timestamp (<strong>not</strong> relative to epoch) at the time the Data Access Object has been released.
         * This timestamp shall be obtained by {@link System#nanoTime()} for consistency with {@link DelayedRunnable}.
         */
        long timestamp;

        /**
         * Creates new Data Access Object information for the given factory.
         */
        DataAccessRef(final DAO factory) {
            this.factory = factory;
        }

        /**
         * Returns a string representation for debugging purpose only.
         */
        @Override
        public String toString() {
            final String text;
            final Number value;
            if (depth != 0) {
                text = "%s in use at depth %d";
                value = depth;
            } else {
                text = "%s made available %d seconds ago";
                value = Math.round((System.nanoTime() - timestamp) / (double) StandardDateFormat.NANOS_PER_SECOND);
            }
            return String.format(text, Classes.getShortClassName(factory), value);
        }
    }

    /**
     * The Data Access Object in use by the current thread.
     */
    private final ThreadLocal<DataAccessRef<DAO>> currentDAO = new ThreadLocal<>();

    /**
     * The Data Access Object instances previously created and released for future reuse.
     * Last used factories must be {@linkplain Deque#addLast(Object) added last}.
     * This is used as a LIFO stack.
     */
    private final Deque<DataAccessRef<DAO>> availableDAOs = new LinkedList<>();

    /**
     * The amount of Data Access Objects that can still be created. This number is decremented in a block
     * synchronized on {@link #availableDAOs} every time a Data Access Object is in use, and incremented
     * once released.
     */
    private int remainingDAOs;

    /**
     * {@code true} if the call to {@link #closeExpired()} is scheduled for future execution in the background
     * cleaner thread. A value of {@code true} implies that this factory contains at least one active data access.
     * However the reciprocal is not true: this field may be set to {@code false} while a DAO is currently in use
     * because this field is set to {@code true} only when a worker factory is {@linkplain #release released}.
     *
     * <p>Note that we can not use {@code !availableDAOs.isEmpty()} as a replacement of {@code isCleanScheduled}
     * because the queue is empty if all Data Access Objects are currently in use.</p>
     *
     * <p>Every access to this field must be performed in a block synchronized on {@link #availableDAOs}.</p>
     *
     * @see #isCleanScheduled()
     */
    private boolean isCleanScheduled;

    /**
     * The delay of inactivity (in nanoseconds) before to close a Data Access Object.
     * Every access to this field must be performed in a block synchronized on {@link #availableDAOs}.
     *
     * @see #getTimeout(TimeUnit)
     */
    private long timeout = 60_000_000_000L;     // 1 minute

    /**
     * The maximal difference between the scheduled time and the actual time in order to perform the factory disposal,
     * in nanoseconds. This is used as a tolerance value for possible wait time inaccuracy.
     */
    static final long TIMEOUT_RESOLUTION = 200_000_000L;    // 0.2 second

    /**
     * Constructs an instance with a default number of threads and a default number of entries to keep
     * by strong references. Note that those default values may change in any future SIS versions based
     * on experience gained.
     *
     * @param dataAccessClass The class of Data Access Object (DAO) created by {@link #newDataAccess()}.
     */
    protected ConcurrentAuthorityFactory(Class<DAO> dataAccessClass) {
        this(dataAccessClass, 100, 8);
        /*
         * NOTE: if the default maximum number of Data Access Objects (currently 8) is augmented,
         * make sure to augment the number of runner threads in the "StressTest" class to a greater amount.
         */
    }

    /**
     * Constructs an instance with the specified number of entries to keep by strong references.
     * If a number of object greater than {@code maxStrongReferences} are created, then the strong references
     * for the eldest objects will be replaced by weak references.
     *
     * @param dataAccessClass       the class of Data Access Object (DAO) created by {@link #newDataAccess()}.
     * @param maxStrongReferences   the maximum number of objects to keep by strong reference.
     * @param maxConcurrentQueries  the maximal amount of Data Access Objects to use concurrently.
     *        If more than this amount of threads are querying this {@code ConcurrentAuthorityFactory} concurrently,
     *        additional threads will be blocked until a Data Access Object become available.
     */
    protected ConcurrentAuthorityFactory(final Class<DAO> dataAccessClass,
            final int maxStrongReferences, final int maxConcurrentQueries)
    {
        ArgumentChecks.ensureNonNull("dataAccessClass", dataAccessClass);
        ArgumentChecks.ensurePositive("maxStrongReferences", maxStrongReferences);
        ArgumentChecks.ensureStrictlyPositive("maxConcurrentQueries", maxConcurrentQueries);
        /*
         * Detect which methods in the DAO have been overridden.
         */
        for (final Method method : dataAccessClass.getMethods()) {
            if (method.getDeclaringClass() == GeodeticAuthorityFactory.class && method.getName().startsWith("create")) {
                final Class<?>[] p = method.getParameterTypes();
                if (p.length == 1 && p[0] == String.class) {
                    inherited.put(method.getReturnType(), Boolean.TRUE);
                }
            }
        }
        /*
         * Create a cache allowing key collisions.
         * Key collision is usually an error. But in this case we allow them in order to enable recursivity.
         * If during the creation of an object the program asks to this ConcurrentAuthorityFactory for the same
         * object (using the same key), then the default Cache implementation considers that situation as an
         * error unless the above property has been set to 'true'.
         */
        remainingDAOs = maxConcurrentQueries;
        cache = new Cache<>(20, maxStrongReferences, false);
        cache.setKeyCollisionAllowed(true);
        /*
         * The shutdown hook serves two purposes:
         *
         *   1) Closes the Data Access Objects when the garbage collector determined
         *      that this ConcurrentAuthorityFactory is no longer in use.
         *
         *   2) Closes the Data Access Objects at JVM shutdown time if the application is standalone,
         *      or when the bundle is uninstalled if running inside an OSGi or Servlet container.
         */
        Shutdown.register(new ShutdownHook<>(this));
    }

    /**
     * Returns the number of Data Access Objects available for reuse. This count does not include the
     * Data Access Objects that are currently in use. This method is used only for testing purpose.
     *
     * @see #isCleanScheduled()
     */
    @Debug
    final int countAvailableDataAccess() {
        synchronized (availableDAOs) {
            return availableDAOs.size();
        }
    }

    /**
     * Creates a factory which will perform the actual geodetic object creation work.
     * This method is invoked the first time a {@code createFoo(String)} method is invoked.
     * It may also be invoked again if additional factories are needed in different threads,
     * or if all factories have been closed after the timeout.
     *
     * <div class="section">Multi-threading</div>
     * This method (but not necessarily the returned factory) needs to be thread-safe;
     * {@code ConcurrentAuthorityFactory} does not hold any lock when invoking this method.
     * Subclasses are responsible to apply their own synchronization if needed,
     * but are encouraged to avoid doing so if possible.
     * In addition, implementations should not invoke other {@code ConcurrentAuthorityFactory}
     * methods during this method execution in order to avoid never-ending loop.
     *
     * @return Data Access Object (DAO) to use in {@code createFoo(String)} methods.
     * @throws UnavailableFactoryException if the Data Access Object is unavailable because an optional resource is missing.
     * @throws FactoryException if the creation of Data Access Object failed for another reason.
     */
    protected abstract DAO newDataAccess() throws UnavailableFactoryException, FactoryException;

    /**
     * Returns a Data Access Object. This method <strong>must</strong>
     * be used together with {@link #release(String, Class, String)}
     * in a {@code try ... finally} block.
     *
     * @return Data Access Object (DAO) to use in {@code createFoo(String)} methods.
     * @throws FactoryException if the Data Access Object creation failed.
     */
    @SuppressWarnings("null")
    private DAO getDataAccess() throws FactoryException {
        /*
         * First checks if the current thread is already using a factory. If yes, we will
         * avoid creating new factories on the assumption that factories are reentrant.
         */
        DataAccessRef<DAO> usage = currentDAO.get();
        if (usage == null) {
            synchronized (availableDAOs) {
                /*
                 * If we have reached the maximal amount of Data Access Objects allowed, wait for an instance
                 * to become available. In theory the 0.2 second timeout is not necessary, but we put it as a
                 * safety in case we fail to invoke a notify() matching this wait(), for example someone else
                 * is waiting on this monitor or because the release(…) method threw an exception.
                 */
                while (remainingDAOs == 0) {
                    try {
                        availableDAOs.wait(TIMEOUT_RESOLUTION);
                    } catch (InterruptedException e) {
                        // Someone does not want to let us sleep.
                        throw new FactoryException(e.getLocalizedMessage(), e);
                    }
                }
                /*
                 * Reuse the most recently used factory, if available. If there is no factory available for reuse,
                 * creates a new one. We do not add it to the queue now; it will be done by the release(…) method.
                 */
                usage = availableDAOs.pollLast();
                remainingDAOs--;                            // Should be done last when we are sure to not fail.
            }
            /*
             * If there is a need to create a new factory, do that outside the synchronized block because this
             * creation may involve a lot of client code. This is better for reducing the dead-lock risk.
             * Subclasses are responsible of synchronizing their newDataAccess() method if necessary.
             */
            try {
                if (usage == null) {
                    final DAO factory = newDataAccess();
                    if (factory == null) {
                        UnavailableFactoryException e = new UnavailableFactoryException(Errors.format(
                                Errors.Keys.FactoryNotFound_1, GeodeticAuthorityFactory.class));
                        e.setUnavailableFactory(this);
                        throw e;
                    }
                    usage = new DataAccessRef<>(factory);
                }
                assert usage.depth == 0 : usage;
                usage.timestamp = System.nanoTime();
            } catch (Throwable e) {
                /*
                 * If any kind of error occurred, restore the 'remainingDAO' field as if no code were executed.
                 * This code would not have been needed if we were allowed to decrement 'remainingDAO' only as
                 * the very last step (when we know that everything else succeed).
                 * But it needed to be decremented inside the synchronized block.
                 */
                synchronized (availableDAOs) {
                    remainingDAOs++;
                }
                throw e;
            }
            currentDAO.set(usage);
        }
        /*
         * Increment below is safe even if outside the synchronized block,
         * because each thread own exclusively its DataAccessRef instance.
         */
        usage.depth++;
        return usage.factory;
    }

    /**
     * Releases the Data Access Object previously obtained with {@link #getDataAccess()}.
     * This method marks the factory as available for reuse by other threads.
     *
     * <p>All arguments given to this method are for logging purpose only.</p>
     *
     * @param  caller  the caller method, or {@code null} for {@code "create" + type.getSimpleName()}.
     * @param  type    the type of the created object, or {@code null} for performing no logging.
     * @param  code    the code of the created object, or {@code null} if none.
     */
    private void release(String caller, final Class<?> type, final String code) {
        final DataAccessRef<DAO> usage = currentDAO.get();  // A null value here would be an error in our algorithm.
        if (--usage.depth == 0) {
            currentDAO.remove();
            long time = usage.timestamp;
            synchronized (availableDAOs) {
                remainingDAOs++;            // Must be done first in case an exception happen after this point.
                recycle(usage);
                availableDAOs.notify();     // We released only one data access, so awake only one thread - not all of them.
                time = usage.timestamp - time;
            }
            /*
             * Log only events that take longer than the threshold (e.g. 10 milliseconds).
             */
            if (time >= DURATION_FOR_LOGGING && type != null) {
                if (caller == null) {
                    caller = "create".concat(type.getSimpleName());
                }
                final PerformanceLevel level = PerformanceLevel.forDuration(time, TimeUnit.NANOSECONDS);
                final Double duration = time / (double) StandardDateFormat.NANOS_PER_SECOND;
                final Messages resources = Messages.getResources(null);
                final LogRecord record;
                if (code != null) {
                    record = resources.getLogRecord(level, Messages.Keys.CreateDurationFromIdentifier_3, type, code, duration);
                } else {
                    record = resources.getLogRecord(level, Messages.Keys.CreateDuration_2, type, duration);
                }
                record.setLoggerName(Loggers.CRS_FACTORY);
                Logging.log(getClass(), caller, record);
            }
        }
        assert usage.depth >= 0 : usage;
    }

    /**
     * Pushes the given DAO in the list of objects available for reuse.
     */
    private void recycle(final DataAccessRef<DAO> usage) {
        usage.timestamp = System.nanoTime();
        availableDAOs.addLast(usage);
        /*
         * If the Data Access Object we just released is the first one, awake the
         * cleaner thread which was waiting for an indefinite amount of time.
         */
        if (!isCleanScheduled) {
            isCleanScheduled = true;
            DelayedExecutor.schedule(new CloseTask(usage.timestamp + timeout));
        }
    }

    /**
     * {@code true} if the call to {@link #closeExpired()} is scheduled for future execution in the background
     * cleaner thread. A value of {@code true} implies that this factory contains at least one active data access.
     * However the reciprocal is not true: this field may be set to {@code false} while a DAO is currently in use
     * because this field is set to {@code true} only when a worker factory is {@linkplain #release released}.
     *
     * <p>This method is used only for testing purpose.</p>
     *
     * @see #countAvailableDataAccess()
     */
    @Debug
    final boolean isCleanScheduled() {
        synchronized (availableDAOs) {
            return isCleanScheduled;
        }
    }

    /**
     * Confirms that the given factories can be closed. If any factory is still in use,
     * it will be removed from that {@code factories} list and re-injected in the {@link #availableDAOs} queue.
     */
    private void confirmClose(final List<DAO> factories) {
        assert !Thread.holdsLock(availableDAOs);
        for (final Iterator<DAO> it = factories.iterator(); it.hasNext();) {
            final DAO factory = it.next();
            try {
                if (canClose(factory)) {
                    continue;
                }
            } catch (Exception e) {
                unexpectedException("canClose", e);
                continue;                               // Keep the factory on the list of factories to close.
            }
            // Cancel closing for that factory.
            it.remove();
            synchronized (availableDAOs) {
                recycle(new DataAccessRef<>(factory));
            }
        }
    }

    /**
     * A task for invoking {@link ConcurrentAuthorityFactory#closeExpired()} after a delay.
     */
    private final class CloseTask extends DelayedRunnable {
        /**
         * Creates a new task to be executed at the given time,
         * in nanoseconds relative to {@link System#nanoTime()}.
         */
        CloseTask(final long timestamp) {
            super(timestamp);
        }

        /** Invoked when the delay expired. */
        @Override public void run() {
            closeExpired();
        }
    }

    /**
     * Closes the expired Data Access Objects. This method should be invoked from a background task only.
     * This method may reschedule the task again for an other execution if it appears that at least one
     * Data Access Object was not ready for disposal.
     *
     * @see #close()
     */
    final void closeExpired() {
        final List<DAO> factories;
        final boolean isEmpty;
        synchronized (availableDAOs) {
            factories = new ArrayList<>(availableDAOs.size());
            final Iterator<DataAccessRef<DAO>> it = availableDAOs.iterator();
            final long nanoTime = System.nanoTime();
            while (it.hasNext()) {
                final DataAccessRef<DAO> dao = it.next();
                /*
                 * Computes how much time we need to wait again before we can close the factory.
                 * If this time is greater than some arbitrary amount, do not close the factory
                 * and wait again.
                 */
                final long nextTime = dao.timestamp + timeout;
                if (nextTime - nanoTime > TIMEOUT_RESOLUTION) {
                    /*
                     * Found a factory which is not expired. Stop the search,
                     * since the iteration is expected to be ordered.
                     */
                    DelayedExecutor.schedule(new CloseTask(nextTime));
                    break;
                }
                /*
                 * Found an expired factory. Adds it to the list of
                 * factories to close and search for other factories.
                 */
                factories.add(dao.factory);
                it.remove();
            }
            /*
             * The DAOs list is empty if all Data Access Objects in the queue have been closed.
             * Note that some DAOs may still be in use outside the queue, because the DAOs are
             * added to the queue only after completion of their work.
             * In the later case, release() will reschedule a new task.
             */
            isCleanScheduled = !(isEmpty = availableDAOs.isEmpty());
        }
        /*
         * We must close the factories from outside the synchronized block.
         */
        confirmClose(factories);
        try {
            close(factories);
        } catch (Exception exception) {
            unexpectedException("closeExpired", exception);
        }
        /*
         * If the queue of Data Access Objects (DAO) become empty, this means that this ConcurrentAuthorityFactory
         * has not created new object for a while (at least the amount of time given by the timeout), ignoring any
         * request which may be under execution in another thread right now. Reduce the amount of objects retained
         * in the cache of IdentifiedObjectFinder.find(…) results by removing all results containing more than one
         * element, except for results of CoordinateReferenceSystem and CoordinateOperation lookups. The reason is
         * that IdentifiedObjectFinder is almost always used for resolving CoordinateReferenceSystem objects, and
         * all other kind of elements in the cache were dependencies searched as a side effect of the CRS search.
         * Since we have the result of the CRS search, we often do not need anymore the result of dependency search.
         *
         * Touching 'findPool' also has the desired side-effect of letting WeakHashMap expunges stale entries.
         */
        if (isEmpty) {
            synchronized (findPool) {
                final Iterator<FindEntry> it = findPool.values().iterator();
                while (it.hasNext()) {
                    if (it.next().cleanup()) {
                        it.remove();
                    }
                }
            }
        }
    }

    /**
     * Invoked when an exception occurred while closing a factory and we can not propagate the exception to the user.
     * This situation happen when the factories are closed in a background thread. There is not much we can do except
     * logging the problem. {@code ConcurrentAuthorityFactory} should be able to continue its work normally since the
     * factory that we failed to close will not be used anymore.
     *
     * @param  method     the name of the method to report as the source of the problem.
     * @param  exception  the exception that occurred while closing a Data Access Object.
     */
    static void unexpectedException(final String method, final Exception exception) {
        Logging.unexpectedException(Logging.getLogger(Loggers.CRS_FACTORY),
                ConcurrentAuthorityFactory.class, method, exception);
    }

    /**
     * Returns {@code true} if the given Data Access Object (DAO) can be closed. This method is invoked automatically
     * after the {@linkplain #getTimeout timeout} if the given DAO has been idle during all that time.
     * Subclasses can override this method and return {@code false} if they want to prevent the DAO disposal
     * under some circumstances.
     *
     * <p>The default implementation always returns {@code true}.</p>
     *
     * @param  factory  the Data Access Object which is about to be closed.
     * @return {@code true} if the given Data Access Object can be closed.
     *
     * @see #close()
     */
    protected boolean canClose(DAO factory) {
        return true;
    }

    /**
     * Returns the amount of time that {@code ConcurrentAuthorityFactory} will wait before to close a Data Access Object.
     * This delay is measured from the last time the Data Access Object has been used by a {@code createFoo(String)} method.
     *
     * @param  unit  the desired unit of measurement for the timeout.
     * @return the current timeout in the given unit of measurement.
     */
    public long getTimeout(final TimeUnit unit) {
        synchronized (availableDAOs) {
            return unit.convert(timeout, TimeUnit.NANOSECONDS);
        }
    }

    /**
     * Sets a timer for closing the Data Access Object after the specified amount of time of inactivity.
     * If a new Data Access Object is needed after the disposal of the last one, then the {@link #newDataAccess()}
     * method will be invoked again.
     *
     * @param  delay  the delay of inactivity before to close a Data Access Object.
     * @param  unit   the unit of measurement of the given delay.
     */
    public void setTimeout(long delay, final TimeUnit unit) {
        ArgumentChecks.ensureStrictlyPositive("delay", delay);
        delay = unit.toNanos(delay);
        synchronized (availableDAOs) {
            timeout = delay;                // Will be taken in account after the next factory to close.
        }
    }

    /**
     * Returns the database or specification that defines the codes recognized by this factory.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Returns the cached value if it exists.</li>
     *   <li>Otherwise:
     *     <ol>
     *       <li>get an instance of the Data Access Object,</li>
     *       <li>delegate to its {@link GeodeticAuthorityFactory#getAuthority()} method,</li>
     *       <li>release the Data Access Object,</li>
     *       <li>cache the result.</li>
     *     </ol>
     *   </li>
     * </ul>
     *
     * If this method can not get a Data Access Object (for example because no database connection is available),
     * then this method returns {@code null}.
     *
     * @return the organization responsible for definition of the database, or {@code null} if unavailable.
     */
    @Override
    public Citation getAuthority() {
        Citation c = authority;
        if (c == null || c == UNAVAILABLE) try {
            final DAO factory = getDataAccess();
            try {
                /*
                 * Cache only in case of success. If we failed, we
                 * will try again next time this method is invoked.
                 */
                authority = c = factory.getAuthority();
            } finally {
                release("getAuthority", Citation.class, null);
            }
        } catch (FactoryException e) {
            authority = UNAVAILABLE;
            /*
             * Use the warning level only on the first failure, then the fine level on all subsequent failures.
             * Do not log the stack trace if we failed because of UnavailableFactoryException since it may be
             * normal (the EPSG geodetic dataset is optional, even if strongly recommended).
             */
            final LogRecord record = new LogRecord(c == null ? Level.WARNING : Level.FINE, e.getLocalizedMessage());
            if (!(e instanceof UnavailableFactoryException)) {
                record.setThrown(e);
            }
            record.setLoggerName(Loggers.CRS_FACTORY);
            Logging.log(ConcurrentAuthorityFactory.class, "getAuthority", record);
            c = null;
        }
        return c;
    }

    /**
     * Returns the set of authority codes for objects of the given type.
     * The default implementation performs the following steps:
     * <ol>
     *   <li>get an instance of the Data Access Object,</li>
     *   <li>delegate to its {@link GeodeticAuthorityFactory#getAuthorityCodes(Class)} method,</li>
     *   <li>release the Data Access Object.</li>
     * </ol>
     *
     * @param  type  the spatial reference objects type (e.g. {@code ProjectedCRS.class}).
     * @return the set of authority codes for spatial reference objects of the given type.
     *         If this factory does not contains any object of the given type, then this method returns an empty set.
     * @throws FactoryException if access to the underlying database failed.
     */
    @Override
    public Set<String> getAuthorityCodes(final Class<? extends IdentifiedObject> type) throws FactoryException {
        final DAO factory = getDataAccess();
        try {
            return factory.getAuthorityCodes(type);
            /*
             * In the particular case of EPSG factory, the returned Set maintains a live connection to the database.
             * But it still okay to release the factory anyway because our implementation will really close
             * the connection only when the iteration is over or the iterator has been garbage-collected.
             */
        } finally {
            release("getAuthorityCodes", Set.class, null);
        }
    }

    /**
     * Gets a description of the object corresponding to a code.
     * The default implementation performs the following steps:
     * <ol>
     *   <li>get an instance of the Data Access Object,</li>
     *   <li>delegate to its {@link GeodeticAuthorityFactory#getDescriptionText(String)} method,</li>
     *   <li>release the Data Access Object.</li>
     * </ol>
     *
     * @param  code  value allocated by authority.
     * @return a description of the object, or {@code null} if the object
     *         corresponding to the specified {@code code} has no description.
     * @throws NoSuchAuthorityCodeException if the specified {@code code} was not found.
     * @throws FactoryException if the query failed for some other reason.
     */
    @Override
    public InternationalString getDescriptionText(final String code)
            throws NoSuchAuthorityCodeException, FactoryException
    {
        final DAO factory = getDataAccess();
        try {
            return factory.getDescriptionText(code);
        } finally {
            release("getDescriptionText", InternationalString.class, code);
        }
    }

    /**
     * Returns {@code true} if the Data Access Object (DAO) does not provide a {@code create} method for the
     * given type of object. The intent is to decide if the caller should delegate to the DAO or delegate to
     * a more generic method of this class (e.g. {@code createCoordinateReferenceSystem(String)} instead of
     * {@code createGeographicCRS(String)}) in order to give to {@code ConcurrentAuthorityFactory} a chance
     * to reuse a value presents in the cache.
     */
    private boolean isDefault(final Class<?> type) {
        return inherited.containsKey(type);
    }

    /**
     * Returns a code equivalent to the given code but with unnecessary elements eliminated.
     * The normalized code is used as the key in the cache, and is also the code which will
     * be passed to the {@linkplain #newDataAccess() Data Access Object} (DAO).
     *
     * <p>The default implementation performs the following steps:</p>
     * <ol>
     *   <li>Removes the namespace if presents. For example if the {@linkplain #getCodeSpaces() codespace}
     *       is EPSG and the given code starts with the {@code "EPSG:"} prefix, then that prefix is removed.</li>
     *   <li>Removes leading and trailing spaces.</li>
     * </ol>
     *
     * Subclasses can override this method for performing a different normalization work.
     * It is okay to return internal codes completely different than the given codes,
     * provided that the Data Access Objects will understand those internal codes.
     *
     * @param  code  the code to normalize.
     * @return the normalized code.
     * @throws FactoryException if an error occurred while normalizing the given code.
     */
    protected String normalizeCode(String code) throws FactoryException {
        return trimNamespace(code);
    }

    /**
     * Returns an arbitrary object from a code.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Returns the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise:
     *     <ol>
     *       <li>get an instance of the Data Access Object,</li>
     *       <li>delegate to its {@link GeodeticAuthorityFactory#createObject(String)} method,</li>
     *       <li>release the Data Access Object,</li>
     *       <li>cache the result.</li>
     *     </ol>
     *   </li>
     * </ul>
     *
     * @return the object for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public IdentifiedObject createObject(final String code) throws FactoryException {
        return create(AuthorityFactoryProxy.OBJECT, code);
    }

    /**
     * Returns an arbitrary coordinate reference system from a code.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createCoordinateReferenceSystem(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createCoordinateReferenceSystem(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createObject(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate reference system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public CoordinateReferenceSystem createCoordinateReferenceSystem(final String code) throws FactoryException {
        if (isDefault(CoordinateReferenceSystem.class)) {
            return super.createCoordinateReferenceSystem(code);
        }
        return create(AuthorityFactoryProxy.CRS, code);
    }

    /**
     * Returns a 2- or 3-dimensional coordinate reference system based on an ellipsoidal approximation of the geoid.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createGeographicCRS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createGeographicCRS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateReferenceSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate reference system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public GeographicCRS createGeographicCRS(final String code) throws FactoryException {
        if (isDefault(GeographicCRS.class)) {
            return super.createGeographicCRS(code);
        }
        return create(AuthorityFactoryProxy.GEOGRAPHIC_CRS, code);
    }

    /**
     * Returns a 3-dimensional coordinate reference system with the origin at the approximate centre of mass of the earth.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createGeocentricCRS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createGeocentricCRS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateReferenceSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate reference system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public GeocentricCRS createGeocentricCRS(final String code) throws FactoryException {
        if (isDefault(GeocentricCRS.class)) {
            return super.createGeocentricCRS(code);
        }
        return create(AuthorityFactoryProxy.GEOCENTRIC_CRS, code);
    }

    /**
     * Returns a 2-dimensional coordinate reference system used to approximate the shape of the earth on a planar surface.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createProjectedCRS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createProjectedCRS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateReferenceSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate reference system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public ProjectedCRS createProjectedCRS(final String code) throws FactoryException {
        if (isDefault(ProjectedCRS.class)) {
            return super.createProjectedCRS(code);
        }
        return create(AuthorityFactoryProxy.PROJECTED_CRS, code);
    }

    /**
     * Returns a 1-dimensional coordinate reference system used for recording heights or depths.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createVerticalCRS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createVerticalCRS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateReferenceSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate reference system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public VerticalCRS createVerticalCRS(final String code) throws FactoryException {
        if (isDefault(VerticalCRS.class)) {
            return super.createVerticalCRS(code);
        }
        return create(AuthorityFactoryProxy.VERTICAL_CRS, code);
    }

    /**
     * Returns a 1-dimensional coordinate reference system used for the recording of time.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createTemporalCRS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createTemporalCRS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateReferenceSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate reference system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public TemporalCRS createTemporalCRS(final String code) throws FactoryException {
        if (isDefault(TemporalCRS.class)) {
            return super.createTemporalCRS(code);
        }
        return create(AuthorityFactoryProxy.TEMPORAL_CRS, code);
    }

    /**
     * Returns a CRS describing the position of points through two or more independent coordinate reference systems.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createCompoundCRS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createCompoundCRS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateReferenceSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate reference system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public CompoundCRS createCompoundCRS(final String code) throws FactoryException {
        if (isDefault(CompoundCRS.class)) {
            return super.createCompoundCRS(code);
        }
        return create(AuthorityFactoryProxy.COMPOUND_CRS, code);
    }

    /**
     * Returns a CRS that is defined by its coordinate conversion from another CRS (not by a datum).
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createDerivedCRS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createDerivedCRS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateReferenceSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate reference system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public DerivedCRS createDerivedCRS(final String code) throws FactoryException {
        if (isDefault(DerivedCRS.class)) {
            return super.createDerivedCRS(code);
        }
        return create(AuthorityFactoryProxy.DERIVED_CRS, code);
    }

    /**
     * Returns a 1-, 2- or 3-dimensional contextually local coordinate reference system.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createEngineeringCRS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createEngineeringCRS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateReferenceSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate reference system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public EngineeringCRS createEngineeringCRS(final String code) throws FactoryException {
        if (isDefault(EngineeringCRS.class)) {
            return super.createEngineeringCRS(code);
        }
        return create(AuthorityFactoryProxy.ENGINEERING_CRS, code);
    }

    /**
     * Returns a 2-dimensional engineering coordinate reference system applied to locations in images.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createImageCRS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createImageCRS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateReferenceSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate reference system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public ImageCRS createImageCRS(final String code) throws FactoryException {
        if (isDefault(ImageCRS.class)) {
            return super.createImageCRS(code);
        }
        return create(AuthorityFactoryProxy.IMAGE_CRS, code);
    }

    /**
     * Returns an arbitrary datum from a code. The returned object will typically be an
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createDatum(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createDatum(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createObject(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the datum for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public Datum createDatum(final String code) throws FactoryException {
        if (isDefault(Datum.class)) {
            return super.createDatum(code);
        }
        return create(AuthorityFactoryProxy.DATUM, code);
    }

    /**
     * Returns a datum defining the location and orientation of an ellipsoid that approximates the shape of the earth.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createGeodeticDatum(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createGeodeticDatum(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createDatum(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the datum for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public GeodeticDatum createGeodeticDatum(final String code) throws FactoryException {
        if (isDefault(GeodeticDatum.class)) {
            return super.createGeodeticDatum(code);
        }
        return create(AuthorityFactoryProxy.GEODETIC_DATUM, code);
    }

    /**
     * Returns a datum identifying a particular reference level surface used as a zero-height surface.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createVerticalDatum(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createVerticalDatum(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createDatum(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the datum for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public VerticalDatum createVerticalDatum(final String code) throws FactoryException {
        if (isDefault(VerticalDatum.class)) {
            return super.createVerticalDatum(code);
        }
        return create(AuthorityFactoryProxy.VERTICAL_DATUM, code);
    }

    /**
     * Returns a datum defining the origin of a temporal coordinate reference system.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createTemporalDatum(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createTemporalDatum(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createDatum(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the datum for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public TemporalDatum createTemporalDatum(final String code) throws FactoryException {
        if (isDefault(TemporalDatum.class)) {
            return super.createTemporalDatum(code);
        }
        return create(AuthorityFactoryProxy.TEMPORAL_DATUM, code);
    }

    /**
     * Returns a datum defining the origin of an engineering coordinate reference system.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createEngineeringDatum(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createEngineeringDatum(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createDatum(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the datum for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public EngineeringDatum createEngineeringDatum(final String code) throws FactoryException {
        if (isDefault(EngineeringDatum.class)) {
            return super.createEngineeringDatum(code);
        }
        return create(AuthorityFactoryProxy.ENGINEERING_DATUM, code);
    }

    /**
     * Returns a datum defining the origin of an image coordinate reference system.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createImageDatum(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createImageDatum(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createDatum(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the datum for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public ImageDatum createImageDatum(final String code) throws FactoryException {
        if (isDefault(ImageDatum.class)) {
            return super.createImageDatum(code);
        }
        return create(AuthorityFactoryProxy.IMAGE_DATUM, code);
    }

    /**
     * Returns a geometric figure that can be used to describe the approximate shape of the earth.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createEllipsoid(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createEllipsoid(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createObject(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the ellipsoid for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public Ellipsoid createEllipsoid(final String code) throws FactoryException {
        if (isDefault(Ellipsoid.class)) {
            return super.createEllipsoid(code);
        }
        return create(AuthorityFactoryProxy.ELLIPSOID, code);
    }

    /**
     * Returns a prime meridian defining the origin from which longitude values are determined.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createPrimeMeridian(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createPrimeMeridian(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createObject(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the prime meridian for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public PrimeMeridian createPrimeMeridian(final String code) throws FactoryException {
        if (isDefault(PrimeMeridian.class)) {
            return super.createPrimeMeridian(code);
        }
        return create(AuthorityFactoryProxy.PRIME_MERIDIAN, code);
    }

    /**
     * Returns information about spatial, vertical, and temporal extent (usually a domain of validity) from a code.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createExtent(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createExtent(String)}
     *       method in the parent class.</li>
     * </ul>
     *
     * @return the extent for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public Extent createExtent(final String code) throws FactoryException {
        if (isDefault(Extent.class)) {
            return super.createExtent(code);
        }
        return create(AuthorityFactoryProxy.EXTENT, code);
    }

    /**
     * Returns an arbitrary coordinate system from a code.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createCoordinateSystem(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createCoordinateSystem(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createObject(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public CoordinateSystem createCoordinateSystem(final String code) throws FactoryException {
        if (isDefault(CoordinateSystem.class)) {
            return super.createCoordinateSystem(code);
        }
        return create(AuthorityFactoryProxy.COORDINATE_SYSTEM, code);
    }

    /**
     * Returns a 2- or 3-dimensional coordinate system for geodetic latitude and longitude, sometime with ellipsoidal height.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createEllipsoidalCS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createEllipsoidalCS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public EllipsoidalCS createEllipsoidalCS(final String code) throws FactoryException {
        if (isDefault(EllipsoidalCS.class)) {
            return super.createEllipsoidalCS(code);
        }
        return create(AuthorityFactoryProxy.ELLIPSOIDAL_CS, code);
    }

    /**
     * Returns a 1-dimensional coordinate system for heights or depths of points.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createVerticalCS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createVerticalCS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public VerticalCS createVerticalCS(final String code) throws FactoryException {
        if (isDefault(VerticalCS.class)) {
            return super.createVerticalCS(code);
        }
        return create(AuthorityFactoryProxy.VERTICAL_CS, code);
    }

    /**
     * Returns a 1-dimensional coordinate system for heights or depths of points.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createTimeCS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createTimeCS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public TimeCS createTimeCS(final String code) throws FactoryException {
        if (isDefault(TimeCS.class)) {
            return super.createTimeCS(code);
        }
        return create(AuthorityFactoryProxy.TIME_CS, code);
    }

    /**
     * Returns a 2- or 3-dimensional Cartesian coordinate system made of straight orthogonal axes.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createCartesianCS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createCartesianCS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public CartesianCS createCartesianCS(final String code) throws FactoryException {
        if (isDefault(CartesianCS.class)) {
            return super.createCartesianCS(code);
        }
        return create(AuthorityFactoryProxy.CARTESIAN_CS, code);
    }

    /**
     * Returns a 3-dimensional coordinate system with one distance measured from the origin and two angular coordinates.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createSphericalCS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createSphericalCS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public SphericalCS createSphericalCS(final String code) throws FactoryException {
        if (isDefault(SphericalCS.class)) {
            return super.createSphericalCS(code);
        }
        return create(AuthorityFactoryProxy.SPHERICAL_CS, code);
    }

    /**
     * Returns a 3-dimensional coordinate system made of a polar coordinate system
     * extended by a straight perpendicular axis.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createCylindricalCS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createCylindricalCS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public CylindricalCS createCylindricalCS(final String code) throws FactoryException {
        if (isDefault(CylindricalCS.class)) {
            return super.createCylindricalCS(code);
        }
        return create(AuthorityFactoryProxy.CYLINDRICAL_CS, code);
    }

    /**
     * Returns a 2-dimensional coordinate system for coordinates represented by a distance from the origin
     * and an angle from a fixed direction.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createPolarCS(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createPolarCS(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createCoordinateSystem(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the coordinate system for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public PolarCS createPolarCS(final String code) throws FactoryException {
        if (isDefault(PolarCS.class)) {
            return super.createPolarCS(code);
        }
        return create(AuthorityFactoryProxy.POLAR_CS, code);
    }

    /**
     * Returns a coordinate system axis with name, direction, unit and range of values.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createCoordinateSystemAxis(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createCoordinateSystemAxis(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createObject(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the axis for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public CoordinateSystemAxis createCoordinateSystemAxis(final String code) throws FactoryException {
        if (isDefault(CoordinateSystemAxis.class)) {
            return super.createCoordinateSystemAxis(code);
        }
        return create(AuthorityFactoryProxy.AXIS, code);
    }

    /**
     * Returns an unit of measurement from a code.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createUnit(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createUnit(String)}
     *       method in the parent class.</li>
     * </ul>
     *
     * @return the unit of measurement for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public Unit<?> createUnit(final String code) throws FactoryException {
        if (isDefault(Unit.class)) {
            return super.createUnit(code);
        }
        return create(AuthorityFactoryProxy.UNIT, code);
    }

    /**
     * Returns a definition of a single parameter used by an operation method.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createParameterDescriptor(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createParameterDescriptor(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createObject(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the parameter descriptor for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public ParameterDescriptor<?> createParameterDescriptor(final String code) throws FactoryException {
        if (isDefault(ParameterDescriptor.class)) {
            return super.createParameterDescriptor(code);
        }
        return create(AuthorityFactoryProxy.PARAMETER, code);
    }

    /**
     * Returns a description of the algorithm and parameters used to perform a coordinate operation.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createOperationMethod(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createOperationMethod(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createObject(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the operation method for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public OperationMethod createOperationMethod(final String code) throws FactoryException {
        if (isDefault(OperationMethod.class)) {
            return super.createOperationMethod(code);
        }
        return create(AuthorityFactoryProxy.METHOD, code);
    }

    /**
     * Returns an operation for transforming coordinates in the source CRS to coordinates in the target CRS.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Return the cached instance for the given code if such instance already exists.</li>
     *   <li>Otherwise if the Data Access Object (DAO) overrides the {@code createCoordinateOperation(String)}
     *       method, invoke that method and cache the result for future use.</li>
     *   <li>Otherwise delegate to the {@link GeodeticAuthorityFactory#createCoordinateOperation(String)}
     *       method in the parent class. This allows to check if the more generic
     *       {@link #createObject(String)} method cached a value before to try that method.</li>
     * </ul>
     *
     * @return the operation for the given code.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    public CoordinateOperation createCoordinateOperation(final String code) throws FactoryException {
        if (isDefault(CoordinateOperation.class)) {
            return super.createCoordinateOperation(code);
        }
        return create(AuthorityFactoryProxy.OPERATION, code);
    }

    /**
     * The key objects to use in the {@link ConcurrentAuthorityFactory#cache}.
     * This is one of the following pairs of values:
     * <ul>
     *   <li>For all {@code ConcurrentAuthorityFactory.createFoo(String)} methods:
     *     <ol>
     *       <li>The {@code Foo} {@link Class} of the cached object.</li>
     *       <li>The authority code of the cached object.</li>
     *     </ol>
     *   </li>
     *   <li>For {@link ConcurrentAuthorityFactory#createFromCoordinateReferenceSystemCodes(String, String)}:
     *     <ol>
     *       <li>The authority code of source CRS (stored in the "type" field even if the name is not right).</li>
     *       <li>The authority code of target CRS (stored in the "code" field).</li>
     *     </ol>
     *   </li>
     * </ul>
     */
    private static final class Key {
        /** The type of the cached object.    */ final Object type;
        /** The cached object authority code. */ final String code;

        /** Creates a new key for the given type and code. */
        Key(final Object type, final String code) {
            this.type = type;
            this.code = code;
        }

        /** Returns the hash code value for this key. */
        @Override public int hashCode() {
            return type.hashCode() ^ code.hashCode();
        }

        /** Compares this key with the given object for equality .*/
        @Override public boolean equals(final Object other) {
            if (other instanceof Key) {
                final Key that = (Key) other;
                return type.equals(that.type) && code.equals(that.code);
            }
            return false;
        }

        /** String representation used by {@link CacheRecord}. */
        @Override public String toString() {
            final StringBuilder buffer = new StringBuilder();
            if (type instanceof Class<?>) {
                buffer.append("Code[“").append(code);
                if (buffer.length() > 15) {                     // Arbitrary limit in string length.
                    buffer.setLength(15);
                    buffer.append('…');
                }
                buffer.append("” : ").append(((Class<?>) type).getSimpleName());
            } else {
                buffer.append("CodePair[“").append(type).append("” → “").append(code).append('”');
            }
            return buffer.append(']').toString();
        }
    }

    /**
     * Returns an object from a code using the given proxy. This method first checks in the cache.
     * If no object exists in the cache for the given code, then a lock is created and the object
     * creation is delegated to the {@linkplain #getDataAccess() Data Access Object}.
     * The result is then stored in the cache and returned.
     *
     * @param  <T>    the type of the object to be returned.
     * @param  proxy  the proxy to use for creating the object.
     * @param  code   the code of the object to create.
     * @return the object extracted from the cache or created.
     * @throws FactoryException if an error occurred while creating the object.
     */
    private <T> T create(final AuthorityFactoryProxy<T> proxy, final String code) throws FactoryException {
        ArgumentChecks.ensureNonNull("code", code);
        final Class<T> type = proxy.type;
        final Key key = new Key(type, normalizeCode(code));
        Object value = cache.peek(key);
        if (!type.isInstance(value)) {
            final Cache.Handler<Object> handler = cache.lock(key);
            try {
                value = handler.peek();
                if (!type.isInstance(value)) {
                    final T result;
                    final DAO factory = getDataAccess();
                    try {
                        result = proxy.create(factory, key.code);
                    } finally {
                        release(null, type, code);
                    }
                    if (isCacheable(code, result)) {
                        value = result;                                 // For the finally block below.
                    }
                    return result;
                }
            } finally {
                handler.putAndUnlock(value);
            }
        }
        return type.cast(value);
    }

    /**
     * Returns operations from source and target coordinate reference system codes.
     * The default implementation performs the following steps:
     * <ul>
     *   <li>Returns the cached collection for the given pair of codes if such collection already exists.</li>
     *   <li>Otherwise:
     *     <ol>
     *       <li>get an instance of the Data Access Object,</li>
     *       <li>delegate to its {@link GeodeticAuthorityFactory#createFromCoordinateReferenceSystemCodes(String, String)} method,</li>
     *       <li>release the Data Access Object — <em>this step assumes that the collection obtained at step 2
     *           is still valid after the Data Access Object has been released</em>,</li>
     *       <li>cache the result — <em>this step assumes that the collection obtained at step 2 is immutable</em>.</li>
     *     </ol>
     *   </li>
     * </ul>
     *
     * @return the operations from {@code sourceCRS} to {@code targetCRS}.
     * @throws FactoryException if the object creation failed.
     */
    @Override
    @SuppressWarnings("unchecked")
    public Set<CoordinateOperation> createFromCoordinateReferenceSystemCodes(
            final String sourceCRS, final String targetCRS) throws FactoryException
    {
        ArgumentChecks.ensureNonNull("sourceCRS", sourceCRS);
        ArgumentChecks.ensureNonNull("targetCRS", targetCRS);
        final Key key = new Key(normalizeCode(sourceCRS), normalizeCode(targetCRS));
        Object value = cache.peek(key);
        if (!(value instanceof Set<?>)) {
            final Cache.Handler<Object> handler = cache.lock(key);
            try {
                value = handler.peek();
                if (!(value instanceof Set<?>)) {
                    final DAO factory = getDataAccess();
                    try {
                        value = factory.createFromCoordinateReferenceSystemCodes(sourceCRS, targetCRS);
                    } finally {
                        release("createFromCoordinateReferenceSystemCodes", CoordinateOperation.class, null);
                    }
                }
            } finally {
                handler.putAndUnlock(value);
            }
        }
        return (Set<CoordinateOperation>) value;
    }

    /**
     * Returns a finder which can be used for looking up unidentified objects.
     * The default implementation delegates lookup to the underlying Data Access Object and caches the result.
     *
     * @return a finder to use for looking up unidentified objects.
     * @throws FactoryException if the finder can not be created.
     */
    @Override
    public IdentifiedObjectFinder newIdentifiedObjectFinder() throws FactoryException {
        return new Finder(this);
    }

    /**
     * An implementation of {@link IdentifiedObjectFinder} which delegates
     * the work to the underlying Data Access Object and caches the result.
     *
     * <div class="section">Synchronization note</div>
     * our public API claims that {@link IdentifiedObjectFinder}s are not thread-safe.
     * Nevertheless we synchronize this particular implementation for safety, because the consequence of misuse
     * are more dangerous than other implementations. Furthermore this is also a way to assert that no code path
     * go to the {@link #create(AuthorityFactoryProxy, String)} method from a non-overridden public method.
     *
     * @author  Martin Desruisseaux (IRD, Geomatys)
     * @version 0.7
     * @since   0.7
     * @module
     */
    private static final class Finder extends IdentifiedObjectFinder {
        /**
         * The finder on which to delegate the work. This is acquired by {@link #acquire()}
         * <strong>and must be released</strong> by call to {@link #release()} once finished.
         */
        private transient IdentifiedObjectFinder finder;

        /**
         * Number of time that {@link #acquire()} has been invoked.
         * When this count reaches zero, the {@linkplain #finder} is released.
         */
        private transient int acquireCount;

        /**
         * The object in process of being searched, for information purpose only.
         */
        private transient IdentifiedObject searching;

        /**
         * Creates a finder for the given type of objects.
         */
        Finder(final ConcurrentAuthorityFactory<?> factory) {
            super(factory);
        }

        /**
         * Acquires a new {@linkplain #finder}.
         * The {@link #release()} method must be invoked in a {@code finally} block after the call to {@code acquire}.
         * The pattern must be as below (note that the call to {@code acquire()} is inside the {@code try} block):
         *
         * {@preformat java
         *     try {
         *         acquire();
         *         (finder or proxy).doSomeStuff();
         *     } finally {
         *         release();
         *     }
         * }
         */
        private void acquire() throws FactoryException {
            assert Thread.holdsLock(this);
            assert (acquireCount == 0) == (finder == null) : acquireCount;
            if (acquireCount == 0) {
                final GeodeticAuthorityFactory delegate = ((ConcurrentAuthorityFactory<?>) factory).getDataAccess();
                /*
                 * Set 'acquireCount' only after we succeed in fetching the factory, and before any operation on it.
                 * The intent is to get ConcurrentAuthorityFactory.release() invoked if and only if the getDataAccess()
                 * method succeed, no matter what happen after this point.
                 */
                acquireCount = 1;
                finder = delegate.newIdentifiedObjectFinder();
                finder.setWrapper(this);
            } else {
                acquireCount++;
            }
        }

        /**
         * Releases the {@linkplain #finder}.
         */
        private void release() {
            assert Thread.holdsLock(this);
            if (acquireCount == 0) {
                // May happen only if a failure occurred during getDataAccess() execution.
                return;
            }
            if (--acquireCount == 0) {
                finder = null;
                ((ConcurrentAuthorityFactory<?>) factory).release(null, null, null);
            }
        }

        /**
         * Returns a set of authority codes that <strong>may</strong> identify the same
         * object than the specified one. This method delegates to the data access object.
         */
        @Override
        protected synchronized Set<String> getCodeCandidates(final IdentifiedObject object) throws FactoryException {
            try {
                acquire();
                return finder.getCodeCandidates(object);
            } finally {
                release();
            }
        }

        /**
         * Returns the cached value for the given object, or {@code null} if none.
         */
        @Override
        final Set<IdentifiedObject> getFromCache(final IdentifiedObject object) {
            final Map<IdentifiedObject,FindEntry> findPool = ((ConcurrentAuthorityFactory<?>) factory).findPool;
            synchronized (findPool) {
                final FindEntry entry = findPool.get(object);
                if (entry != null) {
                    // 'finder' may be null if this method is invoked directly by this Finder.
                    return entry.get((finder != null ? finder : this).isIgnoringAxes());
                }
            }
            return null;
        }

        /**
         * Stores the given result in the cache.
         * This method shall be invoked only when {@link #getSearchDomain()} is not {@link Domain#DECLARATION}.
         */
        @Override
        final Set<IdentifiedObject> cache(final IdentifiedObject object, Set<IdentifiedObject> result) {
            final Map<IdentifiedObject,FindEntry> findPool = ((ConcurrentAuthorityFactory<?>) factory).findPool;
            result = CollectionsExt.unmodifiableOrCopy(result);
            FindEntry entry = new FindEntry();
            synchronized (findPool) {
                final FindEntry c = findPool.putIfAbsent(object, entry);
                if (c != null) {
                    entry = c;          // May happen if the same set has been computed in another thread.
                }
                // 'finder' should never be null since this method is not invoked directly by this Finder.
                result = entry.set(finder.isIgnoringAxes(), result, object == searching);
            }
            return result;
        }

        /**
         * Looks up an object from this authority factory which is approximately equal to the specified object.
         * The default implementation performs the same lookup than the Data Access Object and caches the result.
         */
        @Override
        public Set<IdentifiedObject> find(final IdentifiedObject object) throws FactoryException {
            Set<IdentifiedObject> candidate = getFromCache(object);
            if (candidate == null) {
                /*
                 * Nothing has been found in the cache. Delegates the search to the Data Access Object.
                 * Note that the Data Access Object will itself callbacks our 'cache(…)' method, so there
                 * is no need that we cache the result here.
                 */
                synchronized (this) {
                    try {
                        acquire();
                        searching = object;
                        candidate = finder.find(object);
                    } finally {
                        searching = null;
                        release();
                    }
                }
            }
            return candidate;
        }
    }

    /**
     * Cache for the result of {@link IdentifiedObjectFinder#find(IdentifiedObject)} operations.
     * All access to this object must be done in a block synchronized on {@link #findPool}.
     */
    private static final class FindEntry {
        /** Result of the search with or without ignoring axes. */
        private Set<IdentifiedObject> strict, lenient;

        /** Whether the cache is the result of an explicit request instead than a dependency search. */
        private boolean explicitStrict, explicitLenient;

        /** Returns the cached instance. */
        Set<IdentifiedObject> get(final boolean ignoreAxes) {
            return ignoreAxes ? lenient : strict;
        }

        /** Cache an instance, or return previous instance if computed concurrently. */
        @SuppressWarnings({"AssignmentToCollectionOrArrayFieldFromParameter", "ReturnOfCollectionOrArrayField"})
        Set<IdentifiedObject> set(final boolean ignoreAxes, Set<IdentifiedObject> result, final boolean explicit) {
            if (ignoreAxes) {
                if (lenient != null) {
                    result = lenient;
                } else {
                    lenient = result;
                }
                explicitLenient |= explicit;
            } else {
                if (strict != null) {
                    result = strict;
                } else {
                    strict = result;
                }
                explicitStrict |= explicit;
            }
            return result;
        }

        /** Forgets the set that were not explicitly requested. */
        boolean cleanup() {
            if (!explicitStrict)  strict  = null;
            if (!explicitLenient) lenient = null;
            return (strict == null) && (lenient == null);
        }
    }

    /**
     * Returns whether the given object can be cached. This method is invoked after the
     * {@linkplain #newDataAccess() Data Access Object} created a new object not previously in the cache.
     * If this {@code isCacheable(…)} method returns {@code true}, then the newly created object will be cached so
     * that next calls to the same {@code createFoo(String)} method with the same code may return the same object.
     * If this method returns {@code false}, then the newly created object will not be cached and next call to
     * the {@code createFoo(String)} method with the same code will return a new object.
     *
     * <p>The default implementation always returns {@code true}.
     * Subclasses can override this method for filtering the objects to store in the cache.</p>
     *
     * @param  code    the authority code specified by the caller for creating an object.
     * @param  object  the object created for the given authority code.
     * @return whether the given object should be cached.
     *
     * @see #printCacheContent(PrintWriter)
     *
     * @since 0.8
     */
    protected boolean isCacheable(String code, Object object) {
        return true;
    }

    /**
     * Prints the cache content to the given writer.
     * Keys are sorted by numerical order if possible, or alphabetical order otherwise.
     * This method is used for debugging purpose only.
     *
     * @param  out  the output printer, or {@code null} for the {@linkplain System#out standard output stream}.
     *
     * @see #isCacheable(String, Object)
     */
    @Debug
    public void printCacheContent(final PrintWriter out) {
        CacheRecord.printCacheContent(cache, out);
    }

    /**
     * A hook to be executed either when the {@link ConcurrentAuthorityFactory} is collected by the garbage collector,
     * when the Java Virtual Machine is shutdown, or when the module is uninstalled by the OSGi or Servlet container.
     *
     * <p><strong>Do not keep reference to the enclosing factory</strong> - in particular,
     * this class must not be static - otherwise the factory would never been garbage collected.</p>
     */
    private static final class ShutdownHook<DAO extends GeodeticAuthorityFactory>           // MUST be static!
            extends PhantomReference<ConcurrentAuthorityFactory<DAO>> implements Disposable, Callable<Object>
    {
        /**
         * The {@link ConcurrentAuthorityFactory#availableDAOs} queue.
         */
        private final Deque<DataAccessRef<DAO>> availableDAOs;

        /**
         * Creates a new shutdown hook for the given factory.
         */
        ShutdownHook(final ConcurrentAuthorityFactory<DAO> factory) {
            super(factory, ReferenceQueueConsumer.QUEUE);
            availableDAOs = factory.availableDAOs;
        }

        /**
         * Invoked indirectly by the garbage collector when the {@link ConcurrentAuthorityFactory} is disposed.
         */
        @Override
        public void dispose() {
            Shutdown.unregister(this);
            try {
                call();
            } catch (Exception exception) {
                /*
                 * Pretend that the exception is logged by ConcurrentAuthorityFactory.finalize().
                 * This is not true, but carries the idea that the error occurred while cleaning
                 * ConcurrentAuthorityFactory after garbage collection.
                 */
                unexpectedException("finalize", exception);
            }
        }

        /**
         * Invoked at JVM shutdown time, or when the container (OSGi or Servlet) uninstall the bundle containing SIS.
         */
        @Override
        public Object call() throws Exception {
            final List<DAO> factories;
            synchronized (availableDAOs) {
                factories = ConcurrentAuthorityFactory.clear(availableDAOs);
            }
            // No call to confirmClose(List<DAO>) as we want to force close.
            close(factories);
            return null;
        }
    }

    /**
     * Clears the given queue and returns all DAO instances that it contained.
     * The given queue shall be the {@link ConcurrentAuthorityFactory#availableDAOs} queue.
     *
     * @param  availableDAOs  the queue of factories to close.
     */
    static <DAO extends GeodeticAuthorityFactory> List<DAO> clear(final Deque<DataAccessRef<DAO>> availableDAOs) {
        assert Thread.holdsLock(availableDAOs);
        final List<DAO> factories = new ArrayList<>(availableDAOs.size());
        DataAccessRef<DAO> dao;
        while ((dao = availableDAOs.pollFirst()) != null) {
            factories.add(dao.factory);
        }
        return factories;
    }

    /**
     * Invokes {@link AutoCloseable#close()} on all the given factories.
     * Exceptions will be collected and rethrown only after all factories have been closed.
     *
     * @param  factories  the factories to close.
     * @throws Exception the exception thrown by the first factory that failed to close.
     */
    static <DAO extends GeodeticAuthorityFactory> void close(final List<DAO> factories) throws Exception {
        Exception exception = null;
        for (int i=factories.size(); --i>=0;) {
            final DAO factory = factories.get(i);
            if (factory instanceof AutoCloseable) try {
                ((AutoCloseable) factory).close();
            } catch (Exception e) {
                if (exception == null) {
                    exception = e;
                } else {
                    exception.addSuppressed(e);
                }
            }
        }
        if (exception != null) {
            throw exception;
        }
    }

    /**
     * Immediately closes all Data Access Objects that are closeable.
     * This method does not clear the cache and does not disallow further usage of this factory:
     * this {@code ConcurrentAuthorityFactory} can still be used as usual after it has been "closed".
     * {@linkplain #newDataAccess() New Data Access Objects} will be created if needed for replacing
     * the ones closed by this method.
     *
     * <p>The main purpose of this method is to force immediate release of JDBC connections or other kind of resources
     * that Data Access Objects may hold. If this method is not invoked, Data Access Objects will be closed
     * when this {@code ConcurrentAuthorityFactory} will be garbage collected or at JVM shutdown time,
     * depending which event happen first.</p>
     *
     * @throws FactoryException if an error occurred while closing the Data Access Objects.
     *
     * @see #canClose(GeodeticAuthorityFactory)
     */
    @Override
    public void close() throws FactoryException {
        try {
            final List<DAO> factories;
            synchronized (availableDAOs) {
                factories = clear(availableDAOs);
            }
            confirmClose(factories);
            close(factories);                       // Must be invoked outside the synchronized block.
        } catch (Exception e) {
            if (e instanceof FactoryException) {
                throw (FactoryException) e;
            } else {
                throw new FactoryException(e);
            }
        }
    }

    /**
     * Returns a string representation of this factory for debugging purpose only.
     * The string returned by this method may change in any future SIS version.
     *
     * @return a string representation for debugging purpose.
     *
     * @see #printCacheContent(PrintWriter)
     */
    @Override
    public String toString() {
        final String s = super.toString();
        DataAccessRef<DAO> usage = currentDAO.get();
        if (usage == null) {
            synchronized (availableDAOs) {
                usage = availableDAOs.peekLast();
            }
            if (usage == null) {
                return s;
            }
        }
        return s + System.lineSeparator() + usage;
    }

    /**
     * Completes the string representation of this factory for debugging purpose only.
     * The string formatted by this method may change in any future SIS version.
     */
    @Debug
    @Override
    final void appendStringTo(final StringBuilder buffer) {
        buffer.append(", cache=").append(cache.size()).append(", DAO=");
        synchronized (availableDAOs) {
            buffer.append(availableDAOs.size());
            if (remainingDAOs <= 0) {
                buffer.append(" (limit reached)");
            }
        }
    }
}