content/developer-guide/introduction/DataAccess.html (84 lines of code) (raw):
<?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>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.buildtools.book` class in `buildSrc`.
-->
<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>
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.
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, 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>
<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 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);
}
}</code></pre>
<p>
Above 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>
<p>
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, 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>
</html>