/*
 * 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.
 */

/**
 * Defines the structure and content of views of real-world phenomenon.
 * The phenomenon to represent (or a fundamental unit of information) is called <cite>a feature</cite>.
 * The term “feature” may be used in different contexts:
 *
 * <ul class="verbose">
 *   <li><b>{@linkplain org.apache.sis.feature.DefaultFeatureType Feature types}</b><br>
 *       Define the <em>structure</em> of real-world representations. A feature type lists the
 *       {@linkplain org.apache.sis.feature.DefaultAttributeType attributes},
 *       {@linkplain org.apache.sis.feature.AbstractOperation operations} or
 *       {@linkplain org.apache.sis.feature.DefaultAssociationRole associations to other features}
 *       (collectively called “{@linkplain org.apache.sis.feature.DefaultFeatureType#getProperties(boolean) properties}”
 *       or “characteristics”) that a feature can have.
 *
 *       <div class="note"><b>Analogy:</b> a {@code FeatureType} in a Spatial Information System is equivalent to a
 *       {@link java.lang.Class} in the Java language. By extension, {@code AttributeType} and {@code Operation} are
 *       equivalent to {@link java.lang.reflect.Field} and {@link java.lang.reflect.Method} respectively.</div></li>
 *
 *   <li><b>{@linkplain org.apache.sis.feature.AbstractFeature Feature instances}</b> (often called only Features)<br>
 *       Hold the <em>content</em> (or values) that describe one specific real-world object.
 *
 *       <div class="note"><b>Example:</b> the “Eiffel tower” is a <em>feature instance</em> belonging
 *       to the “Tower” <em>feature type</em>.</div></li>
 *
 *   <li><b>{@linkplain org.apache.sis.feature.DefaultFeatureType#isSimple() Simple features}</b><br>
 *       Are instances of a feature type with no association to other features, and where all attributes
 *       have [1 … 1] multiplicity. Such simple features are very common.</li>
 * </ul>
 *
 * In addition, a feature type can inherit the properties of one or more other feature types.
 * Properties defined in the sub-type can override properties of the same name defined in the
 * {@linkplain org.apache.sis.feature.DefaultFeatureType#getSuperTypes() super-types}, provided
 * that values of the sub-type property are assignable to the super-type property.
 *
 * <h2>Naming</h2>
 * Each feature type has a {@linkplain org.apache.sis.feature.DefaultFeatureType#getName() name},
 * which should be unique. Those names are the main criterion used for checking if a feature type
 * {@linkplain org.apache.sis.feature.DefaultFeatureType#isAssignableFrom is assignable from} another type.
 * Names can be {@linkplain org.apache.sis.util.iso.DefaultScopedName scoped} for avoiding name collision.
 *
 * <h2>Class hierarchy</h2>
 * The class hierarchy for feature <cite>types</cite> is derived from ISO 19109 specification.
 * The class hierarchy for feature <cite>instances</cite> is closely related:
 *
 * <table class="sis">
 * <caption>Feature class hierarchy</caption>
 * <tr>
 *   <th>Types</th>
 *   <th class="sep">Instances</th>
 * </tr><tr><td style="width: 50%; white-space: nowrap">
 *                 {@linkplain org.apache.sis.feature.AbstractIdentifiedType  Identified type}<br>
 * {@code  ├─}     {@linkplain org.apache.sis.feature.DefaultFeatureType      Feature type}<br>
 * {@code  └─}                                                                Property type<br>
 * {@code      ├─} {@linkplain org.apache.sis.feature.DefaultAttributeType    Attribute type}<br>
 * {@code      ├─} {@linkplain org.apache.sis.feature.DefaultAssociationRole  Feature association role}<br>
 * {@code      └─} {@linkplain org.apache.sis.feature.AbstractOperation       Operation}<br>
 * </td><td class="sep" style="width: 50%; white-space: nowrap">
 *                 Object<br>
 * {@code  ├─}     {@linkplain org.apache.sis.feature.AbstractFeature     Feature}             (<cite>sparse</cite> or <cite>dense</cite>)<br>
 * {@code  └─}                                                            Property<br>
 * {@code      ├─} {@linkplain org.apache.sis.feature.AbstractAttribute   Attribute}           (<cite>singleton</cite> or <cite>multi-valued</cite>)<br>
 * {@code      └─} {@linkplain org.apache.sis.feature.AbstractAssociation Feature association} (<cite>singleton</cite> or <cite>multi-valued</cite>)<br>
 * </td></tr></table>
 *
 * <h2>Instantiation</h2>
 * Classes defined in this package are rarely instantiated directly (by a {@code new} statement).
 * Instead those classes are instantiated indirectly by invoking a method on a parent container,
 * or by using a builder. The starting point is {@code FeatureType}, which may be created by a
 * {@link org.apache.sis.feature.builder.FeatureTypeBuilder} or may be provided by a
 * {@link org.apache.sis.storage.DataStore} reading a data file.
 * Once a {@code FeatureType} has been obtained, {@code Feature}s can be instantiated by calls to the
 * {@link org.apache.sis.feature.DefaultFeatureType#newInstance() FeatureType.newInstance()} method.
 * Once a {@code Feature} instance has been obtained, {@code Attribute}s can be instantiated indirectly
 * by calls to the {@link org.apache.sis.feature.AbstractFeature#setPropertyValue Feature.setPropertyValue(…)} method.
 *
 * @author  Travis L. Pinney
 * @author  Johann Sorel (Geomatys)
 * @author  Martin Desruisseaux (Geomatys)
 * @version 1.0
 * @since   0.5
 * @module
 */
package org.apache.sis.feature;