001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    http://www.geoapi.org
004 *
005 *    Copyright (C) 2011-2019 Open Geospatial Consortium, Inc.
006 *    All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 *    Permission to use, copy, and modify this software and its documentation, with
009 *    or without modification, for any purpose and without fee or royalty is hereby
010 *    granted, provided that you include the following on ALL copies of the software
011 *    and documentation or portions thereof, including modifications, that you make:
012 *
013 *    1. The full text of this NOTICE in a location viewable to users of the
014 *       redistributed or derivative work.
015 *    2. Notice of any changes or modifications to the OGC files, including the
016 *       date changes were made.
017 *
018 *    THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 *    NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 *    TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 *    THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 *    PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 *    COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 *    CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 *    The name and trademarks of copyright holders may NOT be used in advertising or
028 *    publicity pertaining to the software without specific, written prior permission.
029 *    Title to copyright in this software and any associated documentation will at all
030 *    times remain with copyright holders.
031 */
032package org.opengis.test;
033
034import org.opengis.util.Factory;
035import org.opengis.referencing.operation.MathTransform;
036
037
038/**
039 * Provides optional information about the implementation being tested. Implementors can
040 * provide an instance of this interface in their test packages and declare their instance
041 * in the {@code META-INF/services/org.opengis.test.ImplementationDetails} file. GeoAPI
042 * will iterate over every {@code ImplementationDetails} found on the classpath when needed:
043 *
044 * <ul>
045 *   <li>Before each execution of a configurable {@link TestCase}, in order to check which tests
046 *   (if any) should be disabled.</li>
047 *
048 *   <li>Before each execution of a {@link TestCase} performing numerical calculation, in
049 *   order to determine if a specific implementation needs to relax the tolerance threshold.</li>
050 * </ul>
051 *
052 * If no instance of {@code ImplementationDetails} is registered, then GeoAPI assumes that
053 * all tests are enabled with their default tolerance threshold. This is equivalent to using
054 * an {@code ImplementationDetails} instance where every methods return {@code null}.
055 *
056 * @author  Martin Desruisseaux (Geomatys)
057 * @version 3.1
058 * @since   3.1
059 */
060public interface ImplementationDetails {
061    /**
062     * Returns the set of tests that should be disabled, or {@code null} if none.
063     * If non-null, then the returned map can contain some {@link org.opengis.test.Configuration.Key}
064     * associated to the {@link Boolean#FALSE} value. Example:
065     *
066     * <blockquote><pre>&#64;Override
067     *public Configuration configuration(Factory... factories) {
068     *    Configuration config = new Configuration();
069     *    config.{@linkplain Configuration#unsupported unsupported}({@linkplain org.opengis.test.Configuration.Key#isDerivativeSupported}, {@linkplain org.opengis.test.Configuration.Key#isNonSquareMatrixSupported});
070     *    return config;
071     *}</pre></blockquote>
072     *
073     * If more than one {@code ImplementationDetails} is found on the classpath, then a logical {@code AND}
074     * is performed on the boolean values returned by all {@code ImplementationDetails.configuration(…)} calls.
075     *
076     * <p>This method is invoked often (typically one or two time before every single test method),
077     * so implementors may want to cache their configuration map.</p>
078     *
079     * @param  factories  the factories to be tested.
080     * @return the collection of tests to disable for the given factories, or {@code null} if none.
081     *
082     * @see TestCase#configuration()
083     */
084    Configuration configuration(Factory... factories);
085
086    /**
087     * Returns an object for modifying the tolerance thresholds when testing the given math transform,
088     * or {@code null} if no change is needed. This method should return a non-null value only if the
089     * implementation being tested does not have the accuracy expected by the {@link TestCase}. In
090     * such case, the object returned by this method can be used for relaxing the tolerance threshold.
091     *
092     * <p>If more than one {@code ImplementationDetails} return a non-null value, then the threshold
093     * used by GeoAPI will be the maximal value returned by all {@code ToleranceModifier} objects.</p>
094     *
095     * @param  transform  the transform being tested.
096     * @return an object for modifying the tolerance thresholds, or {@code null} if no change is needed.
097     */
098    ToleranceModifier tolerance(MathTransform transform);
099}