This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sis-site.git
commit 729e122bc084a2892cf62b9a6bd17884e89b84bf
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Fri Nov 17 16:30:00 2023 +0100
Reorganize and develop the discussion about metadata and nil values.
---
content/developer-guide/geometry/Envelope.html | 2 +-
.../developer-guide/introduction/DataAccess.html | 98 ++++-------
.../metadata/GetMetadataElement.html | 91 -----------
.../developer-guide/metadata/NavigateMetadata.html | 180 +++++++++++++++++++++
content/developer-guide/metadata/NilReason.html | 68 ++++++++
content/developer-guide/metadata/index.html | 105 +++++++++++-
content/developer-guide/xml/ISO-19115.html | 20 +--
static/book/book.css | 3 +-
8 files changed, 387 insertions(+), 180 deletions(-)
diff --git a/content/developer-guide/geometry/Envelope.html
b/content/developer-guide/geometry/Envelope.html
index 9ec48bac..61bf1f4f 100644
--- a/content/developer-guide/geometry/Envelope.html
+++ b/content/developer-guide/geometry/Envelope.html
@@ -92,7 +92,7 @@
This case is illustrated by the red rectangle in the figure below.
</p>
<p style="text-align:center">
- <img
src="../../apidocs/org/apache/sis/geometry/doc-files/AntiMeridian.png"
+ <img
src="../../apidocs/org.apache.sis.referencing/org/apache/sis/geometry/doc-files/AntiMeridian.png"
alt="Envelope example with and without anti-meridian spanning."/>
</p>
<p>
diff --git a/content/developer-guide/introduction/DataAccess.html
b/content/developer-guide/introduction/DataAccess.html
index c09b283e..f7039a12 100644
--- a/content/developer-guide/introduction/DataAccess.html
+++ b/content/developer-guide/introduction/DataAccess.html
@@ -58,35 +58,41 @@
legal or technical constraints on data usage,
the history of processing apply on the data,
expected updates schedule, <i>etc.</i>
- </p><p>
- Various data formats have their own metadata model, but Apache
<abbr>SIS</abbr> translates all of them
+ The metadata structures depends on the data formats, but Apache
<abbr>SIS</abbr> translates all of them
in a unique metadata model in order to hide this heterogeneity.
This <em>pivot model</em> approach is often used by various libraries,
with Dublin Core as a popular choice.
For Apache <abbr>SIS</abbr>, the chosen pivot model is the
<abbr>ISO</abbr> 19115 international standard.
- This model organizes metadata in a tree structure where each
information is accessible by a well-defined path,
- regardless the origin of that information.
+ This model organizes metadata in a tree structure.
For example if a data format can provides a geographic bounding box
encompassing all data,
then that information will always be accessible (regardless the data
format) from the root <code>Metadata</code> object
- under the <code class="OGC">identificationInfo</code> node, <code
class="OGC">extent</code> sub-node,
- <code class="OGC">geographicElement</code> sub-node.
+ under the <code class="OGC">identificationInfo</code> node, then the
<code class="OGC">extent</code> sub-node,
+ and finally the <code class="OGC">geographicElement</code> sub-node.
+ For example, the following code read a metadata file from a Landsat-8
image and prints the declared geographic bounding box:
</p>
- <div class="example"><p><b>Example:</b>
- following code read a metadata file from a Landsat-8 image and
prints the declared geographic bounding box:
- </p>
-<pre><code>try (DataStore store = DataStores.open(new
File("LC81230522014071LGN00_MTL.txt"))) {
- Metadata overview = store.<code class="SIS">getMetadata()</code>;
+<pre><code>
+import org.opengis.metadata.Metadata;
+import org.opengis.metadata.extent.GeographicBoundingBox;
+import org.apache.sis.storage.DataStore;
+import org.apache.sis.storage.DataStores;
+import org.apache.sis.storage.DataStoreException;
+import org.apache.sis.metadata.iso.extent.Extents;
+
+void main() throws DataStoreException {
+ try (DataStore store = DataStores.open(new
File("LC81230522014071LGN00_MTL.txt"))) {
+ Metadata overview = store.<code class="SIS">getMetadata()</code>;
- // Convenience method for fetching the geographic bounding box at the
right location in metadata tree.
- GeographicBoundingBox bbox = <code
class="SIS">Extents.getGeographicBoundingBox</code>(overview);
+ // Convenience method for fetching value at the
"metadata/identificationInfo/geographicElement" path.
+ GeographicBoundingBox bbox = <code
class="SIS">Extents.getGeographicBoundingBox</code>(overview);
- System.out.println("The geographic bounding box is:");
- System.out.println(bbox);
+ System.out.println("The geographic bounding box is:");
+ System.out.println(bbox);
+ }
}</code></pre>
- <p>
- This example produces the following output (this area is located in
Vietnam):
- </p>
+ <p>
+ Above example produces the following output (this area is located in
Vietnam):
+ </p>
<pre><samp>The geographic bounding box is:
Geographic Bounding Box
@@ -94,64 +100,16 @@ Geographic Bounding Box
├─East bound longitude…………………………… 110°26′39.66″E
├─South bound latitude…………………………… 10°29′59.604″N
└─North bound latitude…………………………… 12°37′25.716″N</samp></pre>
- </div>
-
- <p>
- The <abbr>ISO</abbr> 19115 standard defines hundreds of elements.
- Some of them will be introduced progressively in next chapters.
- But in order to give some idea about what is available, the following
table lists a few metadata elements.
- Most of the nodes accept an arbitrary number of values.
- For example the <code class="OGC">extent</code> node may contain many
geographic areas.
- </p>
- <table class="monospacedHeaderColumn" style="font-size:0.82vw">
- <caption>Extract of a few metadata elements from ISO 19115</caption>
- <tr><th>Element</th>
<th>Description</th></tr>
- <tr><td style="padding-top:9px">Metadata</td> <td
style="padding-top:9px">Metadata about a dataset, service or other
resources.</td></tr>
- <tr><td> ├─Reference system info</td> <td>Description of
the spatial and temporal reference systems used in the dataset.</td></tr>
- <tr><td> ├─Identification info</td> <td>Basic
information about the resource(s) to which the metadata applies.</td></tr>
- <tr><td> │ ├─Citation</td> <td>Name by which
the cited resource is known, reference dates, presentation form,
<i>etc.</i></td></tr>
- <tr><td> │ │ └─Cited responsible party</td> <td>Role, name,
contact and position information for individuals or organizations that are
responsible for the resource.</td></tr>
- <tr><td> │ ├─Topic category</td> <td>Main theme(s)
of the resource (e.g. farming, climatology, environment, economy, health,
transportation, <i>etc.</i>).</td></tr>
- <tr><td> │ ├─Descriptive keywords</td> <td>Category
keywords, their type, and reference source.</td></tr>
- <tr><td> │ ├─Spatial resolution</td> <td>Factor which
provides a general understanding of the density of spatial data in the
resource.</td></tr>
- <tr><td> │ ├─Temporal resolution</td> <td>Smallest
resolvable temporal period in a resource.</td></tr>
- <tr><td> │ ├─Extent</td> <td>Spatial and
temporal extent of the resource.</td></tr>
- <tr><td> │ ├─Resource format</td> <td>Description of
the format of the resource(s).</td></tr>
- <tr><td> │ ├─Resource maintenance</td> <td>Information
about the frequency of resource updates, and the scope of those
updates.</td></tr>
- <tr><td> │ └─Resource constraints</td> <td>Information
about constraints (legal or security) which apply to the resource(s).</td></tr>
- <tr><td> ├─Content info</td> <td>Information
about the feature catalog and describes the coverage and image data
characteristics.</td></tr>
- <tr><td> │ ├─Imaging condition</td> <td>Conditions
which affected the image (e.g. blurred image, fog, semi darkness,
<i>etc.</i>).</td></tr>
- <tr><td> │ ├─Cloud cover percentage</td> <td>Area of the
dataset obscured by clouds, expressed as a percentage of the spatial
extent.</td></tr>
- <tr><td> │ └─Attribute group</td> <td>Information on
attribute groups of the resource.</td></tr>
- <tr><td> │ ├─Content type</td> <td>Types of
information represented by the values (e.g. thematic classification, physical
measurement, <i>etc.</i>).</td></tr>
- <tr><td> │ └─Attribute</td> <td>Information on
an attribute of the resource.</td></tr>
- <tr><td> │ ├─Sequence identifier</td> <td>Unique name or
number that identifies attributes included in the coverage.</td></tr>
- <tr><td> │ ├─Peak response</td> <td>Wavelength at
which the response is the highest.</td></tr>
- <tr><td> │ ├─Min/max value</td>
<td>Minimum/maximum value of data values in each sample dimension included in
the resource.</td></tr>
- <tr><td> │ ├─Units</td> <td>Units of data
in each dimension included in the resource.</td></tr>
- <tr><td> │ └─Transfer function type</td> <td>Type of
transfer function to be used when scaling a physical value for a given
element.</td></tr>
- <tr><td> ├─Distribution info</td> <td>Information
about the distributor of and options for obtaining the resource(s).</td></tr>
- <tr><td> │ ├─Distribution format</td> <td>Description of
the format of the data to be distributed.</td></tr>
- <tr><td> │ └─Transfer options</td> <td>Technical
means and media by which a resource is obtained from the distributor.</td></tr>
- <tr><td> ├─Data quality info</td> <td>Overall
assessment of quality of a resource(s).</td></tr>
- <tr><td> ├─Acquisition information</td> <td>Information
about the acquisition of the data.</td></tr>
- <tr><td> │ ├─Environmental conditions</td> <td>Record of the
environmental circumstances during the data acquisition.</td></tr>
- <tr><td> │ └─Platform</td> <td>General
information about the platform from which the data were taken.</td></tr>
- <tr><td> │ └─Instrument</td> <td>Instrument(s)
mounted on a platform.</td></tr>
- <tr><td> └─Resource lineage</td> <td>Information
about the provenance, sources and/or the production processes applied to the
resource.</td></tr>
- <tr><td> ├─Source</td> <td>Information
about the source data used in creating the data specified by the
scope.</td></tr>
- <tr><td> └─Process step</td> <td>Information
about events in the life of a resource specified by the scope.</td></tr>
- </table>
<p>
- Among metadata elements introduced in this chapter, there is one which
will be the topic of
+ Metadata are covered in more details in a <a href="#Metadata">latter
chapter</a>.
+ Among metadata elements, there is one which will be the topic of
a <a href="#Referencing">dedicated chapter</a>: <code
class="OGC">referenceSystemInfo</code>.
Its content is essential for accurate data positioning;
without this element, even positions given by latitudes and longitudes
are ambiguous.
Reference systems have many characteristics that make them apart from
other metadata:
- they are immutable, cannot be handled by <code
class="SIS">MetadataStandard.ISO_19115.asValueMap(…)</code>,
- have a particular text representation and are associated to an engine
- performing coordinate transformation from one reference system to
another.
+ they are immutable, have a particular Well-Known Text representation
and are associated
+ to an engine performing coordinate transformation from one reference
system to another.
</p>
</section>
</body>
diff --git a/content/developer-guide/metadata/GetMetadataElement.html
b/content/developer-guide/metadata/GetMetadataElement.html
deleted file mode 100644
index ef2aa3c9..00000000
--- a/content/developer-guide/metadata/GetMetadataElement.html
+++ /dev/null
@@ -1,91 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE html>
-
-<!--
- 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.
--->
-
-<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en">
- <head>
- <title>GetMetadataElement</title>
- <meta charset="UTF-8"/>
- <link rel="stylesheet" type="text/css" href="../book.css"/>
- </head>
- <body>
- <!--
- Content below this point is copied in
"/asf-staging/book/en/developer-guide.html" file
- by the `org.apache.sis.buildtools.book` class in `buildSrc`.
- -->
- <section>
- <header>
- <h2 id="GetMetadataElement">Navigating in metadata elements</h2>
- </header>
- <p>
- Methods like <code class="GeoAPI">getExtents()</code> are efficient
when looking for a particular element known at compile-time.
- But those elements may be deep in the tree structure and may require
traversal of many optional elements and collection members,
- which is sometimes tedious. For a few frequently-used elements, some
convenience methods are provided.
- Those conveniences are generally defined as static methods in classes
having a name in plural form.
- For example the <code>Extents</code> class defines static methods for
fetching more easily some information from <code>Extent</code> metadata
elements.
- For example the following method navigates through different branches
where North, South, East and West data bounds may be found:
- </p>
- <pre><code>GeographicBoundingBox bbox =
Extents.getGeographicBoundingBox(extent);</code></pre>
- <p>
- Those conveniences are defined as static methods in order to allow
their use with different metadata implementations.
- Some other classes providing static methods for specific interfaces are
- <code>Citations</code>, <code>Envelopes</code>, <code>Matrices</code>
and <code>MathTransforms</code>.
- </p>
-
- <h3 id="MetadataAsMap">View as key-value pairs</h3>
- <p>
- Above static methods explore fragments of metadata tree in search for
requested information,
- but the searches are still targeted to elements whose types and at
least part of their paths are known at compile-time.
- Sometimes the element to search is known only at runtime, or sometimes
there is a need to iterate over all elements.
- In such cases, one can view the metadata as a
<code>java.util.Map</code> like below:
- </p>
-
-<pre><code>Map<String,Object> elements =
MetadataStandard.ISO_19115.asValueMap(
- metadata, // Any instance from the
org.opengis.metadata package or a sub-package.
- null, // Used for resolving ambiguities.
We can ignore for this example.
- KeyNamePolicy.JAVABEANS_PROPERTY, // Keys in the map will be getter
method names without "get" prefix.
- ValueExistencePolicy.NON_EMPTY); // Entries with null or empty
values will be omitted.
-/*
- * Print the names of all root metadata elements having a value.
- * This loop does not iterate recursively in children.
- */
-for (String name : elements.keySet()) {
- System.out.println(name);
-}</code></pre>
-
- <p>
- The <code>Map</code> object returned by <code
class="SIS">asValueMap(…)</code> is live:
- any change in the <code>metadata</code> instance will be immediately
reflected in the view.
- Actually, each <code>map.get("foo")</code> call is forwarded to the
corresponding <code>metadata.getFoo()</code> method.
- Conversely, any <code>map.put("foo", …)</code> or
<code>map.remove("foo")</code> operation applied on the view
- will be forwarded to the corresponding <code>metadata.setFoo(…)</code>
method, if that method exists.
- The view is lenient regarding keys given in arguments to
<code>Map</code> methods:
- keys may be property names (<code>"foo"</code>), method names
(<code>"getFoo"</code>),
- or names used in <abbr>ISO</abbr> 19115 standard <abbr>UML</abbr>
diagrams
- (similar to property names but not always identical).
- Differences in upper cases and lower cases are ignored when this
tolerance does not introduce ambiguities.
- For more information on metadata views, see
- <a
href="../../apidocs/org/apache/sis/metadata/package-summary.html#package.description"><code>org.apache.sis.metadata</code></a>
- package javadoc.
- </p>
- </section>
- </body>
-</html>
diff --git a/content/developer-guide/metadata/NavigateMetadata.html
b/content/developer-guide/metadata/NavigateMetadata.html
new file mode 100644
index 00000000..a8883b06
--- /dev/null
+++ b/content/developer-guide/metadata/NavigateMetadata.html
@@ -0,0 +1,180 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ 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.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en">
+ <head>
+ <title>NavigateMetadata</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in
"/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.buildtools.book` class in `buildSrc`.
+ -->
+ <section>
+ <header>
+ <h2 id="NavigateMetadata">Navigating in metadata elements</h2>
+ </header>
+ <p>
+ 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
+ Plain Old Java objects every time their type is known at compile time,
+ and fallback on the reflection technic when the type is known only at
runtime.
+ When using Java reflection, a metadata can be viewed in different ways:
+ </p>
+ <ul>
+ <li>As key-value pairs in a <code>Map</code> (from
<code>java.util</code>).</li>
+ <li>As a <code>TreeTable</code> (from
<code>org.apache.sis.util.collection</code>).</li>
+ <li>As a table record in a database (using
<code>org.apache.sis.metadata.sql</code>).</li>
+ <li>As an <abbr>XML</abbr> document conforms to <abbr>ISO</abbr>
standard schema.</li>
+ </ul>
+ <p>
+ The use of reflection is described <a href="#MetadataAsMap">below</a>.
+ The <abbr>XML</abbr> representation is described in a <a
href="#XML-ISO-19115">separated chapter</a>.
+ </p>
+
+ <h3 id="GetMetadataElement">Direct access via getter methods</h3>
+ <p>
+ All metadata classes provide getter, and sometime setter, methods for
their properties.
+ Some properties accept many values, in which case the property type is
a collection.
+ The following example prints the range of latitudes of all data
descriptions
+ found in a given root <code>Metadata</code> object:
+ </p>
+
+<pre><code>
+import org.opengis.metadata.metadata;
+import org.opengis.metadata.extent.Extent;
+import org.opengis.metadata.extent.GeographicExtent;
+import org.opengis.metadata.extent.GeographicBoundingBox;
+import org.opengis.metadata.identification.Identification;
+import org.opengis.metadata.identification.DataIdentification;
+
+void main() {
+ Metadata metadata = ...; // For example, metadata read from a data
store.
+ for (Identification identification : metadata.getIdentificationInfo()) {
+ if (identification instanceof DataIdentification data) {
+ for (Extent extent : data.getExtents()) {
+ // Extents may have horizontal, vertical and temporal
components.
+ for (GeographicExtent horizontal :
extent.getGeographicElements()) {
+ if (horizontal instanceof GeographicBoundingBox bbox) {
+ double south = bbox.getSouthBoundLatitude();
+ double north = bbox.getNorthBoundLatitude();
+ System.out.println("Latitude range: " + south + " to "
+ north);
+ }
+ }
+ }
+ }
+ }
+}</code></pre>
+
+ <p>
+ Because of <abbr>ISO</abbr> 19115 richness, interesting information
may be buried deeply in the metadata tree, as in above example.
+ For a few frequently-used elements, some convenience methods are
provided.
+ Those conveniences are generally defined as static methods in classes
having a name in plural form.
+ For example the <code>Extents</code> class defines static methods for
fetching more easily some information from <code>Extent</code> metadata
elements.
+ For example the following method navigates through different branches
where North, South, East and West data bounds may be found:
+ </p>
+
+<pre><code>
+import org.opengis.metadata.metadata;
+import org.opengis.metadata.extent.GeographicBoundingBox;
+import org.apache.sis.metadata.iso.extent.Extents;
+
+void main() {
+ Metadata metadata = ...; // For example, metadata read from a data
store.
+ GeographicBoundingBox bbox = Extents.getGeographicBoundingBox(extent);
+}</code></pre>
+
+ <p>
+ Those conveniences are defined as static methods in order to allow
their use with different metadata implementations.
+ Some other classes providing static methods for specific interfaces are
+ <code>Citations</code>, <code>Envelopes</code>, <code>Matrices</code>
and <code>MathTransforms</code>.
+ </p>
+
+ <h3 id="MetadataAsMap">View as key-value pairs</h3>
+ <p>
+ Above static methods explore fragments of metadata tree in search for
requested information,
+ but the searches are still targeted to elements whose types and at
least part of their paths are known at compile-time.
+ Sometimes the element to search is known only at runtime, or sometimes
there is a need to iterate over all elements.
+ In such cases, one can view the metadata as a
<code>java.util.Map</code> like below:
+ </p>
+
+<pre><code>
+import java.util.Map;
+import org.apache.sis.metadata.MetadataStandard;
+import org.apache.sis.metadata.KeyNamePolicy;
+import org.apache.sis.metadata.ValueExistencePolicy;
+
+void main() {
+ Map<String,Object> elements = MetadataStandard.ISO_19115.asValueMap(
+ metadata, // Any instance from the
org.opengis.metadata package or a sub-package.
+ null, // Used for resolving
ambiguities. We can ignore for this example.
+ KeyNamePolicy.JAVABEANS_PROPERTY, // Keys in the map will be
getter method names without "get" prefix.
+ ValueExistencePolicy.NON_EMPTY); // Entries with null or empty
values will be omitted.
+
+ // Print the names of all root metadata elements having a value.
+ for (String name : elements.keySet()) {
+ System.out.println(name);
+ }
+}</code></pre>
+
+ <p>
+ The <code>Map</code> object returned by <code
class="SIS">asValueMap(…)</code> is live:
+ any change in the <code>metadata</code> instance will be immediately
reflected in the view.
+ Actually, each <code>map.get("foo")</code> call is forwarded to the
corresponding <code>metadata.getFoo()</code> method.
+ Conversely, any <code>map.put("foo", …)</code> or
<code>map.remove("foo")</code> operation applied on the view
+ will be forwarded to the corresponding <code>metadata.setFoo(…)</code>
method, if that method exists.
+ The view is lenient regarding keys given in arguments to
<code>Map</code> methods:
+ keys may be property names (<code>"foo"</code>), method names
(<code>"getFoo"</code>),
+ or names used in <abbr>ISO</abbr> 19115 standard <abbr>UML</abbr>
diagrams
+ (similar to property names but not always identical).
+ Differences in upper cases and lower cases are ignored when this
tolerance does not introduce ambiguities.
+ For more information on metadata views, see
+ <a
href="../../apidocs/org.apache.sis.metadata/org/apache/sis/metadata/package-summary.html#package.description"><code>org.apache.sis.metadata</code></a>
+ package javadoc.
+ </p>
+
+ <h3 id="MetadataAsTreeTable">View as tree table</h3>
+ <p>
+ A richer alternative to the view as a map is the view as a tree table.
+ With this view, the metadata structure is visible as a tree,
+ and each tree node is a table row with the following columns:
+ </p>
+ <table>
+ <caption>Columns of a tree table view of a metadata</caption>
+ <tr><th>Column</th> <th>Description</th></tr>
+ <tr><td><code class="SIS">IDENTIFIER</code></td> <td>The UML
identifier if any, or otherwise the Java Beans name, of the metadata
property.</td></tr>
+ <tr><td><code class="SIS">INDEX</code></td> <td>If the property
is a collection, then the zero-based index of the element in that
collection.</td></tr>
+ <tr><td><code class="SIS">NAME</code></td> <td>A human-readable
name for the node, derived from above identifier and index.</td></tr>
+ <tr><td><code class="SIS">TYPE</code></td> <td>The base type of
the value (usually a GeoAPI interface).</td></tr>
+ <tr><td><code class="SIS">VALUE</code></td> <td>The metadata
value for the node. This column may be writable.</td></tr>
+ <tr><td><code class="SIS">NIL_REASON</code></td> <td>If the value is
mandatory and nevertheless absent, the reason why.</td></tr>
+ <tr><td><code class="SIS">REMARKS</code></td> <td>Remarks or
warning on the property value.</td></tr>
+ </table>
+ <p>
+ Tree table views are obtained in a way similar to <a
href="#MetadataAsMap">map views</a>,
+ but using the <code class="SIS">asTreeTable(Object)</code> method
instead of <code class="SIS">asValueMap(Object)</code>.
+ </p>
+ </section>
+ </body>
+</html>
diff --git a/content/developer-guide/metadata/NilReason.html
b/content/developer-guide/metadata/NilReason.html
new file mode 100644
index 00000000..274da300
--- /dev/null
+++ b/content/developer-guide/metadata/NilReason.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+ 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.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en">
+ <head>
+ <title>NilReason</title>
+ <meta charset="UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="../book.css"/>
+ </head>
+ <body>
+ <!--
+ Content below this point is copied in
"/asf-staging/book/en/developer-guide.html" file
+ by the `org.apache.sis.buildtools.book` class in `buildSrc`.
+ -->
+ <section>
+ <header>
+ <h2 id="NilReason">Nil values in mandatory properties</h2>
+ </header>
+ <p>
+ Apache <abbr>SIS</abbr> allows any metadata property to be
<code>null</code>
+ (for values that are not collections) or an empty collection.
+ However, <abbr>ISO</abbr> 19115 defines some properties as mandatory.
+ For example, the <code class="OGC">title</code> of a
<code>Citation</code> is mandatory,
+ while the <code class="OGC">edition</code> is optional.
+ Apache <abbr>SIS</abbr> will not raise any warning or error if a
mandatory property is missing.
+ But for strict <abbr>ISO</abbr> compliance, the reason why the
property is missing should be provided.
+ Predefined reasons are:
+ </p>
+ <table>
+ <caption>Predefined nil reasons from <abbr>ISO</abbr> 19115-3</caption>
+ <tr><th>Reason</th> <th>Explanation</th></tr>
+ <tr><td><code class="OGC">inapplicable</code></td> <td>The property is
not applicable.</td></tr>
+ <tr><td><code class="OGC">unknown</code></td> <td>The value
probably exists but is not known.</td></tr>
+ <tr><td><code class="OGC">missing</code></td> <td>The value
cannot exist.</td></tr>
+ <tr><td><code class="OGC">withheld</code></td> <td>The value
cannot be revealed.</td></tr>
+ <tr><td><code class="OGC">template</code></td> <td>The value will
be available later.</td></tr>
+ </table>
+ <p>
+ The transmission of this information requires the use of a non-null
object, even when the value is missing.
+ In such case, <abbr>SIS</abbr> will return an object that, besides
implementing the desired GeoAPI interface,
+ also implements the <code>org.apache.sis.xml.NilObject</code>
interface.
+ This interface flags the instances where all methods return an empty
collection, an empty table, <code>null</code>,
+ <code>NaN</code>, <code>0</code> or <code>false</code>, in this
preference order, as permitted by the return types of the methods.
+ Each instance that implements <code>NilObject</code> provides a <code
class="SIS">getNilReason()</code> method
+ indicating why the object is nil.
+ </p>
+ </section>
+ </body>
+</html>
diff --git a/content/developer-guide/metadata/index.html
b/content/developer-guide/metadata/index.html
index 7ebb5a6e..a6e811b0 100644
--- a/content/developer-guide/metadata/index.html
+++ b/content/developer-guide/metadata/index.html
@@ -35,8 +35,111 @@
<header>
<h1 id="Metadata">Metadata</h1>
</header>
+ <p>
+ Many metadata standards exist, including Dublin core, <abbr>ISO</abbr>
19115
+ and the Image I/O metadata defined in the
<code>javax.imageio.metadata</code> package.
+ Apache <abbr>SIS</abbr> uses the <abbr>ISO</abbr> 19115 series of
standards as the pivotal metadata structure,
+ and converts other metadata structures to <abbr>ISO</abbr> 19115 when
needed.
+ The <abbr>ISO</abbr> 19115 standard defines hundreds of metadata
elements,
+ but the following table gives an overview with a few of them.
+ Note that most of the nodes accept an arbitrary number of values.
+ For example the <code class="OGC">extent</code> node may contain many
geographic areas.
+ </p>
- <xi:include href="GetMetadataElement.html"/>
+ <table class="monospacedHeaderColumn" style="font-size:0.82vw">
+ <caption>Extract of a few metadata elements from ISO 19115</caption>
+ <tr><th>Element</th>
<th>Description</th></tr>
+ <tr><td style="padding-top:9px">Metadata</td> <td
style="padding-top:9px">Metadata about a dataset, service or other
resources.</td></tr>
+ <tr><td> ├─Reference system info</td> <td>Description of
the spatial and temporal reference systems used in the dataset.</td></tr>
+ <tr><td> ├─Identification info</td> <td>Basic
information about the resource(s) to which the metadata applies.</td></tr>
+ <tr><td> │ ├─Citation</td> <td>Name by which
the cited resource is known, reference dates, presentation form,
<i>etc.</i></td></tr>
+ <tr><td> │ │ └─Cited responsible party</td> <td>Role, name,
contact and position information for individuals or organizations that are
responsible for the resource.</td></tr>
+ <tr><td> │ ├─Topic category</td> <td>Main theme(s)
of the resource (e.g. farming, climatology, environment, economy, health,
transportation, <i>etc.</i>).</td></tr>
+ <tr><td> │ ├─Descriptive keywords</td> <td>Category
keywords, their type, and reference source.</td></tr>
+ <tr><td> │ ├─Spatial resolution</td> <td>Factor which
provides a general understanding of the density of spatial data in the
resource.</td></tr>
+ <tr><td> │ ├─Temporal resolution</td> <td>Smallest
resolvable temporal period in a resource.</td></tr>
+ <tr><td> │ ├─Extent</td> <td>Spatial and
temporal extent of the resource.</td></tr>
+ <tr><td> │ ├─Resource format</td> <td>Description of
the format of the resource(s).</td></tr>
+ <tr><td> │ ├─Resource maintenance</td> <td>Information
about the frequency of resource updates, and the scope of those
updates.</td></tr>
+ <tr><td> │ └─Resource constraints</td> <td>Information
about constraints (legal or security) which apply to the resource(s).</td></tr>
+ <tr><td> ├─Content info</td> <td>Information
about the feature catalog and describes the coverage and image data
characteristics.</td></tr>
+ <tr><td> │ ├─Imaging condition</td> <td>Conditions
which affected the image (e.g. blurred image, fog, semi darkness,
<i>etc.</i>).</td></tr>
+ <tr><td> │ ├─Cloud cover percentage</td> <td>Area of the
dataset obscured by clouds, expressed as a percentage of the spatial
extent.</td></tr>
+ <tr><td> │ └─Attribute group</td> <td>Information on
attribute groups of the resource.</td></tr>
+ <tr><td> │ ├─Content type</td> <td>Types of
information represented by the values (e.g. thematic classification, physical
measurement, <i>etc.</i>).</td></tr>
+ <tr><td> │ └─Attribute</td> <td>Information on
an attribute of the resource.</td></tr>
+ <tr><td> │ ├─Sequence identifier</td> <td>Unique name or
number that identifies attributes included in the coverage.</td></tr>
+ <tr><td> │ ├─Peak response</td> <td>Wavelength at
which the response is the highest.</td></tr>
+ <tr><td> │ ├─Min/max value</td>
<td>Minimum/maximum value of data values in each sample dimension included in
the resource.</td></tr>
+ <tr><td> │ ├─Units</td> <td>Units of data
in each dimension included in the resource.</td></tr>
+ <tr><td> │ └─Transfer function type</td> <td>Type of
transfer function to be used when scaling a physical value for a given
element.</td></tr>
+ <tr><td> ├─Distribution info</td> <td>Information
about the distributor of and options for obtaining the resource(s).</td></tr>
+ <tr><td> │ ├─Distribution format</td> <td>Description of
the format of the data to be distributed.</td></tr>
+ <tr><td> │ └─Transfer options</td> <td>Technical
means and media by which a resource is obtained from the distributor.</td></tr>
+ <tr><td> ├─Data quality info</td> <td>Overall
assessment of quality of a resource(s).</td></tr>
+ <tr><td> ├─Acquisition information</td> <td>Information
about the acquisition of the data.</td></tr>
+ <tr><td> │ ├─Environmental conditions</td> <td>Record of the
environmental circumstances during the data acquisition.</td></tr>
+ <tr><td> │ └─Platform</td> <td>General
information about the platform from which the data were taken.</td></tr>
+ <tr><td> │ └─Instrument</td> <td>Instrument(s)
mounted on a platform.</td></tr>
+ <tr><td> └─Resource lineage</td> <td>Information
about the provenance, sources and/or the production processes applied to the
resource.</td></tr>
+ <tr><td> ├─Source</td> <td>Information
about the source data used in creating the data specified by the
scope.</td></tr>
+ <tr><td> └─Process step</td> <td>Information
about events in the life of a resource specified by the scope.</td></tr>
+ </table>
+
+ <p>
+ The ISO 19115 standard is reified by the <a
href="http://www.geoapi.org";>GeoAPI</a> interfaces
+ defined in the <code>org.opengis.metadata</code> package and
sub-packages.
+ For each interface, the collection of declared getter methods defines
its <dfn>properties</dfn> (or <dfn>attributes</dfn>).
+ The implementation classes are defined in the
<code>org.apache.sis.metadata.iso</code> package and sub-packages.
+ The sub-packages hierarchy is the same as GeoAPI,
+ and the names of implementation classes are the name of the GeoAPI
interfaces
+ prefixed with <code>Abstract</code> or <code>Default</code>. In this
context,
+ the <code>Abstract</code> 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,
+ sometimes an "abstract" class may be instantiated because of the lack
of knowledge about the exact sub-type.
+ A metadata instance (abstract or not) may also have missing values for
properties considered as mandatory.
+ The latter case is handled by <a href="#NilReason">nil reasons</a>.
+ </p><p>
+ A metadata may be created programmatically like below:
+ </p>
+
+<pre><code>
+import org.apache.sis.metadata.iso.citation.DefaultCitation;
+import org.opengis.metadata.citation.PresentationForm;
+
+void main() {
+ // Convenience constructor setting the "title" property to the given value.
+ var citation = new DefaultCitation("Map of Antarctica");
+ citation.getPresentationForms().add(PresentationForm.DOCUMENT_HARDCOPY);
+
+ // The following code prints "Map of Antarctica".
+ System.out.println(citation.getTitle());
+}</code></pre>
+
+ <p>
+ But more often, metadata are obtained by parsing an <abbr>XML</abbr>
document
+ conforms to the <abbr>ISO</abbr> 19115-3 schema:
+ </p>
+
+<pre><code>import org.apache.sis.xml.XML;
+import org.opengis.metadata.Metadata;
+import jakarta.xml.bind.JAXBException;
+
+void main() throws JAXBException {
+ var metadata = (Metadata) XML.unmarshal(Path.of("Map of Antarctica.xml"));
+}</code></pre>
+
+ <p>
+ Metadata objects in Apache <abbr>SIS</abbr> are mostly containers:
+ they provide getter and setter methods for manipulating the values
associated to properties
+ (for example the <code class="OGC">title</code> property of a
<code>Citation</code> object),
+ but otherwise does not process the values.
+ Exceptions to this rule are deprecated properties,
+ which are not stored but rather redirected to their replacements.
+ </p>
+
+ <xi:include href="NavigateMetadata.html"/>
+ <xi:include href="NilReason.html"/>
</section>
</body>
</html>
diff --git a/content/developer-guide/xml/ISO-19115.html
b/content/developer-guide/xml/ISO-19115.html
index 52d03432..7c194ae7 100644
--- a/content/developer-guide/xml/ISO-19115.html
+++ b/content/developer-guide/xml/ISO-19115.html
@@ -193,22 +193,10 @@ public class MyClass {
<h3 id="nilReason">Placeholders for missing values</h3>
<p>
- When a property is not defined, the corresponding GeoAPI method
usually returns <code>null</code>.
- However, things become complicated when the missing property is a
value considered mandatory by <abbr>ISO</abbr> 19115 standard.
- <abbr>ISO</abbr> 19115-3 allows for the omission of mandatory
properties so long as the reason for the missing value is indicated.
- The reason may be that the property is not applicable (<code
class="OGC">inapplicable</code>),
- that the value probably exists but is not known (<code
class="OGC">unknown</code>),
- that the value cannot exist (<code class="OGC">missing</code>),
- or that the value cannot be revealed (<code
class="OGC">withheld</code>), <i>etc.</i>
- The transmission of this information requires the use of a non-nul
object, even when the value is missing.
- <abbr>SIS</abbr> will then return an object that, besides implementing
the desired GeoAPI interface,
- also implements the <code>org.apache.sis.xml.NilObject</code>
interface.
- This interface flags the instances where all methods return an empty
collection, an empty table, <code>null</code>,
- <code>NaN</code>, <code>0</code> or <code>false</code>, in this
preference order, as permitted by the return types of the methods.
- Each instance that implements <code>NilObject</code> provides a <code
class="SIS">getNilReason()</code> method
- indicating why the object is nil.
- </p>
- <p>
+ If a mandatory property value is missing, a <a href="#NilReason">nil
reason should be provided</a>.
+ The reason is specified in a <code class="OGC">nilReason</code>
attribute, which can take values such as
+ <code class="OGC">unknown</code>, <code class="OGC">missing</code>,
<code class="OGC">inapplicable</code>,
+ <code class="OGC">withheld</code>, <code class="OGC">template</code>,
<i>etc.</i>
In the following example, the left side shows a
<code>CI_Citation</code> element containing a
<code>CI_Series</code> element, while on the right side the series is
unknown.
If the <code>CI_Series</code> element had been completely omitted,
diff --git a/static/book/book.css b/static/book/book.css
index b319440c..effe5d85 100644
--- a/static/book/book.css
+++ b/static/book/book.css
@@ -286,7 +286,8 @@ pre {
margin-bottom: 21px;
padding: 12px;
border: 2px solid silver;
- background: #F8F8F8
+ background: #F8F8F8;
+ font-size: smaller;
}
samp.xml {
