001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2021-2024 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.filter;
019
020import org.opengis.util.CodeList;
021import org.opengis.annotation.UML;
022import org.opengis.geoapi.internal.Vocabulary;
023
024import static org.opengis.annotation.Obligation.CONDITIONAL;
025import static org.opengis.annotation.Specification.ISO_19143;
026
027
028/**
029 * Nature of the spatial operation computed with geometries and a distance parameter.
030 *
031 * @author  Chris Dillard (SYS Technologies)
032 * @author  Martin Desruisseaux (Geomatys)
033 * @version 3.1
034 * @since   3.1
035 */
036@Vocabulary(capacity=2)
037@UML(identifier="DistanceOperatorName", specification=ISO_19143)
038public final class DistanceOperatorName extends CodeList<DistanceOperatorName> {
039    /**
040     * Serial number for compatibility with different versions.
041     */
042    private static final long serialVersionUID = -6843540817045459049L;
043
044    /**
045     * Operator evaluates to {@code true} when all of a feature's geometry lies beyond
046     * (is more distant) than a given distance from the filter geometry.
047     * More specifically:
048     *
049     * <blockquote>{@literal Beyond(A,B,d) = Distance(A,B) > d}</blockquote>
050     */
051    @UML(identifier="Beyond", obligation=CONDITIONAL, specification=ISO_19143)
052    public static final DistanceOperatorName BEYOND = new DistanceOperatorName("BEYOND");
053
054    /**
055     * Operator evaluates to {@code true} when any part of the first geometry
056     * lies within the given distance of the second geometry.
057     * More specifically:
058     *
059     * <blockquote>{@literal Within(A,B,d) = Distance(A,B) < d}</blockquote>
060     */
061    @UML(identifier="DWithin", obligation=CONDITIONAL, specification=ISO_19143)
062    public static final DistanceOperatorName WITHIN = new DistanceOperatorName("WITHIN");
063
064    /**
065     * Constructs an element of the given name.
066     *
067     * @param name  the name of the new element. This name shall not be in use by another element of this type.
068     */
069    private DistanceOperatorName(final String name) {
070        super(name);
071    }
072
073    /**
074     * Returns the list of {@code DistanceOperatorName}s.
075     *
076     * @return the list of codes declared in the current JVM.
077     */
078    public static DistanceOperatorName[] values() {
079        return values(DistanceOperatorName.class);
080    }
081
082    /**
083     * Returns the list of codes of the same kind as this code list element.
084     * Invoking this method is equivalent to invoking {@link #values()}, except that
085     * this method can be invoked on an instance of the parent {@code CodeList} class.
086     *
087     * @return all code {@linkplain #values() values} for this code list.
088     */
089    @Override
090    public DistanceOperatorName[] family() {
091        return values();
092    }
093
094    /**
095     * Returns the distance operator that matches the given string, or returns a new one if none match it.
096     * This methods returns the first instance (in declaration order) for which the {@linkplain #name() name}
097     * is {@linkplain String#equalsIgnoreCase(String) equals, ignoring case}, to the given name.
098     * If no existing instance is found, then a new one is created for the given name.
099     *
100     * @param  code  the name of the code to fetch or to create.
101     * @return a code matching the given name.
102     */
103    public static DistanceOperatorName valueOf(String code) {
104        return valueOf(DistanceOperatorName.class, code, DistanceOperatorName::new).get();
105    }
106}