001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 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.referencing.datum;
019
020import org.opengis.util.CodeList;
021import org.opengis.annotation.UML;
022import org.opengis.geoapi.internal.Vocabulary;
023
024import static org.opengis.annotation.Obligation.*;
025import static org.opengis.annotation.Specification.*;
026
027
028/**
029 * Specification of the method by which the vertical reference frame is realized.
030 *
031 * @see VerticalDatum#getRealizationMethod()
032 *
033 * @author  OGC Topic 2 (for abstract model and documentation)
034 * @author  Martin Desruisseaux (Geomatys)
035 * @version 3.1
036 * @since   3.1
037 */
038@Vocabulary(capacity=3)
039@UML(identifier="RealizationMethod", specification=ISO_19111)
040public final class RealizationMethod extends CodeList<RealizationMethod> {
041    /**
042     * Serial number for compatibility with different versions.
043     */
044    private static final long serialVersionUID = -4801740301491126879L;
045
046    /**
047     * Realization is by adjustment of a levelling network fixed to one or more tide gauges.
048     */
049    @UML(identifier="levelling", obligation=CONDITIONAL, specification=ISO_19111)
050    public static final RealizationMethod LEVELLING = new RealizationMethod("LEVELLING");
051
052    /**
053     * Realization is through a geoid height model or a height correction model.
054     * This is applied to a specified geodetic <abbr>CRS</abbr>.
055     */
056    @UML(identifier="geoid", obligation=CONDITIONAL, specification=ISO_19111)
057    public static final RealizationMethod GEOID = new RealizationMethod("GEOID");
058
059    /**
060     * Realization is through a tidal model or by tidal predictions.
061     */
062    @UML(identifier="tidal", obligation=CONDITIONAL, specification=ISO_19111)
063    public static final RealizationMethod TIDAL = new RealizationMethod("TIDAL");
064
065    /**
066     * Constructs an element of the given name.
067     *
068     * @param name  the name of the new element. This name shall not be in use by another element of this type.
069     */
070    private RealizationMethod(final String name) {
071        super(name);
072    }
073
074    /**
075     * Returns the list of {@code RealizationMethod}s.
076     *
077     * @return the list of codes declared in the current JVM.
078     */
079    public static RealizationMethod[] values() {
080        return values(RealizationMethod.class);
081    }
082
083    /**
084     * Returns the list of codes of the same kind as this code list element.
085     * Invoking this method is equivalent to invoking {@link #values()}, except that
086     * this method can be invoked on an instance of the parent {@code CodeList} class.
087     *
088     * @return all code {@linkplain #values() values} for this code list.
089     */
090    @Override
091    public RealizationMethod[] family() {
092        return values();
093    }
094
095    /**
096     * Returns the realization method that matches the given string, or returns a new one if none match it.
097     * This methods returns the first instance (in declaration order) for which the {@linkplain #name() name}
098     * is {@linkplain String#equalsIgnoreCase(String) equals, ignoring case}, to the given name.
099     * If no existing instance is found, then a new one is created for the given name.
100     *
101     * @param  code  the name of the code to fetch or to create.
102     * @return a code matching the given name.
103     */
104    public static RealizationMethod valueOf(String code) {
105        return valueOf(RealizationMethod.class, code, RealizationMethod::new).get();
106    }
107}