Copied: sis/site/trunk/book/en/implementation-independence.html (from r1743965, sis/site/trunk/book/en/geoapi.html) URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/implementation-independence.html?p2=sis/site/trunk/book/en/implementation-independence.html&p1=sis/site/trunk/book/en/geoapi.html&r1=1743965&r2=1745551&rev=1745551&view=diff ============================================================================== --- sis/site/trunk/book/en/geoapi.html (original) +++ sis/site/trunk/book/en/implementation-independence.html Thu May 26 00:52:22 2016 @@ -22,234 +22,30 @@ <html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en"> <head> - <title>GeoAPI</title> + <title>Reduce direct dependency to Apache SIS</title> <link rel="stylesheet" type="text/css" href="../book.css"/> </head> <body> <header> - <h1 id="GeoAPI">GeoAPI</h1> + <h1 id="reduce-direct-dependency">Reduce direct dependency to Apache SIS</h1> </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: + Previous chapters used Apache SIS static methods for convenience. + In some cases, usage of those convenience methods can be replaced by Java code using only GeoAPI methods. + Such replacements may be desirable for applications who want to reduce direct dependency toward Apache SIS, + for example in order to ease migrations between SIS and other GeoAPI implementations. + However this may require that applications write their own convenience methods. + The following sections provide some tip for easing this task. </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> - - <article> - <header> - <h1>GeoAPI project history</h1> - </header> - <p> - In 2001, the Open GIS Consortium (the former name of the Open Geospatial Consortium) published - <a href="http://www.opengeospatial.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="http://www.opengeospatial.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="http://www.opengeospatial.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> - - <h2 id="SpecificationToInterfaces">Interface Specifications</h2> - <p> - Since <abbr>OGC</abbr> standards are defined by well-tested software engineering methods, - it is possible to automatically generate Java interfaces using relatively common tools. - One of the most commonly-used approaches is to transform <a href="http://schemas.opengis.net/gml/3.3/";><abbr>XSD</abbr> schemas</a> - into Java interfaces using command line utility <code>xjc</code>. - As this utility is included in most Java distributions (it is one of the <a href="http://jaxb.java.net";><abbr>JAXB</abbr></a> tools), - this approach is favoured by many projects found on the Internet. - Other approaches use tools integrated into the Eclipse Development Environment, - which is based on <abbr>UML</abbr> schemas rather than <abbr>XSD</abbr> ones. - </p><p> - A similar approach was attempted in the early days of the GeoAPI project, but was quickly abandoned. - We favor a manual approach for the following reasons: - </p> - <ul> - <li> - <p> - Some <abbr>XSD</abbr> schemas are much more verbose than the original <abbr>UML</abbr> schemas. - Converting from <abbr>XSD</abbr> schemas introduces â at least in the case of metadata â - almost double the number of interfaces actually defined by the standard, without adding any new features. - <abbr>XSD</abbr> schemas also define attributes specific to <abbr>XML</abbr> documents (<code class="OGC">id</code>, - <code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>), that do not exist in the original <abbr>UML</abbr> diagrams, - and which we do not necessarily wish to expose in a Java <abbr>API</abbr>. - Converting from <abbr>UML</abbr> schemas avoids this problem, but tools capable of performing this operation are less common. - </p> - <div class="example"><p><b>Example:</b> - <abbr>XSD</abbr> metadata schemas insert a <code><gmd:CI_Citation></code> element - inside a <code class="OGC"><gmd:citation></code>, - a <code><gmd:CI_OnlineResource></code> element inside a <code class="OGC"><gmd:onlineResource></code>, - and so on for the hundreds of classes defined by <abbr>ISO</abbr> 19115 standard. - This redundancy is certainly not necessary in a Java program. - </p></div> - </li> - <li> - <p> - <abbr>OGC</abbr> standards use different naming conventions than Java. - In particular, the names of almost all <abbr>OGC</abbr> classes begin with a two-letter prefix, - such as <code>MD_Identifier</code>. - This prefixes fulfill the same role as package names in Java. - GeoAPI adapts this practice by using interface names without prefixes and placing these interfaces in packages corresponding to the prefixes, - but with more descriptive names. - Occasionally we also change the names; for example, to avoid acronyms, or to conform to an established convention such as JavaBeans. - </p> - <div class="example"><p><b>Example:</b> - The <abbr>OGC</abbr> class <code>MD_Identifier</code> becomes the - <code>Identifier</code> interface in the <code>org.opengis.metadata</code> package. - The <abbr>OGC</abbr> class <code>SC_CRS</code> becomes the <code>CoordinateReferenceSystem</code> interface, - and the <code class="OGC">usesDatum</code> association becomes a <code class="GeoAPI">getDatum()</code> method, - rather than the â<code>getUsesDatum()</code>â that would result from an automatic conversion tool. - We do not allow programs to blindly apply rules that ignore the conventions of the community whose schemas we translate. - </p></div> - </li> - <li> - <p> - The standards may contain structures that do not have a direct equivalent in Java, - such as unions similar to what we would find in C/C++. - The strategy used to obtain an equivalent feature in Java depends on the context: - multiple inheritance of interfaces, modification of the hierarchy, or simply omitting the union. - These decisions are made case-by-case based on a needs analysis. - </p> - <div class="example"><p><b>Example:</b> - <abbr>ISO</abbr> 19111 standard defines different types of coordinate systems, such as spherical, cylindrical, polar or Cartesian. - It then defines several <em>subsets</em> of these types of coordinate systems systems. - These subsets, represented by unions, serve to specify that a class may only be associated with a particular type of coordinate system. - For example, a union of types may be associated with an image, named <code>CS_ImageCS</code>, - which can only contain <code>CS_CartesianCS</code> and <code>CS_AffineCS</code>. - In this case, we get the desired effect in Java through a modification of the hierarchy of classes: - we define the <code>CartesianCS</code> interface as a specialization of <code>AffineCS</code>, - which is semantically correct. - But it is not possible to apply a similar strategy to other unions without violating the semantics. - </p></div> - </li> - <li> - <p> - Several specifications overlap. - GeoAPI performs the work of integration by replacing some duplicate structures with references to equivalent structures from the standards that best represent them. - </p> - <div class="example"><p><b>Example:</b> - <abbr>ISO</abbr> 19115:2003 standard, which defines metadata structures, - also attempts to describe a few structures representing coordinate reference systems (<abbr title="Coordinate Reference System">CRS</abbr>). - Yet these are also the focus of another standard: <abbr>ISO</abbr> 19111. - At the same time, <abbr>ISO</abbr> 19111:2007 states in section 3 that it reuses all of the elements of - <abbr>ISO</abbr> 19115:2003 except <code>MD_CRS</code> and its components. - GeoAPI interfaces reduce the redundancy by applying the exclusion recommended by <abbr>ISO</abbr> 19111 to the entire project. - </p></div> - </li> - <li> - <p> - The complexity of some standards have increased for historical reasons rather than technical ones, related to the standardization process. - GeoAPI reduces the technical debt by designing interfaces with each element in its proper place, - regardless of the chronological order in which the standards were published. - </p> - <div class="example"><p><b>Exemple:</b> - <abbr>ISO</abbr> 19115-2 standard is an extension of <abbr>ISO</abbr> 19115-1 standard, adding image metadata structures. - These metadata were defined in a separate standard because they were not yet ready when the first part of the standard was published. - As it was not possible for administrative reasons to add attributes to already-published classes, - the new attributes were added in a sub-class bearing almost the same name. - Thus, <abbr>ISO</abbr> 19115-2 defines the class <code>MI_Band</code>, - which extends the class <code>MD_Band</code> from <abbr>ISO</abbr> 19115-1 by adding attributes that would have appeared - directly in the parent class if there were ready on time. - In GeoAPI, we have chosen to ârepairâ these anomalies by fusing these two classes into a single interface. - </p></div> - </li> - </ul> - <p> - Deviations from the standards are documented in each affected class and method. - Each mention of a deviation is also collected on a <a href="http://www.geoapi.org/3.0/javadoc/departures.html";>single page</a> in order to provide an overview. - Since these deviations blur the relationships between the standards and certain Java interfaces, - the correspondence between these languages is explained by <code>@UML</code> annotations and property files described in the following section. - </p> - - - - <h3 id="UML-annotation">Mapping Given by <code>@UML</code> Annotations</h3> + <h2 id="UML-annotation-geoapi">Mapping Given by <code>@UML</code> Annotations</h2> <p> For each class, method and constant defined by an <abbr>OGC</abbr> or <abbr>ISO</abbr> standard, GeoAPI indicates its provenance using annotations defined in the <code>org.opengis.annotation</code> package. - In particular, the <code>@UML</code> annotations indicates the standard, - the name of the element in that standard, and also its obligation. - For example, in the following code snippet, the first <code>@UML</code> code indicates that the Java interface that follows - (<code>ProjectedCRS</code>) is defined using the <code>SC_ProjectedCRS</code> type of <abbr>ISO</abbr> 19111 standard. - The second <code>@UML</code> annotation, this time applied to the <code class="GeoAPI">getCoordinateSystem()</code> method, - indicates that this method is defined using the <code class="OGC">coordinateSystem</code> association of <abbr>ISO</abbr> 19111 standard, - and that this association is mandatory â meaning, in Java, that the method is not allowed to return a <code>null</code> value. - </p> - -<pre>package <code>org.opengis.referencing.crs</code>; - -/** - * A 2D coordinate reference system used to approximate the shape of the earth on a planar surface. - */ -@UML(specification = ISO_19111, - identifier = "<code class="OGC">SC_ProjectedCRS</code>") -public interface ProjectedCRS extends GeneralDerivedCRS { - /** - * Returns the coordinate system, which must be Cartesian. - */ - @UML(obligation = MANDATORY, - specification = ISO_19111, - identifier = "<code class="OGC">coordinateSystem</code>") - CartesianCS <code class="GeoAPI">getCoordinateSystem()</code>; -}</pre> - - <p> + This mapping is described in the <a href="#UML-annotation">chapter about GeoAPI</a>. Java reflection methods allow access to this information during the execution of an application. - This is useful for displaying UML identifiers for users familiar with <abbr>OGC</abbr> standards, - or for writing elements in an <abbr>XML</abbr> document. + Class <code>org.apache.sis.util.iso.Types</code> provides static convenience methods like + <code class="SIS">getStandardName(Class)</code>, but one can avoid those methods. The following example displays the standard name for the method <code class="GeoAPI">getTitle()</code> from the <code>Citation</code> interface: </p> @@ -260,11 +56,6 @@ String id = annot.identifier(); System.out.println("The standard name for the " + method.getName() + " method is " + id);</pre> <p> - The class <code>org.apache.sis.util.iso.Types</code> provides the - <code class="SIS">getStandardName(Class)</code> convenience method to perform this operation. - </p> - - <p> The reverse operation â getting the Java class and method from a standard name â is a bit more complicated. It requires reading the <code class="GeoAPI">class-index.properties</code> file provided in the <code>org.opengis.annotation</code> package. The following example reads the files just before searching for the name of the interface corresponding to <code>CI_Citation</code>. @@ -281,198 +72,13 @@ Class<?> type = Class.forName(geo System.out.println("The GeoAPI interface for <abbr>ISO</abbr> type " + isoName + " is " + type);</pre> <p> - The class <code>org.apache.sis.util.iso.Types</code> provides the - <code class="SIS">forStandardName(String)</code> convenience method to perform this operation. + The <code>org.apache.sis.util.iso.Types</code> convenience method for above task is + <code class="SIS">forStandardName(String)</code>. </p> - <h3 id="MappingToJDK">Implicit Mapping to Standard <abbr>JDK</abbr></h3> - <p> - Some classes and methods have neither an <code>@UML</code> annotation, nor an entry in the <code class="GeoAPI">class-index.properties</code> file. - They are either extensions of GeoAPI, or else types defined in other libraries, such as standard <abbr title="Java Development Kit">JDK</abbr>. - In this last case, the mapping to <abbr>ISO</abbr> standards is implicit. - The following table describes this mapping for <abbr>ISO</abbr> 19103 types. - Java's primitive types are preferred when applicable, - but where necessary their wrappers are used in order to authorize null values. - </p> - <table> - <caption>Mapping between <abbr>ISO</abbr> 19103 and <abbr>JDK</abbr> types</caption> - <tr> - <th><abbr>ISO</abbr> type</th> - <th><abbr>JDK</abbr> type</th> - <th>Remarks</th> - </tr> - <tr> - <td class="separator" colspan="2">Numbers</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Integer</code></td> - <td><code>int</code></td> - <td class="leftBorder">Sometimes <code>java.lang.Integer</code> for optional attributes.</td> - </tr> - <tr> - <td><code class="OGC">Integer</code> (in some cases)</td> - <td><code>long</code></td> - <td class="leftBorder">Sometimes <code>java.lang.Long</code> for optional attributes.</td> - </tr> - <tr> - <td><code class="OGC">Real</code></td> - <td><code>double</code></td> - <td class="leftBorder">Sometimes <code>java.lang.Double</code> for optional attributes.</td> - </tr> - <tr> - <td><code class="OGC">Decimal</code></td> - <td><code>java.math.BigDecimal</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Number</code></td> - <td><code>java.lang.Number</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td class="separator" colspan="2">Texts</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">FreeText</code></td> - <td>(no equivalent)</td> - <td class="leftBorder">See <code class="GeoAPI">org.opengis.util.InternationalString</code> below.</td> - </tr> - <tr> - <td><code class="OGC">CharacterString</code></td> - <td><code>java.lang.String</code></td> - <td class="leftBorder">Often <code class="GeoAPI">org.opengis.util.InternationalString</code> (see below).</td> - </tr> - <tr> - <td><code class="OGC">LocalisedCharacterString</code></td> - <td><code>java.lang.String</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Sequence<Character></code></td> - <td><code>java.lang.CharSequence</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Character</code></td> - <td><code>char</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td class="separator" colspan="2">Dates and hours</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Date</code></td> - <td><code>java.util.Date</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Time</code></td> - <td><code>java.util.Date</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">DateTime</code></td> - <td><code>java.util.Date</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td class="separator" colspan="2">Collections</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Collection</code></td> - <td><code>java.util.Collection</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Bag</code></td> - <td><code>java.util.Collection</code></td> - <td class="leftBorder">A <code class="OGC">Bag</code> is similar to a - <code class="OGC">Set</code> without being restricted by uniqueness.</td> - </tr> - <tr> - <td><code class="OGC">Set</code></td> - <td><code>java.util.Set</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Sequence</code></td> - <td><code>java.util.List</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Dictionary</code></td> - <td><code>java.util.Map</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">KeyValuePair</code></td> - <td><code>java.util.Map.Entry</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td class="separator" colspan="2">Enumerations</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Enumeration</code></td> - <td><code>java.lang.Enum</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">CodeList</code></td> - <td>(no equivalent)</td> - <td class="leftBorder">See <code>org.opengis.util.CodeList</code> below.</td> - </tr> - <tr> - <td class="separator" colspan="2">Various</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Boolean</code></td> - <td><code>boolean</code></td> - <td class="leftBorder">Sometimes <code>java.lang.Boolean</code> for optional attributes.</td> - </tr> - <tr> - <td><code class="OGC">Any</code></td> - <td><code>java.lang.Object</code></td> - <td class="leftBorder"></td> - </tr> - </table> - - <p> - The nearest equivalent for <code>CharacterString</code> is the <code>String</code> class, - but GeoAPI often uses the <code>InternationalString</code> interface, allowing the client to choose the language. - For example, it is useful on a server that simultaneously provides pages in multiple languages. - By returning translations when objects are used rather than at the time of their creation, - we allow the <abbr>SIS</abbr> library to provide the same instances of <code>Metadata</code> - or <code>Coverage</code> (for example) for the same data, regardless of the client's language. - Translations may be made on the fly with the help of the application's <code>ResourceBundle</code>, - or may be provided directly with the data (as in the case of <code>Metadata</code>). - </p> - <p> - An <code>Enumeration</code> corresponds to an <code>Enum</code> in Java. - Both define all authorized values, without allowing the user to add any. - A <code class="OGC">CodeList</code> is similar to an enumeration, except that users may add their own items. - Standard <abbr>JDK</abbr> does not offer this possibility. - GeoAPI defines an abstract <code class="GeoAPI">CodeList</code> class that reproduces some of the functionality of <code>Enum</code> while being extensible. - Extensions are made available by the <code class="GeoAPI">valueOf(String)</code> static method, which, in contrast to <code>Enum</code>, - creates new instances if the name provided does not correspond to the name of an existing instance. - </p> - -<pre>MediumName cdRom = MediumName.<code class="GeoAPI">CD_ROM;</code> -MediumName usbKey = MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">USB_KEY</code>"); // There is no constraint on this value. -assert MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">CD_ROM</code>") == cdRom : "valueOf must return existing constants."; -assert MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">USB_KEY</code>") == usbKey : "valueOf must cache the previously requested values.";</pre> - - - - <h2 id="ServiceLoader">Fetching an Implementation of the Interfaces</h2> + <h2 id="ServiceLoader">Fetching implementations of GeoAPI Interfaces</h2> <p> GeoAPI defines factories (<code>Factory</code>) that can create implementations of interfaces. For example, <code>DatumFactory</code> provides methods that can create instances which implement interfaces of the @@ -572,232 +178,7 @@ public class MyApplication { - <h2 id="GeoAPI-modules">GeoAPI Modules</h2> - <p> - The GeoAPI project consists of a standardized part (<code>geoapi</code>) - and an experimental part (<code>geoapi-pending</code>). - As these two parts are mutually exclusive, users must take care not to mix them in the same project. - This separation is guaranteed for all projects that depend only on the Maven central repository - (including the final versions of Apache <abbr>SIS</abbr>), - as the <code>geoapi-pending</code> module is never deployed on this central repository. - By contrast, certain <abbr>SIS</abbr> development branches may depend on <code>geoapi-pending</code>. - </p> - <p> - GeoAPI modules are: - </p> - <ul> - <li><p> - <b><code>geoapi</code></b> â includes interfaces covered by the - <a href="http://www.opengeospatial.org/standards/geoapi";>GeoAPI standard of the <abbr>OGC</abbr></a>. - The final versions of Apache <abbr>SIS</abbr> depend on this module. - </p></li> - <li><p> - <b><code>geoapi-pending</code></b> â contains a - <em>copy</em> of all interfaces in the <code>geoapi</code> module - (not a dependence) with additions that have not yet been approved as an <abbr>OGC</abbr> standard. - Some additions appear in interfaces normally defined by the <code>geoapi</code> module, hence the need to copy them. - Apache <abbr>SIS</abbr>'s development branches <code>jdk6</code>, <code>jdk7</code> and <code>jdk8</code> depend on this module, - but this dependence becomes a dependence on the <code>geoapi</code> standard module when the branches are merged to the trunk. - </p></li> - <li><p> - <b><code>geoapi-conformance</code></b> â includes a JUnit test suite that developers may use to test their implementations. - </p></li> - <li><p> - <b><code>geoapi-examples</code></b> â includes examples of relatively simple implementations. - These examples are placed in the public domain in order to encourage users to copy and adapt them to their needs if - Apache <abbr>SIS</abbr> services are unsuitable. - </p></li> - <li><p> - <b><code>geoapi-proj4</code></b> â contains a partial implementation of <code>org.opengis.referencing</code> - packages as adaptors based on the C/C++ Proj.4 library. - This module may be used as an alternative to the <code>sis-referencing</code> module for certain functions. - </p></li> - <li><p> - <b><code>geoapi-netcdf</code></b> â contains a partial implementation of <code>org.opengis.referencing</code> - and <code>org.opengis.coverage</code> packages as adaptors based on the <abbr>UCAR</abbr> <abbr>NetCDF</abbr> library. - The series of tests in this module was developed in such a way as to be reusable for other projects. - Apache <abbr>SIS</abbr> uses them to test its own <code>sis-netcdf</code> module. - </p></li> - <li><p> - <b><code>geoapi-openoffice</code></b> â contains an add-in for the OpenOffice.org office suite. - <!-- - Apache <abbr>SIS</abbr> offers its own add-in in the <code>sis-openoffice</code> module, - but uses the same function names as the GeoAPI module in order to maintain some compatibility. - --> - </p></li> - </ul> - - <h3 id="GeoAPI-core">The Interfaces' Definition Modules</h3> - <p> - <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>. - </p> - - - - <h3 id="GeoAPI-conformance">The Conformance Tests Module</h3> - <p> - The <code>geoapi-conformance</code> module provides <i>validators</i>, a JUnit <i>test suite</i>, and <i>report generators</i> - in the form of <abbr title="Hypertext Markup Language">HTML</abbr> pages. - This module may be used with any GeoAPI implementation. - For developers of a geospatial library, it offers the following advantages: - </p> - <ul> - <li>Reduces the tedious task of writing tests by using existing tests.</li> - <li>Increases confidence in the validity of tests, - since <code>geoapi-conformance</code> has its own test suite and is applied to other implementations.</li> - <li>Facilitates comparison with other implementations.</li> - </ul> - - - - <h4 id="GeoAPI-validators">Instance Validations</h4> - <p> - GeoAPI can validate an instance of its interfaces by checking that certain constraints are observed. - Many constraints can not be expressed in the method signature. Those constraints - are usually described textually in the abstract specifications or in the javadoc. - </p> - <div class="example"><p><b>Example:</b> - A coordinate conversion or transformation (<code>CC_CoordinateOperation</code>) may require a sequence of several steps. - In such a sequence of operations (<code>CC_ConcatenatedOperation</code>), for each step (<code>CC_SingleOperation</code>) - the number of output dimensions must equal the number of input dimensions in the next operation. - Expressed in Java, this constraint stipulates that for the entire index 0 < <var>i</var> < <var>n</var> where <var>n</var> - is the number of operations, we have <code>coordOperation[i].targetDimensions == coordOperation[i-1].sourceDimensions</code>. - </p></div> - - <p> - The easiest way to perform these verifications is to call the static methods <code class="GeoAPI">validate(â¦)</code> - of the <code>org.opengis.test.Validators</code> class. - As all of <code>Validators</code> methods bear the same name, it is enough to write â<code>validate(<var>value</var>)</code>â - and then let the compiler choose the most appropriate method for the type of object given in argument. - If the object type is not known at the time of compilation, - the <code class="GeoAPI">dispatch(Object)</code> method can be invoked for redirecting the work to the most appropriate <code class="GeoAPI">validate(â¦)</code> method. - </p> - <p> - All <code class="GeoAPI">validate(â¦)</code> functions follow a chain of dependencies, - meaning that they will also validate each component of the object to be validated. - For example, the validation of a <code>GeographicCRS</code> implies the validation of its component - <code>GeodeticDatum</code>, which itself implies the validation of its component <code>Ellipsoid</code>, and so on. - Thus it is unnecessary to validate the components explicitely, unless the developer wishes to isolate the test for a particular item known to cause problems. - </p> - <p> - By default, validations are as strict as possible. It is always possible to relax certain rules. - The most common is to tolerate the absence of attributes that would normally be mandatory. - This rule and a few others may be modified globally for all tests executed by the currently running <abbr title="Java Virtual Machine">JVM</abbr>, - as in the following example: - </p> - -<pre>import org.opengis.metadata.Metadata; -import org.opengis.test.Validators; -import org.junit.Test; - -public class MyTest { - /* - * Tolerate the absence of mandatory attributes in metadata and citation packages. - * This modification applies to all tests executed by the currently running <abbr>JVM</abbr>. - * If there are multiple test classes, this initialization may be performed - * in a parent class to all test classes. - */ - static { - Validators.<code class="GeoAPI">DEFAULT.metadata.requireMandatoryAttributes</code> = false; - Validators.<code class="GeoAPI">DEFAULT.citation.requireMandatoryAttributes</code> = false; - } - - @Test - public void testMyMetadata() { - Metadata myObject = â¦; // Create an object here. - Validators.<code class="GeoAPI">validate</code>(myObject); - } -}</pre> - - <p> - Rules may also be modified for a particular test suite without affecting the default configuration of the standard <abbr>JVM</abbr>. - This approach requires the creation of a new instance of the validator that we wish to modify the configuration. - </p> - -<pre>import org.opengis.metadata.Metadata; -import org.opengis.test.ValidatorContainer; -import org.junit.Test; - -public class MyTest { - private final ValidatorContainer validators; - - public MyTest() { - validators = new ValidatorContainer(); - validators.<code class="GeoAPI">metadata.requireMandatoryAttributes</code> = false; - validators.<code class="GeoAPI">citation.requireMandatoryAttributes</code> = false; - } - - @Test - public void testMyMetadata() { - Metadata myObject = â¦; // Create an object here. - validators.<code class="GeoAPI">validate</code>(myObject); - } -}</pre> - - - - <h4 id="GeoAPI-tests">Executing Pre-defined Tests</h4> - <p> - JUnit tests are defined in the <code>org.opengis.test</code> sub-packages. - All test classes bear a name ending in "<code>Test</code>". - GeoAPI also provides an <code>org.opengis.test.TestSuite</code> class including all test classes defined in the - <code>geoapi-conformance</code> module, but Apache <abbr>SIS</abbr> does not use it. - Instead, Apache <abbr>SIS</abbr> inherits GeoAPI's <code class="GeoAPI">*Test</code> classes on a case-by-case basis, - in the appropriate modules. - The example below gives an example of a customized GeoAPI test: - The <a href="http://www.geoapi.org/geoapi-conformance/apidocs/org/opengis/test/referencing/ParameterizedTransformTest.html";>parent test javadoc</a> - documents the tests performed in detail. - In this example, only one test is modified and all the others are inherited as they are (it is not necessary to repeat them in the sub-class). - However, this example adds a supplemental verification, annotated with <code>@After</code>, which will be executed after each test. - </p> - -<pre>import org.junit.*; -import org.junit.runner.RunWith; -import org.junit.runners.JUnit4; -import org.opengis.test.referencing.ParameterizedTransformTest; -import static org.junit.Assert.*; - -@RunWith(JUnit4.class) -public class MyTest extends ParameterizedTransformTest { - /** - * Specify our own coordinate transformation factory for the GeoAPI tests. - * GeoAPI will test the objects created by this factory. - */ - public MyTest() { - super(new MyMathTransformFactory()); - } - - /** - * Changes the behaviour of a test. This example relaxes the requirements of this test a little, - * by accepting errors of up to 10 centimetres, rather than the default value of 1 cm. - * This change only applies to this method, and does not affect the other inherited tests. - */ - @Test - @Override - public void testLambertAzimuthalEqualArea() throws FactoryException, TransformException { - <code class="GeoAPI">tolerance</code> = 0.1; // 10 cm tolerance. - super.<code class="GeoAPI">testLambertAzimuthalEqualArea()</code>; - } - - /** - * Supplemental verification performed after each test, inherited or not. - * In this example, we are verifying that the transformation tested - * works correctly in two-dimensional spaces. - */ - @After - public void ensureAllTransformAreMath2D() { - assertTrue(<code class="GeoAPI">transform</code> instanceof MathTransform2D); - } -}</pre> - - - - <h3 id="GeoAPI-examples">Example Modules</h3> - <p> + <p id="GeoAPI-examples"> The <code>geoapi-examples</code> module provides examples of simple implementations. Many of these classes implement more than one interface at a time in order to provide a simpler conceptual model. The <a href="http://www.geoapi.org/geoapi-examples/apidocs/overview-summary.html";>javadoc for this module</a>
Modified: sis/site/trunk/book/en/introduction.html URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/introduction.html?rev=1745551&r1=1745550&r2=1745551&view=diff ============================================================================== --- sis/site/trunk/book/en/introduction.html (original) +++ sis/site/trunk/book/en/introduction.html Thu May 26 00:52:22 2016 @@ -95,15 +95,6 @@ Standardization organizations do not create software; to obtain an implementation of these specifications, users must choose one of the compliant products available on the market, or develop their own solutions. Such voluntary compliance with these specifications allow independent communities to more easily exchange geographic information. - </p><p> - Besides these formal standardization organizations, there are organizations that are not officially dedicated - to the creation of standards, but whose work has largely been adopted as <i>de facto</i> standards. - In particular, the <a href="http://www.epsg.org";>EPSG</a> database offers numeric codes which allow the easy identification of a - Coordinates Reference System (<abbr>CRS</abbr>) among <a href="../../tables/CoordinateReferenceSystems.html">several thousand</a>. - This database is offered by petroleum companies that have an interest in ensuring their explorations are conducted in the correct place, - even when using map produced by another party. - Other examples of <i>de facto</i> standards include <a href="http://geotiff.osgeo.org";>GeoTIFF</a> for data distributed on a grid (such as images), - and <a href="http://en.wikipedia.org/wiki/Shapefile";>Shapefile</a> for vector data (such as geometric shapes). </p> @@ -183,13 +174,21 @@ </details> - <h3 id="SpecificationTypes">Types of Specifications</h3> + <p> + Besides these formal standardization organizations, there are organizations that are not officially dedicated + to the creation of standards, but whose work has largely been adopted as <i>de facto</i> standards. + In particular, the <a href="http://www.epsg.org";>EPSG</a> database offers numeric codes which allow the easy identification of a + Coordinates Reference System (<abbr>CRS</abbr>) among <a href="../../tables/CoordinateReferenceSystems.html">several thousand</a>. + This database is offered by petroleum companies that have an interest in ensuring their explorations are conducted in the correct place, + even when using map produced by another party. + Other examples of <i>de facto</i> standards include <a href="http://geotiff.osgeo.org";>GeoTIFF</a> for data distributed on a grid (such as images), + and <a href="http://en.wikipedia.org/wiki/Shapefile";>Shapefile</a> for vector data (such as geometric shapes). + </p><p> <abbr>OGC</abbr> standards are specified in several dozen documents. Each document outlines a service â for example, the transformation of coordinates. The function of each service is described by a collection of object classes and their interactions. These elements are illustrated by <abbr>UML</abbr> (Unified Modeling Language) diagrams in specifications called âabstractsâ. - </p><p> <a href="http://www.opengeospatial.org/standards/as";>Abstract specifications</a> do not refer to any specific computer language. Their concepts may be applied more or less directly to a programming language, a database or an <abbr>XML</abbr> schema. There is always an element of arbitrariness in the method of applying an abstract specification, Copied: sis/site/trunk/book/en/test.html (from r1743965, sis/site/trunk/book/en/geoapi.html) URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/test.html?p2=sis/site/trunk/book/en/test.html&p1=sis/site/trunk/book/en/geoapi.html&r1=1743965&r2=1745551&rev=1745551&view=diff ============================================================================== --- sis/site/trunk/book/en/geoapi.html (original) +++ sis/site/trunk/book/en/test.html Thu May 26 00:52:22 2016 @@ -22,624 +22,22 @@ <html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en"> <head> - <title>GeoAPI</title> + <title>Test suites</title> <link rel="stylesheet" type="text/css" href="../book.css"/> </head> <body> <header> - <h1 id="GeoAPI">GeoAPI</h1> + <h1 id="tests">Test suites</h1> </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: + In addition to its own tests, Apache SIS uses tests defined by GeoAPI. + One advantages is that those tests provide an external source for the definition of expected results + (for example the numerical values of coordinates obtained after a map projection). + Such external source reduce the risk that some tests are actually anti-regression tests + instead of correctness tests. + Those tests can also be used by projects other than Apache SIS. </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> - - <article> - <header> - <h1>GeoAPI project history</h1> - </header> - <p> - In 2001, the Open GIS Consortium (the former name of the Open Geospatial Consortium) published - <a href="http://www.opengeospatial.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="http://www.opengeospatial.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="http://www.opengeospatial.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> - - - <h2 id="SpecificationToInterfaces">Interface Specifications</h2> - <p> - Since <abbr>OGC</abbr> standards are defined by well-tested software engineering methods, - it is possible to automatically generate Java interfaces using relatively common tools. - One of the most commonly-used approaches is to transform <a href="http://schemas.opengis.net/gml/3.3/";><abbr>XSD</abbr> schemas</a> - into Java interfaces using command line utility <code>xjc</code>. - As this utility is included in most Java distributions (it is one of the <a href="http://jaxb.java.net";><abbr>JAXB</abbr></a> tools), - this approach is favoured by many projects found on the Internet. - Other approaches use tools integrated into the Eclipse Development Environment, - which is based on <abbr>UML</abbr> schemas rather than <abbr>XSD</abbr> ones. - </p><p> - A similar approach was attempted in the early days of the GeoAPI project, but was quickly abandoned. - We favor a manual approach for the following reasons: - </p> - <ul> - <li> - <p> - Some <abbr>XSD</abbr> schemas are much more verbose than the original <abbr>UML</abbr> schemas. - Converting from <abbr>XSD</abbr> schemas introduces â at least in the case of metadata â - almost double the number of interfaces actually defined by the standard, without adding any new features. - <abbr>XSD</abbr> schemas also define attributes specific to <abbr>XML</abbr> documents (<code class="OGC">id</code>, - <code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>), that do not exist in the original <abbr>UML</abbr> diagrams, - and which we do not necessarily wish to expose in a Java <abbr>API</abbr>. - Converting from <abbr>UML</abbr> schemas avoids this problem, but tools capable of performing this operation are less common. - </p> - <div class="example"><p><b>Example:</b> - <abbr>XSD</abbr> metadata schemas insert a <code><gmd:CI_Citation></code> element - inside a <code class="OGC"><gmd:citation></code>, - a <code><gmd:CI_OnlineResource></code> element inside a <code class="OGC"><gmd:onlineResource></code>, - and so on for the hundreds of classes defined by <abbr>ISO</abbr> 19115 standard. - This redundancy is certainly not necessary in a Java program. - </p></div> - </li> - <li> - <p> - <abbr>OGC</abbr> standards use different naming conventions than Java. - In particular, the names of almost all <abbr>OGC</abbr> classes begin with a two-letter prefix, - such as <code>MD_Identifier</code>. - This prefixes fulfill the same role as package names in Java. - GeoAPI adapts this practice by using interface names without prefixes and placing these interfaces in packages corresponding to the prefixes, - but with more descriptive names. - Occasionally we also change the names; for example, to avoid acronyms, or to conform to an established convention such as JavaBeans. - </p> - <div class="example"><p><b>Example:</b> - The <abbr>OGC</abbr> class <code>MD_Identifier</code> becomes the - <code>Identifier</code> interface in the <code>org.opengis.metadata</code> package. - The <abbr>OGC</abbr> class <code>SC_CRS</code> becomes the <code>CoordinateReferenceSystem</code> interface, - and the <code class="OGC">usesDatum</code> association becomes a <code class="GeoAPI">getDatum()</code> method, - rather than the â<code>getUsesDatum()</code>â that would result from an automatic conversion tool. - We do not allow programs to blindly apply rules that ignore the conventions of the community whose schemas we translate. - </p></div> - </li> - <li> - <p> - The standards may contain structures that do not have a direct equivalent in Java, - such as unions similar to what we would find in C/C++. - The strategy used to obtain an equivalent feature in Java depends on the context: - multiple inheritance of interfaces, modification of the hierarchy, or simply omitting the union. - These decisions are made case-by-case based on a needs analysis. - </p> - <div class="example"><p><b>Example:</b> - <abbr>ISO</abbr> 19111 standard defines different types of coordinate systems, such as spherical, cylindrical, polar or Cartesian. - It then defines several <em>subsets</em> of these types of coordinate systems systems. - These subsets, represented by unions, serve to specify that a class may only be associated with a particular type of coordinate system. - For example, a union of types may be associated with an image, named <code>CS_ImageCS</code>, - which can only contain <code>CS_CartesianCS</code> and <code>CS_AffineCS</code>. - In this case, we get the desired effect in Java through a modification of the hierarchy of classes: - we define the <code>CartesianCS</code> interface as a specialization of <code>AffineCS</code>, - which is semantically correct. - But it is not possible to apply a similar strategy to other unions without violating the semantics. - </p></div> - </li> - <li> - <p> - Several specifications overlap. - GeoAPI performs the work of integration by replacing some duplicate structures with references to equivalent structures from the standards that best represent them. - </p> - <div class="example"><p><b>Example:</b> - <abbr>ISO</abbr> 19115:2003 standard, which defines metadata structures, - also attempts to describe a few structures representing coordinate reference systems (<abbr title="Coordinate Reference System">CRS</abbr>). - Yet these are also the focus of another standard: <abbr>ISO</abbr> 19111. - At the same time, <abbr>ISO</abbr> 19111:2007 states in section 3 that it reuses all of the elements of - <abbr>ISO</abbr> 19115:2003 except <code>MD_CRS</code> and its components. - GeoAPI interfaces reduce the redundancy by applying the exclusion recommended by <abbr>ISO</abbr> 19111 to the entire project. - </p></div> - </li> - <li> - <p> - The complexity of some standards have increased for historical reasons rather than technical ones, related to the standardization process. - GeoAPI reduces the technical debt by designing interfaces with each element in its proper place, - regardless of the chronological order in which the standards were published. - </p> - <div class="example"><p><b>Exemple:</b> - <abbr>ISO</abbr> 19115-2 standard is an extension of <abbr>ISO</abbr> 19115-1 standard, adding image metadata structures. - These metadata were defined in a separate standard because they were not yet ready when the first part of the standard was published. - As it was not possible for administrative reasons to add attributes to already-published classes, - the new attributes were added in a sub-class bearing almost the same name. - Thus, <abbr>ISO</abbr> 19115-2 defines the class <code>MI_Band</code>, - which extends the class <code>MD_Band</code> from <abbr>ISO</abbr> 19115-1 by adding attributes that would have appeared - directly in the parent class if there were ready on time. - In GeoAPI, we have chosen to ârepairâ these anomalies by fusing these two classes into a single interface. - </p></div> - </li> - </ul> - <p> - Deviations from the standards are documented in each affected class and method. - Each mention of a deviation is also collected on a <a href="http://www.geoapi.org/3.0/javadoc/departures.html";>single page</a> in order to provide an overview. - Since these deviations blur the relationships between the standards and certain Java interfaces, - the correspondence between these languages is explained by <code>@UML</code> annotations and property files described in the following section. - </p> - - - - <h3 id="UML-annotation">Mapping Given by <code>@UML</code> Annotations</h3> - <p> - For each class, method and constant defined by an <abbr>OGC</abbr> or <abbr>ISO</abbr> standard, - GeoAPI indicates its provenance using annotations defined in the <code>org.opengis.annotation</code> package. - In particular, the <code>@UML</code> annotations indicates the standard, - the name of the element in that standard, and also its obligation. - For example, in the following code snippet, the first <code>@UML</code> code indicates that the Java interface that follows - (<code>ProjectedCRS</code>) is defined using the <code>SC_ProjectedCRS</code> type of <abbr>ISO</abbr> 19111 standard. - The second <code>@UML</code> annotation, this time applied to the <code class="GeoAPI">getCoordinateSystem()</code> method, - indicates that this method is defined using the <code class="OGC">coordinateSystem</code> association of <abbr>ISO</abbr> 19111 standard, - and that this association is mandatory â meaning, in Java, that the method is not allowed to return a <code>null</code> value. - </p> - -<pre>package <code>org.opengis.referencing.crs</code>; - -/** - * A 2D coordinate reference system used to approximate the shape of the earth on a planar surface. - */ -@UML(specification = ISO_19111, - identifier = "<code class="OGC">SC_ProjectedCRS</code>") -public interface ProjectedCRS extends GeneralDerivedCRS { - /** - * Returns the coordinate system, which must be Cartesian. - */ - @UML(obligation = MANDATORY, - specification = ISO_19111, - identifier = "<code class="OGC">coordinateSystem</code>") - CartesianCS <code class="GeoAPI">getCoordinateSystem()</code>; -}</pre> - - <p> - Java reflection methods allow access to this information during the execution of an application. - This is useful for displaying UML identifiers for users familiar with <abbr>OGC</abbr> standards, - or for writing elements in an <abbr>XML</abbr> document. - The following example displays the standard name for the method <code class="GeoAPI">getTitle()</code> from the <code>Citation</code> interface: - </p> - -<pre>Class<?> type = Citation.class; -Method method = type.getMethod("<code class="GeoAPI">getTitle</code>", (Class<?>[]) null); -UML annot = method.getAnnotation(UML.class); -String id = annot.identifier(); -System.out.println("The standard name for the " + method.getName() + " method is " + id);</pre> - - <p> - The class <code>org.apache.sis.util.iso.Types</code> provides the - <code class="SIS">getStandardName(Class)</code> convenience method to perform this operation. - </p> - - <p> - The reverse operation â getting the Java class and method from a standard name â is a bit more complicated. - It requires reading the <code class="GeoAPI">class-index.properties</code> file provided in the <code>org.opengis.annotation</code> package. - The following example reads the files just before searching for the name of the interface corresponding to <code>CI_Citation</code>. - Users are always encouraged to only read this file once and then save its contents in their application's cache. - </p> - -<pre>Properties isoToGeoAPI = new Properties(); -try (InputStream in = UML.class.getResourceAsStream("<code class="GeoAPI">class-index.properties</code>")) { - isoToGeoAPI.load(in); -} -String isoName = "<code class="OGC">CI_Citation</code>"; -String geoName = getProperty(isoName); -Class<?> type = Class.forName(geoName); -System.out.println("The GeoAPI interface for <abbr>ISO</abbr> type " + isoName + " is " + type);</pre> - - <p> - The class <code>org.apache.sis.util.iso.Types</code> provides the - <code class="SIS">forStandardName(String)</code> convenience method to perform this operation. - </p> - - - - <h3 id="MappingToJDK">Implicit Mapping to Standard <abbr>JDK</abbr></h3> - <p> - Some classes and methods have neither an <code>@UML</code> annotation, nor an entry in the <code class="GeoAPI">class-index.properties</code> file. - They are either extensions of GeoAPI, or else types defined in other libraries, such as standard <abbr title="Java Development Kit">JDK</abbr>. - In this last case, the mapping to <abbr>ISO</abbr> standards is implicit. - The following table describes this mapping for <abbr>ISO</abbr> 19103 types. - Java's primitive types are preferred when applicable, - but where necessary their wrappers are used in order to authorize null values. - </p> - <table> - <caption>Mapping between <abbr>ISO</abbr> 19103 and <abbr>JDK</abbr> types</caption> - <tr> - <th><abbr>ISO</abbr> type</th> - <th><abbr>JDK</abbr> type</th> - <th>Remarks</th> - </tr> - <tr> - <td class="separator" colspan="2">Numbers</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Integer</code></td> - <td><code>int</code></td> - <td class="leftBorder">Sometimes <code>java.lang.Integer</code> for optional attributes.</td> - </tr> - <tr> - <td><code class="OGC">Integer</code> (in some cases)</td> - <td><code>long</code></td> - <td class="leftBorder">Sometimes <code>java.lang.Long</code> for optional attributes.</td> - </tr> - <tr> - <td><code class="OGC">Real</code></td> - <td><code>double</code></td> - <td class="leftBorder">Sometimes <code>java.lang.Double</code> for optional attributes.</td> - </tr> - <tr> - <td><code class="OGC">Decimal</code></td> - <td><code>java.math.BigDecimal</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Number</code></td> - <td><code>java.lang.Number</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td class="separator" colspan="2">Texts</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">FreeText</code></td> - <td>(no equivalent)</td> - <td class="leftBorder">See <code class="GeoAPI">org.opengis.util.InternationalString</code> below.</td> - </tr> - <tr> - <td><code class="OGC">CharacterString</code></td> - <td><code>java.lang.String</code></td> - <td class="leftBorder">Often <code class="GeoAPI">org.opengis.util.InternationalString</code> (see below).</td> - </tr> - <tr> - <td><code class="OGC">LocalisedCharacterString</code></td> - <td><code>java.lang.String</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Sequence<Character></code></td> - <td><code>java.lang.CharSequence</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Character</code></td> - <td><code>char</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td class="separator" colspan="2">Dates and hours</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Date</code></td> - <td><code>java.util.Date</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Time</code></td> - <td><code>java.util.Date</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">DateTime</code></td> - <td><code>java.util.Date</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td class="separator" colspan="2">Collections</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Collection</code></td> - <td><code>java.util.Collection</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Bag</code></td> - <td><code>java.util.Collection</code></td> - <td class="leftBorder">A <code class="OGC">Bag</code> is similar to a - <code class="OGC">Set</code> without being restricted by uniqueness.</td> - </tr> - <tr> - <td><code class="OGC">Set</code></td> - <td><code>java.util.Set</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Sequence</code></td> - <td><code>java.util.List</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Dictionary</code></td> - <td><code>java.util.Map</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">KeyValuePair</code></td> - <td><code>java.util.Map.Entry</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td class="separator" colspan="2">Enumerations</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Enumeration</code></td> - <td><code>java.lang.Enum</code></td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">CodeList</code></td> - <td>(no equivalent)</td> - <td class="leftBorder">See <code>org.opengis.util.CodeList</code> below.</td> - </tr> - <tr> - <td class="separator" colspan="2">Various</td> - <td class="leftBorder"></td> - </tr> - <tr> - <td><code class="OGC">Boolean</code></td> - <td><code>boolean</code></td> - <td class="leftBorder">Sometimes <code>java.lang.Boolean</code> for optional attributes.</td> - </tr> - <tr> - <td><code class="OGC">Any</code></td> - <td><code>java.lang.Object</code></td> - <td class="leftBorder"></td> - </tr> - </table> - - <p> - The nearest equivalent for <code>CharacterString</code> is the <code>String</code> class, - but GeoAPI often uses the <code>InternationalString</code> interface, allowing the client to choose the language. - For example, it is useful on a server that simultaneously provides pages in multiple languages. - By returning translations when objects are used rather than at the time of their creation, - we allow the <abbr>SIS</abbr> library to provide the same instances of <code>Metadata</code> - or <code>Coverage</code> (for example) for the same data, regardless of the client's language. - Translations may be made on the fly with the help of the application's <code>ResourceBundle</code>, - or may be provided directly with the data (as in the case of <code>Metadata</code>). - </p> - <p> - An <code>Enumeration</code> corresponds to an <code>Enum</code> in Java. - Both define all authorized values, without allowing the user to add any. - A <code class="OGC">CodeList</code> is similar to an enumeration, except that users may add their own items. - Standard <abbr>JDK</abbr> does not offer this possibility. - GeoAPI defines an abstract <code class="GeoAPI">CodeList</code> class that reproduces some of the functionality of <code>Enum</code> while being extensible. - Extensions are made available by the <code class="GeoAPI">valueOf(String)</code> static method, which, in contrast to <code>Enum</code>, - creates new instances if the name provided does not correspond to the name of an existing instance. - </p> - -<pre>MediumName cdRom = MediumName.<code class="GeoAPI">CD_ROM;</code> -MediumName usbKey = MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">USB_KEY</code>"); // There is no constraint on this value. -assert MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">CD_ROM</code>") == cdRom : "valueOf must return existing constants."; -assert MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">USB_KEY</code>") == usbKey : "valueOf must cache the previously requested values.";</pre> - - - - <h2 id="ServiceLoader">Fetching an Implementation of the Interfaces</h2> - <p> - GeoAPI defines factories (<code>Factory</code>) that can create implementations of interfaces. - For example, <code>DatumFactory</code> provides methods that can create instances which implement interfaces of the - <code>org.opengis.referencing.datum</code> package. - A <code>Factory</code> must be implemented by a geospatial library, - and declared as a <i>service</i> as defined by the <code>java.util.ServiceLoader</code> class. - The <code>ServiceLoader</code> javadoc explains this procedure. - In brief, the library must create a file in the <code>META-INF/services/</code> directory, - with a name corresponding to the complete name of an interface in the factory - (in the preceding example, <code>org.opengis.referencing.datum.DatumFactory</code>). - On one line, this text file must include the complete name of the class that implements this interface. - This class may be hidden from users, as they do not need to know of its existence. - </p> - <p> - If the library has correctly declared its factories as services, - users may import them by using <code>ServiceLoader</code>, as in the example below. - This example only takes the first factory located; if there is more than one factory - - for example when multiple libraries coexist â then the choice is left to the user. - </p> - -<pre>import org.opengis.referencing.GeodeticDatum; -import org.opengis.referencing.DatumFactory; -import java.util.ServiceLoader; - -public class MyApplication { - public void createMyDatum() { - ServiceLoader loader = ServiceLoader.load(DatumFactory.class); - DatumFactory factory = loader.iterator().next(); - GeodeticDatum myDatum = factory.<code class="GeoAPI">createGeodeticDatum</code>(â¦); - } -}</pre> - - - - <h3 id="GeoAPI-simple">Defining Custom Implementations</h3> - <p> - Implementing GeoAPI oneself in order to meet very specific needs is not difficult. - A developer might concentrate on a handful of interfaces among the hundreds available, - while keeping other interfaces as extension points to eventually implement as needed. - </p> - <p> - The conceptual model that the interfaces represent is complex. But this complexity may be reduced by combining certain interfaces. - For example, many libraries, even well-known ones, do not distinguish between a <cite>Coordinate System</cite> (<abbr>CS</abbr>) - and a <cite>Coordinate <u>Reference</u> System</cite> (<abbr>CRS</abbr>). - A developer that also wishes not to make this distinction may implement these two interfaces with the same class. - The resulting implementation may have a simpler class hierarchy than that of GeoAPI interfaces. - The <code>geoapi-examples</code> module, discussed later, provides such combinations. - The following table lists a few possible combinations: - </p> - <table> - <tr> - <th>Main Interface</th> - <th>Auxiliary Interface</th> - <th>Use</th> - </tr> - <tr> - <td><code>CoordinateReferenceSystem</code></td> - <td><code>CoordinateSystem</code></td> - <td>Description of a spatial reference system (<abbr>CRS</abbr>).</td> - </tr> - <tr> - <td><code>GeodeticDatum</code></td> - <td><code>Ellipsoid</code></td> - <td>Description of the geodetic datum.</td> - </tr> - <tr> - <td><code>CoordinateOperation</code></td> - <td><code>MathTransform</code></td> - <td>Coordinate transformation operations.</td> - </tr> - <tr> - <td><code>IdentifiedObject</code></td> - <td><code>ReferenceIdentifier</code></td> - <td>An objet (usually a <abbr>CRS</abbr>) that we can identify by a code.</td> - </tr> - <tr> - <td><code>Citation</code></td> - <td><code>InternationalString</code></td> - <td>Bibliographic reference consisting of a simple title.</td> - </tr> - <tr> - <td><code>GeographicBoundingBox</code></td> - <td><code>Extent</code></td> - <td>Spatial area in degrees of longitude and latitude.</td> - </tr> - <tr> - <td><code>ParameterValue</code></td> - <td><code>ParameterDescriptor</code></td> - <td>Description of a parameter (name, type) associated with its value.</td> - </tr> - <tr> - <td><code>ParameterValueGroup</code></td> - <td><code>ParameterDescriptorGroup</code></td> - <td>Description of a set of parameters associated with their values.</td> - </tr> - </table> - - - - <h2 id="GeoAPI-modules">GeoAPI Modules</h2> - <p> - The GeoAPI project consists of a standardized part (<code>geoapi</code>) - and an experimental part (<code>geoapi-pending</code>). - As these two parts are mutually exclusive, users must take care not to mix them in the same project. - This separation is guaranteed for all projects that depend only on the Maven central repository - (including the final versions of Apache <abbr>SIS</abbr>), - as the <code>geoapi-pending</code> module is never deployed on this central repository. - By contrast, certain <abbr>SIS</abbr> development branches may depend on <code>geoapi-pending</code>. - </p> - <p> - GeoAPI modules are: - </p> - <ul> - <li><p> - <b><code>geoapi</code></b> â includes interfaces covered by the - <a href="http://www.opengeospatial.org/standards/geoapi";>GeoAPI standard of the <abbr>OGC</abbr></a>. - The final versions of Apache <abbr>SIS</abbr> depend on this module. - </p></li> - <li><p> - <b><code>geoapi-pending</code></b> â contains a - <em>copy</em> of all interfaces in the <code>geoapi</code> module - (not a dependence) with additions that have not yet been approved as an <abbr>OGC</abbr> standard. - Some additions appear in interfaces normally defined by the <code>geoapi</code> module, hence the need to copy them. - Apache <abbr>SIS</abbr>'s development branches <code>jdk6</code>, <code>jdk7</code> and <code>jdk8</code> depend on this module, - but this dependence becomes a dependence on the <code>geoapi</code> standard module when the branches are merged to the trunk. - </p></li> - <li><p> - <b><code>geoapi-conformance</code></b> â includes a JUnit test suite that developers may use to test their implementations. - </p></li> - <li><p> - <b><code>geoapi-examples</code></b> â includes examples of relatively simple implementations. - These examples are placed in the public domain in order to encourage users to copy and adapt them to their needs if - Apache <abbr>SIS</abbr> services are unsuitable. - </p></li> - <li><p> - <b><code>geoapi-proj4</code></b> â contains a partial implementation of <code>org.opengis.referencing</code> - packages as adaptors based on the C/C++ Proj.4 library. - This module may be used as an alternative to the <code>sis-referencing</code> module for certain functions. - </p></li> - <li><p> - <b><code>geoapi-netcdf</code></b> â contains a partial implementation of <code>org.opengis.referencing</code> - and <code>org.opengis.coverage</code> packages as adaptors based on the <abbr>UCAR</abbr> <abbr>NetCDF</abbr> library. - The series of tests in this module was developed in such a way as to be reusable for other projects. - Apache <abbr>SIS</abbr> uses them to test its own <code>sis-netcdf</code> module. - </p></li> - <li><p> - <b><code>geoapi-openoffice</code></b> â contains an add-in for the OpenOffice.org office suite. - <!-- - Apache <abbr>SIS</abbr> offers its own add-in in the <code>sis-openoffice</code> module, - but uses the same function names as the GeoAPI module in order to maintain some compatibility. - --> - </p></li> - </ul> - - <h3 id="GeoAPI-core">The Interfaces' Definition Modules</h3> - <p> - <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>. - </p> - - - - <h3 id="GeoAPI-conformance">The Conformance Tests Module</h3> - <p> + <p id="GeoAPI-conformance"> The <code>geoapi-conformance</code> module provides <i>validators</i>, a JUnit <i>test suite</i>, and <i>report generators</i> in the form of <abbr title="Hypertext Markup Language">HTML</abbr> pages. This module may be used with any GeoAPI implementation. @@ -654,7 +52,7 @@ public class MyApplication { - <h4 id="GeoAPI-validators">Instance Validations</h4> + <h2 id="GeoAPI-validators">Instance Validations</h2> <p> GeoAPI can validate an instance of its interfaces by checking that certain constraints are observed. Many constraints can not be expressed in the method signature. Those constraints @@ -740,13 +138,13 @@ public class MyTest { - <h4 id="GeoAPI-tests">Executing Pre-defined Tests</h4> + <h2 id="GeoAPI-tests">Executing Pre-defined Tests</h2> <p> JUnit tests are defined in the <code>org.opengis.test</code> sub-packages. All test classes bear a name ending in "<code>Test</code>". GeoAPI also provides an <code>org.opengis.test.TestSuite</code> class including all test classes defined in the <code>geoapi-conformance</code> module, but Apache <abbr>SIS</abbr> does not use it. - Instead, Apache <abbr>SIS</abbr> inherits GeoAPI's <code class="GeoAPI">*Test</code> classes on a case-by-case basis, + Instead, Apache <abbr>SIS</abbr> inherits GeoAPIâs <code class="GeoAPI">*Test</code> classes on a case-by-case basis, in the appropriate modules. The example below gives an example of a customized GeoAPI test: The <a href="http://www.geoapi.org/geoapi-conformance/apidocs/org/opengis/test/referencing/ParameterizedTransformTest.html";>parent test javadoc</a> @@ -793,32 +191,5 @@ public class MyTest extends Parameterize assertTrue(<code class="GeoAPI">transform</code> instanceof MathTransform2D); } }</pre> - - - - <h3 id="GeoAPI-examples">Example Modules</h3> - <p> - The <code>geoapi-examples</code> module provides examples of simple implementations. - Many of these classes implement more than one interface at a time in order to provide a simpler conceptual model. - The <a href="http://www.geoapi.org/geoapi-examples/apidocs/overview-summary.html";>javadoc for this module</a> - lists key packages and classes along with the combinations performed. - This module illustrates not only how GeoAPI might be implemented, - but also how the implementation might be tested using <code>geoapi-conformance</code>. - </p> - <p> - Although its primary goal is to serve as a source of inspiration for implementors, - <code>geoapi-examples</code> was also designed so as to be usable by applications with very simple needs. - As all the examples are in the public domain, developers are invited to freely adapt copies of these classes as necessary. - However, if changes are made outside the framework of the GeoAPI project, - fair use demands that modified copies be placed in a package with a different name than <code>org.opengis</code>. - </p> - <p> - For somewhat more involved needs, developers are invited to examine the - <code>geoapi-proj4</code> and <code>geoapi-netcdf</code> modules. - These two modules provide examples of adaptors that are allowed, via GeoAPI interfaces, - to use some of the features of external libraries (Proj.4 and <abbr>NetCDF</abbr>). - The advantage of using these interfaces is to provide a unified model to operate two very different <abbr>API</abbr>s, - while retaining the ability to switch easily to another library if desired. - </p> </body> </html> Modified: sis/site/trunk/book/fr/body.html URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/body.html?rev=1745551&r1=1745550&r2=1745551&view=diff ============================================================================== --- sis/site/trunk/book/fr/body.html (original) +++ sis/site/trunk/book/fr/body.html Thu May 26 00:52:22 2016 @@ -49,6 +49,8 @@ <xi:include href="referencing.html"/> <xi:include href="geometry.html"/> <xi:include href="coverage.html"/> + <xi:include href="implementation-independence.html"/> + <xi:include href="test.html"/> </main> </body> </html>
