| <?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" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="fr"> |
| <head> |
| <title>DataAccess</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.internal.book.Assembler` class in `sis-build-helper` module. |
| --> |
| <section> |
| <header> |
| <h2 id="DataAccess">Data access overview</h2> |
| </header> |
| <p> |
| It is possible to instantiate data structures programmatically in memory. |
| But more often, data are read from files or other kinds of data stores. |
| There is different ways to access those data, but an easy way is to use |
| the <code class="SIS">DataStores.open(Object)</code> convenience method. |
| The method argument can be a path to a data file |
| (<code>File</code>, <code>Path</code>, <code>URL</code>, <code>URI</code>), a stream |
| (<code>Channel</code>, <code>DataInput</code>, <code>InputStream</code>, <code>Reader</code>), |
| a connection to a data base (<code>DataSource</code>, <code>Connection</code>) |
| or other kinds of object specific to the data source. |
| The <code class="SIS">DataStores.open(Object)</code> method detects data formats |
| and returns a <code>DataStore</code> instance for that format. |
| </p><p> |
| <code>DataStore</code> functionalities depend on the kind of data (coverage, feature set, time series, <i>etc.</i>). |
| But in all cases, there is always some metadata that can be obtained. |
| Metadata allows to identify the phenomenon or features described by the data |
| (temperature, land occupation, <i>etc.</i>), |
| the geographic area or temporal period covered by the data, together with their resolution. |
| Some rich data source provides also a data quality estimation, |
| contact information for the responsible person or organization, |
| 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 |
| in a unique metadata model in order to hide this heterogeneity. |
| This <em>pivot model</em> approach is often used by various libraries, |
| with <cite>Dublin Core</cite> as a popular choice. |
| For Apache <abbr>SIS</abbr>, the chosen pivot model is the <abbr>ISO</abbr> <cite>19115</cite> 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. |
| 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. |
| </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>; |
| |
| // Convenience method for fetching the geographic bounding box at the right location in metadata tree. |
| GeographicBoundingBox bbox = <code class="SIS">Extents.getGeographicBoundingBox</code>(overview); |
| |
| 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> |
| |
| <pre><samp>The geographic bounding box is: |
| Geographic Bounding Box |
| ├─West bound longitude…………………………… 108°20′10.464″E |
| ├─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 |
| 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. |
| </p> |
| </section> |
| </body> |
| </html> |
