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>@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}