book/en/introduction/GeoAPI.html - sis-site - Git at Google

 <?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>GeoAPI</title>
     <meta charset="UTF-8"/>
     <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
   </head>
   <body>
     <!--
       Content below this point is copied in "../../content/book/en/developer-guide.html"
       by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
     -->
     <section>
       <header>
         <h2 id="GeoAPI">From conceptual models to Java interfaces: GeoAPI</h2>
       </header>
       <p>
         The <a href="http://www.geoapi.org">GeoAPI</a> project offers a set of Java interfaces for geospatial applications.
         In a series of <code>org.opengis.*</code> packages, GeoAPI defines structures representing metadata,
         coordinate reference systems and operations that perform cartographic projections.
         In a part that is not yet standardized — called <i>pending</i> — GeoAPI defines structures that represent geo-referenced images,
         geometries, filters that can be applied to queries, and other features.
         These interfaces closely follow the specifications of the <abbr>OGC</abbr>, while interpreting and adapting them
         to meet the needs of Java developers — for example, conforming with naming conventions.
         These interfaces benefit both client applications and libraries:
       </p>
       <ul>
         <li><p>
           Developers of client applications benefit from the greater knowledge base available on the Internet
           (due to the many publications related to <abbr>OGC</abbr> standards), as well as increased interoperability.
           Interoperability is facilitated by a better separation between applications that <em>call</em> GeoAPI functions,
           and libraries that <em>implement</em> GeoAPI.
           The separation is similar to that offered by the <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/"><abbr>JDBC</abbr></a> (<i>Java Database Connectivity</i>) interfaces of standard Java.
           Using the interfaces’ <abbr>API</abbr>, developers can ignore the underlying implementation.
           For example, they can perform cartographic projections with the help of the <a href="http://www.geoapi.org/geoapi-proj4/index.html">Proj.4</a> library, or the Apache <abbr>SIS</abbr> library,
           without having to change their programs when they change libraries.
         </p></li>
         <li><p>
           The developers of libraries inherit the expertise of the specifications’ authors, via the models that represent interfaces.
           GeoAPI also provides a framework within which developers can prioritize the implementation of the features they most need,
           while leaving the remaining features as extension points for future developments.
           For example, clients can call a GeoAPI function even if it is not yet supported by the library,
           and simply get a null value until a new version of the library returns a relevant value.
         </p></li>
       </ul>


       <details>
         <summary>More about the GeoAPI project</summary>
         <article id="GeoAPI-history">
           <header>
             <h2>GeoAPI project history</h2>
           </header>
           <p>
             In 2001, the Open GIS Consortium (the former name of the Open Geospatial Consortium) published
             <a href="https://www.ogc.org/standards/ct"><abbr>OGC</abbr> implementation specification 01-009:
             <cite>Coordinate Transformation Services</cite></a>.
             This specification, developed by the Computer Aided Development Corporation (Cadcorp),
             was accompanied by <abbr>COM</abbr>, <abbr>CORBA</abbr>, and Java interfaces.
             At this time, the wave of web services had not yet eclipsed classical programming interfaces.
             The interfaces of the <abbr>OGC</abbr> did anticipate a networked world,
             but invested rather — in the case of Java — in <abbr>RMI</abbr> (<i>Remote Method Invocation</i>) technology.
             As the GeoAPI project did not yet exist, we retroactively designate these historical interfaces “<a href="http://www.geoapi.org/0.1/index.html">GeoAPI 0.1</a>”.
             These interfaces already used the package name <code>org.opengis</code>, which would be adopted by GeoAPI.
           </p><p>
             In 2002, developers of free projects launched a
             <a href="http://web.archive.org/web/20030509104308/http://digitalearth.org/story/2002/10/10/55046/206">call for the creation of a geospatial <abbr>API</abbr></a>.
             The initial proposal attracted the interest of at least five free projects.
             The project was created using <a href="http://sourceforge.net/projects/geoapi/">SourceForge</a>,
             which has since hosted the source code in a <a href="http://www.geoapi.org/source-repository.html">Subversion repository</a>.
             It was then that the project assumed the name “GeoAPI”, and used the interfaces of the <abbr>OGC</abbr> specification 01-009 as a starting point.
           </p><p>
             A few months later, the <abbr>OGC</abbr> launched the <a href="https://www.ogc.org/standards/go"><abbr>GO</abbr>-1: <i>Geographic Objects</i></a> project,
             which pursued goals similar to those of GeoAPI.
             In the meantime, the <abbr>OGC</abbr> abandonned some of their specifications in favor of <abbr>ISO</abbr> standards.
             GeoAPI and <abbr>GO-1</abbr> worked jointly to rework the GeoAPI interfaces and base them on the new <abbr>ISO</abbr> norms.
             Their first interation, <a href="http://www.geoapi.org/1.0/index.html">GeoAPI 1.0</a>,
             served as a starting point for the first draft of the <abbr>OGC</abbr> specification 03-064 by the <abbr>GO</abbr>-1 working group.
             The final version of this specification became an <abbr>OGC</abbr> standard in 2005,
             and <a href="http://www.geoapi.org/2.0/index.html">GeoAPI 2.0</a> was published at that time.
           </p><p>
             The <abbr>GO</abbr>-1 project was largely supported by a company called <i>Polexis</i>.
             Its acquisition by <i>Sys Technology</i>, and the change in priorities under the new owners,
             brought a halt to the <abbr>GO</abbr>-1 project, which in turn slowed development on GeoAPI.
             In order to resume development, a new working group entitled “GeoAPI 3.0” was created at the <abbr>OGC</abbr>.
             This group took a narrower focus compared to GeoAPI 2.0, concentrating on the most stable interfaces, and putting the others
             — such as geometries — in a module entitled “<a href="http://www.geoapi.org/geoapi-pending/index.html">pending</a>”, for future consideration.
             <a href="http://www.geoapi.org/3.0/index.html">GeoAPI 3.0</a> became an <a href="https://www.ogc.org/standards/geoapi"><abbr>OGC</abbr> standard</a> in 2011.
             This version was the first to be deployed in the <a href="http://search.maven.org/#search|ga|1|geoapi">Maven central repository</a>.
           </p>
         </article>
       </details>

       <p id="GeoAPI-core">
         GeoAPI is composed of many modules.
         The <code>geoapi</code> and <code>geoapi-pending</code> modules
         provide interfaces derived from <abbr>UML</abbr> schemas of international standards.
         The conceptual model will be explained in detail in the chapters describing Apache <abbr>SIS</abbr> implementation.
         However, we can get an overview of its content by consulting the page listing the mapping between
         <a href="http://www.geoapi.org/3.0/javadoc/content.html">GeoAPI methods and the standards where they come from</a>.
         Those modules and the mapping between GeoAPI and international standards are described in more details <a href="#SpecificationToInterfaces">in annex</a>.
       </p>


       <h3 id="GeoAPI-implementation">Implementations provided by Apache SIS</h3>
       <p>
         Apache SIS implements most GeoAPI interfaces by a class of the same name than the interface
         but prefixed by “<code>Abstract</code>”, “<code>Default</code>” or “<code>General</code>”.
         Apache SIS classes prefixed by “<code>Default</code>” can be instantiated directly by a
         <code>new DefaultXXX(…)</code> statement or by a call to the <code>createXXX(…)</code> method in a factory.
       </p>
       <div class="example"><b>Example:</b> to represent a projected coordinate reference system (Mercator, Lambert, <i>etc</i>):
         <ul>
           <li><code>org.opengis.referencing.crs.ProjectedCRS</code> is the GeoAPI interface derived from ISO 19111 standard, and</li>
           <li><code>org.apache.sis.referencing.crs.DefaultProjectedCRS</code> is the implementation provided by Apache SIS.</li>
         </ul>
         An instance can be created by:
         <ul>
           <li><code>ProjectedCRS crs = new DefaultProjectedCRS(…)</code>, ou</li>
           <li><code>ProjectedCRS crs = CRSFactory.createProjectedCRS(…)</code>.</li>
         </ul>
         Both approaches expect the same arguments (omitted in this example for brevity).
       </div>
       <p>
         In the default Apache SIS configuration, using <code>FooFactory.createXXX(…)</code> or <code>new DefaultXXX(…)</code>
         is almost the same except that <code>FooFactory</code> may return existing instances instead than creating new instances,
         and that exceptions thrown in case of invalid arguments are different types.
         In more advanced configurations, using <code>Factory</code> reduces the
         <a href="#ServiceLoader">direct dependencies toward Apache SIS</a>
         and allows inversion of control.
       </p><p>
         The “<code>General</code>” prefix is sometime used instead than “<code>Default</code>”
         to indicate that alternative implementations are available for some specific cases.
         For example the <code>Envelope</code> interface is implemented by at least two Apache SIS classes:
         <code>GeneralEnvelope</code> and <code>Envelope2D</code>.
         The first implementation can represent envelopes with any number of dimensions
         while the second implementation is specialized for two-dimensional envelopes.
       </p><p>
         Apache SIS classes prefixed by “<code>Abstract</code>” should not – in principle – be instantiated.
         Users should instantiate a non-abstract subclass instead.
         But many SIS classes are only conceptually abstract, without <code>abstract</code> Java keyword in class definition.
         Such classes can be instantiated by a <code>new AbstractXXX(…)</code> statement
         – but not by <code>Factory</code> – despite being conceptually abstract.
         However such instantiations should be done only in last resort, when it is not possible to determine the exact subtype.
       </p>
     </section>
   </body>
 </html>
	<?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>GeoAPI</title>
	<meta charset="UTF-8"/>
	<link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
	</head>
	<body>
	<!--
	Content below this point is copied in "../../content/book/en/developer-guide.html"
	by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
	-->
	<section>
	<header>
	<h2 id="GeoAPI">From conceptual models to Java interfaces: GeoAPI</h2>
	</header>
	<p>
	The <a href="http://www.geoapi.org">GeoAPI</a> project offers a set of Java interfaces for geospatial applications.
	In a series of <code>org.opengis.*</code> packages, GeoAPI defines structures representing metadata,
	coordinate reference systems and operations that perform cartographic projections.
	In a part that is not yet standardized — called <i>pending</i> — GeoAPI defines structures that represent geo-referenced images,
	geometries, filters that can be applied to queries, and other features.
	These interfaces closely follow the specifications of the <abbr>OGC</abbr>, while interpreting and adapting them
	to meet the needs of Java developers — for example, conforming with naming conventions.
	These interfaces benefit both client applications and libraries:
	</p>
	<ul>
	<li><p>
	Developers of client applications benefit from the greater knowledge base available on the Internet
	(due to the many publications related to <abbr>OGC</abbr> standards), as well as increased interoperability.
	Interoperability is facilitated by a better separation between applications that <em>call</em> GeoAPI functions,
	and libraries that <em>implement</em> GeoAPI.
	The separation is similar to that offered by the <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/"><abbr>JDBC</abbr></a> (<i>Java Database Connectivity</i>) interfaces of standard Java.
	Using the interfaces’ <abbr>API</abbr>, developers can ignore the underlying implementation.
	For example, they can perform cartographic projections with the help of the <a href="http://www.geoapi.org/geoapi-proj4/index.html">Proj.4</a> library, or the Apache <abbr>SIS</abbr> library,
	without having to change their programs when they change libraries.
	</p></li>
	<li><p>
	The developers of libraries inherit the expertise of the specifications’ authors, via the models that represent interfaces.
	GeoAPI also provides a framework within which developers can prioritize the implementation of the features they most need,
	while leaving the remaining features as extension points for future developments.
	For example, clients can call a GeoAPI function even if it is not yet supported by the library,
	and simply get a null value until a new version of the library returns a relevant value.
	</p></li>
	</ul>


	<details>
	<summary>More about the GeoAPI project</summary>
	<article id="GeoAPI-history">
	<header>
	<h2>GeoAPI project history</h2>
	</header>
	<p>
	In 2001, the Open GIS Consortium (the former name of the Open Geospatial Consortium) published
	<a href="https://www.ogc.org/standards/ct"><abbr>OGC</abbr> implementation specification 01-009:
	<cite>Coordinate Transformation Services</cite></a>.
	This specification, developed by the Computer Aided Development Corporation (Cadcorp),
	was accompanied by <abbr>COM</abbr>, <abbr>CORBA</abbr>, and Java interfaces.
	At this time, the wave of web services had not yet eclipsed classical programming interfaces.
	The interfaces of the <abbr>OGC</abbr> did anticipate a networked world,
	but invested rather — in the case of Java — in <abbr>RMI</abbr> (<i>Remote Method Invocation</i>) technology.
	As the GeoAPI project did not yet exist, we retroactively designate these historical interfaces “<a href="http://www.geoapi.org/0.1/index.html">GeoAPI 0.1</a>”.
	These interfaces already used the package name <code>org.opengis</code>, which would be adopted by GeoAPI.
	</p><p>
	In 2002, developers of free projects launched a
	<a href="http://web.archive.org/web/20030509104308/http://digitalearth.org/story/2002/10/10/55046/206">call for the creation of a geospatial <abbr>API</abbr></a>.
	The initial proposal attracted the interest of at least five free projects.
	The project was created using <a href="http://sourceforge.net/projects/geoapi/">SourceForge</a>,
	which has since hosted the source code in a <a href="http://www.geoapi.org/source-repository.html">Subversion repository</a>.
	It was then that the project assumed the name “GeoAPI”, and used the interfaces of the <abbr>OGC</abbr> specification 01-009 as a starting point.
	</p><p>
	A few months later, the <abbr>OGC</abbr> launched the <a href="https://www.ogc.org/standards/go"><abbr>GO</abbr>-1: <i>Geographic Objects</i></a> project,
	which pursued goals similar to those of GeoAPI.
	In the meantime, the <abbr>OGC</abbr> abandonned some of their specifications in favor of <abbr>ISO</abbr> standards.
	GeoAPI and <abbr>GO-1</abbr> worked jointly to rework the GeoAPI interfaces and base them on the new <abbr>ISO</abbr> norms.
	Their first interation, <a href="http://www.geoapi.org/1.0/index.html">GeoAPI 1.0</a>,
	served as a starting point for the first draft of the <abbr>OGC</abbr> specification 03-064 by the <abbr>GO</abbr>-1 working group.
	The final version of this specification became an <abbr>OGC</abbr> standard in 2005,
	and <a href="http://www.geoapi.org/2.0/index.html">GeoAPI 2.0</a> was published at that time.
	</p><p>
	The <abbr>GO</abbr>-1 project was largely supported by a company called <i>Polexis</i>.
	Its acquisition by <i>Sys Technology</i>, and the change in priorities under the new owners,
	brought a halt to the <abbr>GO</abbr>-1 project, which in turn slowed development on GeoAPI.
	In order to resume development, a new working group entitled “GeoAPI 3.0” was created at the <abbr>OGC</abbr>.
	This group took a narrower focus compared to GeoAPI 2.0, concentrating on the most stable interfaces, and putting the others
	— such as geometries — in a module entitled “<a href="http://www.geoapi.org/geoapi-pending/index.html">pending</a>”, for future consideration.
	<a href="http://www.geoapi.org/3.0/index.html">GeoAPI 3.0</a> became an <a href="https://www.ogc.org/standards/geoapi"><abbr>OGC</abbr> standard</a> in 2011.
	This version was the first to be deployed in the <a href="http://search.maven.org/#search\|ga\|1\|geoapi">Maven central repository</a>.
	</p>
	</article>
	</details>

	<p id="GeoAPI-core">
	GeoAPI is composed of many modules.
	The <code>geoapi</code> and <code>geoapi-pending</code> modules
	provide interfaces derived from <abbr>UML</abbr> schemas of international standards.
	The conceptual model will be explained in detail in the chapters describing Apache <abbr>SIS</abbr> implementation.
	However, we can get an overview of its content by consulting the page listing the mapping between
	<a href="http://www.geoapi.org/3.0/javadoc/content.html">GeoAPI methods and the standards where they come from</a>.
	Those modules and the mapping between GeoAPI and international standards are described in more details <a href="#SpecificationToInterfaces">in annex</a>.
	</p>



	<h3 id="GeoAPI-implementation">Implementations provided by Apache SIS</h3>
	<p>
	Apache SIS implements most GeoAPI interfaces by a class of the same name than the interface
	but prefixed by “<code>Abstract</code>”, “<code>Default</code>” or “<code>General</code>”.
	Apache SIS classes prefixed by “<code>Default</code>” can be instantiated directly by a
	<code>new DefaultXXX(…)</code> statement or by a call to the <code>createXXX(…)</code> method in a factory.
	</p>
	<div class="example"><b>Example:</b> to represent a projected coordinate reference system (Mercator, Lambert, <i>etc</i>):
	<ul>
	<li><code>org.opengis.referencing.crs.ProjectedCRS</code> is the GeoAPI interface derived from ISO 19111 standard, and</li>
	<li><code>org.apache.sis.referencing.crs.DefaultProjectedCRS</code> is the implementation provided by Apache SIS.</li>
	</ul>
	An instance can be created by:
	<ul>
	<li><code>ProjectedCRS crs = new DefaultProjectedCRS(…)</code>, ou</li>
	<li><code>ProjectedCRS crs = CRSFactory.createProjectedCRS(…)</code>.</li>
	</ul>
	Both approaches expect the same arguments (omitted in this example for brevity).
	</div>
	<p>
	In the default Apache SIS configuration, using <code>FooFactory.createXXX(…)</code> or <code>new DefaultXXX(…)</code>
	is almost the same except that <code>FooFactory</code> may return existing instances instead than creating new instances,
	and that exceptions thrown in case of invalid arguments are different types.
	In more advanced configurations, using <code>Factory</code> reduces the
	<a href="#ServiceLoader">direct dependencies toward Apache SIS</a>
	and allows inversion of control.
	</p><p>
	The “<code>General</code>” prefix is sometime used instead than “<code>Default</code>”
	to indicate that alternative implementations are available for some specific cases.
	For example the <code>Envelope</code> interface is implemented by at least two Apache SIS classes:
	<code>GeneralEnvelope</code> and <code>Envelope2D</code>.
	The first implementation can represent envelopes with any number of dimensions
	while the second implementation is specialized for two-dimensional envelopes.
	</p><p>
	Apache SIS classes prefixed by “<code>Abstract</code>” should not – in principle – be instantiated.
	Users should instantiate a non-abstract subclass instead.
	But many SIS classes are only conceptually abstract, without <code>abstract</code> Java keyword in class definition.
	Such classes can be instantiated by a <code>new AbstractXXX(…)</code> statement
	– but not by <code>Factory</code> – despite being conceptually abstract.
	However such instantiations should be done only in last resort, when it is not possible to determine the exact subtype.
	</p>
	</section>
	</body>
	</html>