~~
~~ 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.
~~

                             ------------------------------
                                        Overview
                             ------------------------------


Apache SIS Metadata

  Implementations of metadata derived from ISO 19115. This module provides both an implementation
  of the metadata interfaces defined in GeoAPI, and a framework for handling those metadata through
  Java reflection.

   * {{{http://sis.apache.org/faq.html#metadata}Frequently Asked Questions}}

   * {{{https://geo-ide.noaa.gov/wiki/index.php?title=Category:ISO_19115}ISO 19115 wiki at NOAA}}


* Overview of Metadata handling in Apache SIS

  Many metadata standards exist, including <Dublin core>, <ISO 19115> and the Image I/O metadata
  defined in <<<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.

  Metadata objects in SIS are mostly containers: they provide getter and setter methods for
  manipulating the values associated to properties (for example the <title> properties of an
  <Citation> object), but provide few logic. The package <<<org.apache.sis.metadata.iso>>> and
  its sub-packages are the main examples of such containers.

  In addition, the metadata modules provide support methods for handling the metadata objects
  through Java Reflection. This is an approach similar to <Java Beans>, in that users are encouraged
  to use directly the API of <Plain Old Java> objects (actually interfaces) everytime their type is
  known at compile time, and fallback on the reflection technic when the type is known only at runtime.
  Using Java reflection, a metadata can be viewed in many different ways:

   * As a <<<Map>>> (from <<<java.util>>>)

   * As a <<<TreeTable>>> (from <<<org.apache.sis.util.collection>>>)

   * As a <<<IIOMetadata>>> (from <<<javax.imageio.metadata>>>)

   * As a table record in a database (using <<<org.apache.sis.metadata.sql>>>)


** How Metadata are marshalled

  The ISO 19139 standard defines how ISO 19115 metadata shall be represented in XML.
  The SIS library supports XML marshalling and unmarshalling with JAXB annotations.

  Only the implementation classes defined in the <<<org.apache.sis.metadata.iso>>> packages
  are annotated for JAXB marshalling. If a metadata is implemented by an other package (for
  example <<<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.