Source code

Apache SIS source code is maintained using Git version control. Additional data not included in SIS releases are maintained separately using Subversion version control. Those data include in particular the EPSG geodetic dataset and are subject to different licensing terms. The Git repository is mirrored on GitHub and the non-free data can be browsed online. For fetching the source code and those additional data, use the following commands:

git clone https://gitbox.apache.org/repos/asf/sis
svn checkout https://svn.apache.org/repos/asf/sis/data/non-free/

The source code repository contains geoapi-3.1 and geoapi-4.0 branches in addition of master. The Apache SIS releases are created from the code on master only. However the actual development occurs on the geoapi-4.0 branch before to be merged to master. Those branches exist in order to experiment early new API and technologies — since it may impact the library design — while keeping the releases compatible with officially released environments. The remaining of this page gives some guidelines about the way SIS source code is organized.

Development branches

Users who want stability are encouraged to build from the master. The master depends on GeoAPI 3.0.1, which is the latest GeoAPI released by the Open Geospatial Consortium (OGC). Developers who want to contribute to Apache SIS are encouraged to use the geoapi-4.0 branch for now.

GeoAPI 4.0 branch

The geoapi-4.0 branch is the recommended development branch for now. This branch implements the interfaces defined in GeoAPI 4.0 snapshot milestones. This branch uses new interfaces introduced in GeoAPI 4.0-SNAPSHOT and contains upgrades for changes in existing GeoAPI interfaces. Some changes in GeoAPI 4.0-SNAPSHOT interfaces are incompatible with GeoAPI 3.0.1 interfaces. They are caused by changes in the underlying international standards, or by evolution of Java technology. The content of this branch may be fully merged to master in the future, depending on new GeoAPI releases from OGC.

GeoAPI 3.1 branch

The geoapi-3.1 branch implements the interfaces defined in GeoAPI 3.1 snapshot milestones. It has the same content that the geoapi-4.0 branch, excluding changes that are incompatible with GeoAPI 3.0.1. Developments happen on geoapi-4.0 and are periodically merged to geoapi-3.1 with the necessary modifications. This branch is used merely as an intermediate step between the development branch (geoapi-4.0) and master. Its content may be fully merged to master in the future, after new GeoAPI releases from OGC.

Master

The master is a merge of geoapi-3.1 branch ported to the interfaces defined by the GeoAPI stable release. This is the code which is built by the continuous integration system and deployed on the Maven repository. Commits on master can not be removed, since git push --force are not allowed on this branch. Commits should be pushed on above-cited development branch first, so they can be rearranged if needed before merge to master.

Code differences

The main differences (apart version number) between master and geoapi-3.1/4.0 branches are the modifications necessary for implementing an older version of GeoAPI interfaces. In particular, usages of non-released GeoAPI interfaces may be replaced by direct usages of the corresponding Apache SIS implementation classes.

For security reasons and for avoiding misleading information, the following functionalities are disabled on master for now (but are still enabled on branches as experimental features). In particular the Supervisor.ENABLED flag controls whether the MBeans documented in the org.apache.sis.console package are enabled or not.

  • In core/sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java, the ENABLED flag is set to false.
  • In core/sis-utility/src/main/java/org/apache/sis/internal/util/TemporalUtilities.java, the REPORT_MISSING_MODULE flag is set to false.

Behavioral differences

Because of changes between GeoAPI 3.0 and GeoAPI 4.0-SNAPSHOT, the following aspects need special care:

  • If op is an instance of PassThroughOperation, then the if (op instanceof SingleOperation) expression evaluates to true on master but to false on SIS development branches.

History

All developments and tags prior Apache SIS 1.0 were done on a Subversion repository and can be browsed online. Tags for Apache SIS versions 0.1 to 0.8 should be fetched from the SVN repository. The development branches on that repository were named JDK8, JDK7, JDK6 and trunk.

Opening Apache SIS in an IDE

Different SIS branches are available depending on the GeoAPI versions. The alternatives are listed in above section. One thing to take in consideration can be summarized as below:

  • There is no need to build GeoAPI prior working on SIS master.
  • When working on a SIS development branch, we recommend to build GeoAPI 4.0-SNAPSHOT locally first.

While the primarily SIS build system is Maven, the project provides some IDE configuration files for developers convenience. Before opening the project in an IDE, the source code needs to be downloaded from the source repository and the project built at least once using Maven:

git clone https://gitbox.apache.org/repos/asf/sis.git
cd sis
mvn install

NetBeans

