001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2007-2023 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.metadata.identification;
019
020import org.opengis.annotation.UML;
021import org.opengis.annotation.Classifier;
022import org.opengis.annotation.Stereotype;
023
024import static org.opengis.annotation.Obligation.MANDATORY;
025import static org.opengis.annotation.Specification.ISO_19115;
026
027
028/**
029 * A scale defined as the inverse of a denominator. This is derived from ISO 19103 {@code Scale}
030 * where {@linkplain #getDenominator() denominator} = 1 / <var>scale</var>.
031 *
032 * <p>Implementations are encouraged to extend {@link Number} in a manner equivalent to:</p>
033 *
034 * {@snippet lang="java" :
035 * class MyFraction extends Number implements RepresentativeFraction {
036 *     public double doubleValue() {
037 *         return 1.0 / (double) denominator;
038 *     }
039 *     public float floatValue() {
040 *         return 1.0f / (float) denominator;
041 *     }
042 *     public long longValue() {
043 *         return 1 / denominator;       // Result is zero except for denominator = [0,1].
044 *     }
045 * }}
046 *
047 * @author  Ely Conn (Leica Geosystems Geospatial Imaging, LLC)
048 * @version 3.1
049 * @since   2.1
050 *
051 * @see Resolution#getEquivalentScale()
052 */
053@Classifier(Stereotype.DATATYPE)
054@UML(identifier="MD_RepresentativeFraction", specification=ISO_19115)
055public interface RepresentativeFraction {
056    /**
057     * Returns the scale value in a form usable for computation.
058     *
059     * @return <code>1.0 / (double) {@linkplain #getDenominator()}</code>
060     */
061    double doubleValue();
062
063    /**
064     * The number below the line in a vulgar fraction.
065     *
066     * @return the denominator.
067     */
068    @UML(identifier = "denominator", obligation = MANDATORY, specification = ISO_19115)
069    long getDenominator();
070
071    /**
072     * Compares this representative fraction with the specified object for equality.
073     * Implementations should match the following:
074     *
075     * {@snippet lang="java" :
076     * public boolean equals(Object object) {
077     *     if (object instanceof RepresentativeFraction) {
078     *         final RepresentativeFraction that = (RepresentativeFraction) object;
079     *         return getDenominator() == that.getDenominator();
080     *     }
081     *     return false;
082     * }}
083     *
084     * @param  other  the object to compare with.
085     * @return {@code true} if {@code other} is a {@code RepresentedFraction} with the same
086     *         {@linkplain #getDenominator() denominator} value.
087     */
088    @Override
089    boolean equals(Object other);
090
091    /**
092     * Returns a hash value for this representative fraction.
093     * Implementations should match the following:
094     *
095     * {@snippet lang="java" :
096     * public int hashCode() {
097     *     return (int) getDenominator();
098     * }}
099     *
100     * @return a hash code value for this representative fraction.
101     */
102    @Override
103    int hashCode();
104}