content/developer-guide/introduction/Conventions.html (66 lines of code) (raw):
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>Conventions</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../book.css"/>
</head>
<body>
<!--
Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
by the `org.apache.sis.buildtools.book` class in `buildSrc`.
-->
<section>
<header>
<h2 id="TypographicConventions">Typographic conventions in this document</h2>
</header>
<p>
The elements defined in a computer language, such as classes and methods in Java or elements in an <abbr>XML</abbr> document,
appear in monospaced font in this document.
In order to facilitate an understanding of the relationships between Apache <abbr>SIS</abbr> and the standards,
these elements are also represented using the following color codes:
</p>
<ul>
<li>
Elements in blue are defined in an <abbr title="International Organization for Standardization">ISO</abbr>
or <abbr title="Open Geospatial Consortium">OGC</abbr> standard other than GeoAPI.
</li>
<li>
Elements in green are Java element defined in GeoAPI.
</li>
<li>
Elements in brown are defined in Apache <abbr title="Spatial Information System">SIS</abbr>.
</li>
<li>
Elements left in black are either defined elsewhere (for example the standard Java library),
or there is no emphasis on that element for the discussion.
</li>
</ul>
<p>
For example to represent a projected coordinate reference system (Mercator, Lambert, <i>etc</i>),
<code class="OGC">SC_ProjectedCRS</code> is an <abbr>UML</abbr> and <abbr>XML</abbr> element defined by the <abbr>ISO</abbr> 19111 standard.
Then <code class="API">org.opengis.referencing.crs.<b>ProjectedCRS</b></code> is the implementation-neutral GeoAPI interface derived from that standard,
and <code class="SIS">org.apache.sis.referencing.crs.<b>DefaultProjectedCRS</b></code> is the implementation class provided by Apache SIS.
</p>
</section>
<section>
<header>
<h2 id="CodingConventions">Coding conventions in Apache <abbr>SIS</abbr></h2>
</header>
<p>
Apache SIS implements most GeoAPI interfaces by a classes of the same name than the interface
but prefixed by <code>Abstract</code>, <code>Default</code> or <code>General</code> word.
The <code>General</code> prefix is sometimes used instead of <code>Default</code>
to indicate that alternative implementations are available for some specific cases.
For example the <code class="API">Envelope</code> interface is implemented by at least two Apache SIS classes:
<code class="SIS">GeneralEnvelope</code> and <code class="SIS">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.
However many <abbr>SIS</abbr> 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 despite being conceptually abstract.
Such instantiations should be avoided, but are nevertheless permitted in last resort when it is not possible to determine the exact subtype.
</p>
</section>
</body>
</html>