NetBeans can open Maven projects natively. This is the recommended approach for casual working in a small amount of SIS modules. For extensive work on Apache SIS or for work impacting many modules, it may be more convenient and faster to open Apache SIS as a NetBeans project. Such pre-configured NetBeans project is available in the ide-project/NetBeans directory. This project will fetch dependencies directly from the .m2/repository local directory, and will refer to the resources *.utf files compiled by Maven in the sis-*/target directories. Consequently it is important to run mvn install before opening the project and after any change in the project dependencies or in the resources.

Users can customize their project configuration by editing the ide-project/NetBeans/nbproject/private/config.properties file. The private directory is excluded by the versioning system, so it okay to put user-specific information there. For example in order to overwrite the default location of the local Maven repository and to define a system property at execution time, one can use:

maven.repository = /path/to/my/local/repository
run.jvmargs = -DmyProperty=myValue

Eclipse

Execute the svn checkout to mvn install commands documented in the beginning of this section, then execute the following steps:

  • Execute mvn eclipse:eclipse on the command line.
  • Open Eclipse in a new workspace.
  • Go to EclipsePreferencesGeneralWorkspace.
  • Change Text file encoding to Other: UTF-8, press Apply, then Ok.
  • Go to FileImportGeneralExisting Projects in Workspace.
  • Choose the sis directory and import.

License header

All Java source files (*.java) shall begin with the current ASF license header as described in ASF Source Header. Properties source files (*.properties) used as inputs to some processor (e.g. the resource compiler) shall have the same license header, but with lines prefixed by # instead of *. Properties files distributed as-is in the JAR files can summarize the license on a single line for saving space, as below:

# Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.

Naming convention

Classes that do not implement an interface are usually not prefixed, even if abstract. Classes implementing GeoAPI interfaces usually (but not always) begin with Abstract, Default, Simple or General prefix.

  • The Abstract prefix is used when a class is abstract according ISO specifications — it may or may not be be abstract in the Java sense.
  • The General prefix is used when an implementation is designed for use in the general case, as opposed to other implementations specialized for a fixed number of dimensions or other conditions.
  • Implementations specialized for a fixed number of dimensions are suffixed with 1D, 2D, 3D or 4D rather than being prefixed.

Example: GeneralEnvelope class is an implementation of Envelope interface for the multi-dimensional case. Envelope2D is another implementation of the same interface specialized for the two-dimensional case.

Internal packages

All classes in org.apache.sis.internal sub-packages are for SIS usage only and may change without warning in any future release. Those classes are excluded from Javadoc and will not be exported by SIS Jigsaw modules. Those packages may be renamed after SIS upgraded to JDK 9.

Substitution for non-existent classes

When using a JDK 9 class that does not exist on JDK 8, define a class of the same name in a org.apache.sis.internal sub-package with the minimal amount of needed functionalities, provided that it can be done with reasonable effort. Otherwise just delete the JDK9-dependent code from the development branch.

Code formatting

Apache SIS uses the standard Java conventions, except for the 80 characters line length restriction. The conventions listed below are guidelines. Some exceptions to those conventions can occur but should be rare (see exceptions to coding conventions).

For making merges between branches easier, refrain from doing massive code reformatting unless:

  • the modified files do not yet exist on the other branches;
  • or the modified lines are known to be identical on all active branches (merges work well in such cases);
  • or the committer is willing to resolve the merge conflicts.

Import statements

Isolate at the end of the imports section any import statements that are specific to a platform. This separation allows any branch to re-arrange the common import statements without generating conflicts with the platform-dependent import statements. Example:

import java.io.File;
import java.util.List;
import org.opengis.metadata.Metadata;

// Branch-specific imports
import org.opengis.feature.Feature;

Spaces and line length

  • Indentation: Use a consistent space indents and never use tabs.
    • Use 4 space indents for Java files.
    • Use 2 space indents for XML files, because ISO/OGC XML schemas tend to have a very deep structure.
  • Space after keyword: Put a space after if, else, for, try, catch and similar keywords (not after method names).
  • Trailing Whitespaces: Remove all trailing whitespaces.
    • Eclipse users can use the Source - Cleanup option to accomplish this.
    • NetBeans users can use the use the Source - Remove trailing spaces on a file-by-file basis, or set the Preferences - Editor - On Save - Remove trailing whitespaces option.
  • Line wrapping: Use 120-column line width for Java code and Javadoc. Some exceptions to this rule may exist for preserving tabular structures, but should be rare.

