/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.sis.metadata;


/**
 * The kind of values in the {@link MetadataStandard#asTypeMap MetadataStandard.asTypeMap(…)}.
 * This enumeration specifies whether the values shall be property types, element types (same
 * as property types except for collections) or the declaring classes.
 *
 * @author  Martin Desruisseaux (Geomatys)
 * @version 0.3
 *
 * @see MetadataStandard#asTypeMap(Class, KeyNamePolicy, TypeValuePolicy)
 *
 * @since 0.3
 */
public enum TypeValuePolicy {
    /**
     * The type of a property as inferred from the return type of the property method defined in the interface.
     * The property type is the {@linkplain java.lang.reflect.Method#getReturnType()} except for the following
     * special cases:
     *
     * <ul>
     *   <li>{@link java.util.Optional} are replaced by the wrapped type.</li>
     *   <li>Values of type {@code double} (the primitive type) in
     *       {@link org.opengis.metadata.extent.GeographicBoundingBox} are wrapped in
     *       {@link org.apache.sis.measure.Longitude} and {@link org.apache.sis.measure.Latitude}
     *       objects instead of {@link Double}.</li>
     * </ul>
     *
     * Note that collections are not handled in any special way. If the return type is a collection,
     * then the property type is {@code Collection.class} or any other declared return type.
     */
    PROPERTY_TYPE,

    /**
     * The specialized type of a property, or type of elements if the property is a collection.
     * This is the same type as {@link #PROPERTY_TYPE} except for the following:
     *
     * <ul>
     *   <li>If the property is a collection, then the element type is the type of <em>elements</em> in that
     *       collection. For example if the property type is {@code Collection<String>}, then the element type
     *       is {@code String}.</li>
     *   <li>If the implementation declares a more specific property type than the interface (as allowed by
     *       <i>covariant return type</i>), then the element type will be that specialized type.</li>
     * </ul>
     */
    ELEMENT_TYPE,

    /**
     * The type of the interface that declares the method. For any metadata object, different
     * properties may have different declaring interfaces if some properties were inherited
     * from parent interfaces.
     */
    DECLARING_INTERFACE,

    /**
     * The type of the class that declares the method. This is similar to
     * {@link #DECLARING_INTERFACE}, except that the implementation class
     * from the metadata standard is returned instead of the interface.
     */
    DECLARING_CLASS
}
