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

/**
 * Root package for various metadata implementations.
 *
 * <div class="section">Foreword</div>
 * Many metadata standards exist, including <cite>Dublin core</cite>, <cite>ISO 19115</cite> and the Image I/O
 * metadata defined in {@link javax.imageio.metadata}. The SIS implementation focuses on ISO 19115 (including
 * its ISO 19115-2 extension), but the classes are designed in a way that allow the usage of different standards.
 * This genericity goal should be keep in mind in the discussion below.
 *
 * <div class="section">How Metadata are defined</div>
 * A metadata standard is defined by a set of Java interfaces belonging to a specific package and its sub-packages.
 * For example the ISO 19115 standard is defined by the <a href="http://www.geoapi.org">GeoAPI</a> interfaces
 * defined in the {@link org.opengis.metadata} package and sub-packages. That standard is identified in SIS by the
 * {@link org.apache.sis.metadata.MetadataStandard#ISO_19115} constant. Other standards are defined as well,
 * for example the {@link org.apache.sis.metadata.MetadataStandard#ISO_19123} constant stands for the standards
 * defined by the interfaces in the {@code org.opengis.coverage} package and sub-packages.
 *
 * <p>For each interface, the collection of declared getter methods defines its <cite>properties</cite>
 * (or <cite>attributes</cite>). If a {@link org.opengis.annotation.UML} annotation is attached to the getter method,
 * the identifier declared in that annotation is taken as the property name. This is typically the name defined by the
 * International Standard from which the interface is derived. Otherwise (if there is no {@code UML} annotation)
 * the property name is inferred from the method name like what the <cite>Java Beans</cite> framework does.</p>
 *
 * <p>The implementation classes, if they exist, are defined in different packages than the interfaces.
 * For example the ISO 19115 interfaces, declared in {@link org.opengis.metadata}, are implemented by
 * SIS in {@link org.apache.sis.metadata.iso}. The sub-packages hierarchy is the same, and the names
 * of implementation classes are the name of the implemented interfaces prefixed with {@code Abstract}
 * or {@code Default}.</p>
 *
 * <p><b>Notes:</b></p>
 * <ul class="verbose">
 *   <li>The {@code Abstract} prefix means that the class is abstract in the sense of the implemented standard.
 *       It it not necessarily abstract in the sense of Java. Because incomplete metadata are common in practice,
 *       sometime we wish to instantiate an "abstract" class despite the lack of knowledge about the exact sub-type.</li>
 *   <li>The properties are determined by the getter methods declared in the interfaces.
 *       Getter methods declared in the implementation classes are ignored.</li>
 *   <li>Setter methods, if any, can be declared in the implementation classes without the need for declarations
 *       in the interfaces. In other words, interfaces are assumed read-only unless a specific implementation provide
 *       setter methods.</li>
 *   <li>The implementation is not required to exist as source code. They can be generated on the fly with
 *       {@link java.lang.reflect.Proxy}. This is the approach taken by the {@link org.apache.sis.metadata.sql}
 *       package for generating metadata implementations backed by the content of a database.</li>
 * </ul>
 *
 * <div class="section">How Metadata are handled</div>
 * Metadata objects in SIS are mostly containers: they provide getter and setter methods for manipulating the values
 * associated to properties (for example the {@code title} property of a {@code Citation} object), but provide few logic.
 * The package {@link org.apache.sis.metadata.iso} and its sub-packages are the main examples of such containers.
 *
 * <p>In addition, the metadata modules provide support methods for handling the metadata objects through Java Reflection.
 * This is an approach similar to <cite>Java Beans</cite>, in that users are encouraged to use directly the API of
 * <cite>Plain Old Java</cite> objects (actually interfaces) every time their type is known at compile time,
 * and fallback on the reflection technic when the type is known only at runtime.</p>
 *
 * <p>Using Java reflection, a metadata can be viewed in many different ways:</p>
 * <ul class="verbose">
 *   <li><b>As a {@link java.util.Map}</b><br>
 *       The {@link org.apache.sis.metadata.MetadataStandard} class provides various methods returning a view
 *       of an arbitrary metadata implementation as a {@code Map}, where the key are the property names and the
 *       values are the return values, types or descriptions of getter methods. The map is writable if the
 *       underlying metadata implementation has setter methods, otherwise attempts to set a value throw an
 *       {@code UnmodifiableMetadataException}.</li>
 *
 *   <li><b>As a {@link org.apache.sis.util.collection.TreeTable}</b><br>
 *       The metadata are organized as a tree. For example the {@code Citation} metadata contains one or many
 *       {@code ResponsibleParty} elements, each of them containing a {@code Contact} element, which contains
 *       a {@code Telephone} element, <i>etc</i>. For each node, there is many information that can be displayed
 *       in columns:
 *       <ul>
 *         <li>A description of the element.</li>
 *         <li>The type of values ({@code String}, {@code double}, <i>etc</i>).</li>
 *         <li>The range of valid values (if the type is numeric),
 *             or an enumeration of valid values (if the type is a code list).</li>
 *         <li>The value stored in the element, or the default value.</li>
 *       </ul></li>
 *
 *   <li><b>As a table record in a database (using {@link org.apache.sis.metadata.sql})</b><br>
 *       It is possible to establish the following mapping between metadata and a SQL database:
 *       <ul>
 *         <li>Each metadata interface maps to a table of the same name in the database.</li>
 *         <li>Each property in the above interface maps to a column of the same name in the above table.</li>
 *         <li>Each instance of the above interface is a record in the above table.</li>
 *       </ul>
 *       Using Java reflection, it is possible to generate implementations of the metadata interfaces
 *       where each call to a getter method is translated into a SQL query for the above database.</li>
 * </ul>
 *
 * <div class="section">How Metadata are marshalled</div>
 * The ISO 19115-3 standard defines how ISO 19115-1 metadata shall be represented in XML.
 * The SIS library supports XML marshalling and unmarshalling with JAXB annotations.
 *
 * <p>Only the implementation classes defined in the {@link org.apache.sis.metadata.iso} packages and sub-packages
 * are annotated for JAXB marshalling. If a metadata is implemented by an other package (for example
 * {@link org.apache.sis.metadata.sql}), then it shall be converted to an annotated class before to be marshalled.
 * All SIS annotated classes provide a copy constructor for this purpose. A shallow copy is sufficient;
 * JAXB adapters will convert the elements on-the-fly when needed.</p>
 *
 * <p>The annotated classes can be given to a JAXB {@code Marshaller}. For best results, it shall be a marshaller
 * obtained from the {@link org.apache.sis.xml.MarshallerPool}, otherwise some XML outputs may be incomplete
 * (missing namespaces for instance). The {@link org.apache.sis.xml.XML} class provides convenience methods
 * for this purpose.</p>
 *
 * @author  Martin Desruisseaux (IRD, Geomatys)
 * @author  Adrian Custer (Geomatys)
 * @version 1.0
 * @since   0.3
 * @module
 */
package org.apache.sis.metadata;