Brackets

  • Curly brackets: The { and } brackets are mandatory for if, else, while and other blocks, except if the instruction after the keyword is on the same line (e.g. else if).

Member declarations

  • Class, method and field declarations shall use the keywords in the following order. This is known as the "customary order" in the Java Language Specification:
    • public, protected or private,
    • abstract or static,
    • final,
    • strictfp (should be applied on all test classes).
  • Member fields do not have any particular prefix (no m_ prefix).

Exceptions to coding conventions

Many mathematical operations in a two-dimensional space (or more) have symmetry. Formatting the code in a way that emphase their symmetrical nature, for example aligning identical terms in columns, can help to understand the overall pattern and to identify bugs. Example:

if (x < xmin) xmin = x;
if (x > xmax) xmax = x;
if (y < ymin) ymin = y;
if (y > ymax) ymax = y;

The decision to use standard or tabular format is made on a case-by-case basis. Of course, tabular format shall not be abused.

Documentation formatting

Apache SIS uses the standard Javadoc conventions, except for the 80 characters line length restriction. Javadoc lines should not exceed 120 characters, but exceptions to this rule may exist for preserving the structure of <table> elements.

Javadoc annotations

SIS uses standard javadoc annotations. The meaning of some tags are refined as below:

  • @since - the SIS version when the annotated element (class, method, etc.) was first introduced.
  • @version - the last SIS version when the code of the annotated class got a significant change.
  • @author - developer name in FirstName LastName (Organization) format. A separated @author tag is added for each developer. The intent is to allow other developers to know to who to ask questions if needed.

In addition, the sis-build-helper modules provides the following custom javadoc taglets:

Javadoc tag Description
@module Create links to the module where the class is defined, source code and Maven artifacts.
{@include} Include the content of a given HTML file below a <h2> section having the given title.
{@preformat} An inline taglet for pre-formatted text. The first word inside the taglet shall be one of java, xml, sql, wkt, text, math or shell.

HTML elements

HTML tags and entities shall be used only when there is no equivalent Javadoc tag. For example:

  • Instead of "<code>✎</code>", use "{@code ✎}".
  • Instead of "a &lt; b &lt; c", use "{@literal a < b < c}".
  • Instead of "<pre>✎</pre>" for a Java listing, use "{@preformat java ✎}" (this Javadoc tag is specific to Apache SIS — see above table).

Paragraphs

Usages of the <p> tag should be relatively rare, since we use CSS styles (see below) as much as possible for controlling the margin between elements like lists and tables. Do not use <p> for the first paragraph in a package, class or member documentation, or for the first paragraph after a </ul>, </ol>, </table>, </blockquote>, </pre>, or {@preformat} element. The <p> tag shall be used only for separating a new paragraph from a previous one. In such cases, <p> shall have a matching </p> tag at the paragraph end in order to form valid HTML.

Javadoc CSS

Avoid using HTML attributes other than class as much as possible. Instead, rely on styling. Some HTML tags having a style definition in Apache SIS are:

HTML tag Description
<div class="section"> Header of a sub-section in a package, class or member description.
<div class="note"> Indented text with smaller font, used for notes or examples.
<div class="warning"> Text in red color, used for warning about probable API changes.
<ul> and <ol> Default list styles with few space between items (suitable for compact lists).
<ul class="verbose"> A list style with space between items. Used for lists having verbose (multi-lines) items.
<table class="compact"> Table without border and no space between rows. Used for lists with columns alignment.
<table class="sis"> Table with a border, blue headers, light background and some space between columns.
<th class="hsep"> In SIS tables, draw a line on the top border. Used for drawing table section separators.
<th class="sep"> In SIS tables, draw a bright line on the left border. Used for drawing column separators.
<td class="sep"> In SIS tables, draw a bright line on the left border. Used for drawing column separators.

MathML elements

The source code occasionally uses MathML for formulas that are difficult to render with only Unicode characters. PNG images are not extensively used for formulas because they are difficult to edit after creation, and their content are invisible to search operations (for example when a variable is renamed). For examples of MathML usage in SIS, search for the <math …> XML tag in Java source files (note: there is also legacy {@preformat math …} custom Javadoc tags, but they may be phased out as MathML adoption increase). For an introduction to MathML, see:

MathML is supported natively in Firefox, Safari and Opera. Internet Explorer users need to install a plugin. Firefox users can optionally install the fonts for Mozilla's MathML engine for better results. Note that a JavaScript display engine is available for all browsers, but not yet used by SIS.