This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sis-site.git
The following commit(s) were added to refs/heads/main by this push:
new 5aefe8fb Start to prepare the documentation for SIS 1.5 by modifying
texts impacted by the EPSG upgrade.
5aefe8fb is described below
commit 5aefe8fb4fe9d491c039068af5bb01dc8ac0a002
Author: Martin Desruisseaux <[email protected]>
AuthorDate: Wed Aug 13 12:37:11 2025 +0200
Start to prepare the documentation for SIS 1.5 by modifying texts impacted
by the EPSG upgrade.
---
content/epsg.md | 91 ++++++++++++++++++-----------------------
content/release-management.md | 28 +++++++++++--
content/source.md | 91 ++++++++++++++++++++---------------------
layouts/shortcodes/version.html | 2 +-
4 files changed, 108 insertions(+), 104 deletions(-)
diff --git a/content/epsg.md b/content/epsg.md
index 2f3198f7..8257c2dd 100644
--- a/content/epsg.md
+++ b/content/epsg.md
@@ -41,10 +41,10 @@ For example:
sis crs EPSG:6676
```
-Alternatively if the [JavaFX application](javafx.html) is used, just start the
application.
+Alternatively, if the [JavaFX application](javafx.html) is used, just start
the application.
It may be necessary to open a random data file for triggering the EPSG dataset
initialization.
In both cases, the first time that the command-line tool or JavaFX application
needs to query EPSG,
-it will prompt the user for authorization to download EPSG geodetic dataset
from Maven Central.
+it will prompt the user for authorization to download the EPSG geodetic
dataset from Maven Central.
If the user accepts EPSG terms of use, then a local copy of the EPSG geodetic
dataset will be created
and stored in the `apache-sis-{{% version %}}/data` sub-directory.
@@ -72,84 +72,73 @@ java -Dderby.system.home=apache-sis-{{% version
%}}/data/Databases \
MyMainClass
```
-Alternatively `SIS_DATA` or `derby.system.home` can be set to the path of any
other directory which contain the same files.
+The `SIS_DATA` environment variable or `derby.system.home` Java property
+can be set to the path of any other directory which contain the same files.
# Add a Maven dependency {#maven}
-Maven projects can get the EPSG geodetic dataset automatically, _without any
prompt for terms of use agreement_,
-if they add a `sis-epsg` or `sis-embedded-data` dependency (from
`org.apache.sis.non-free` group) in their project.
+Maven projects can get the EPSG geodetic dataset automatically, _without any
prompt for EPSG Terms of Use agreement_,
+if the users add a `sis-embedded-data` or `sis-epsg` dependency (from
`org.apache.sis.non-free` group) in their project.
Those two approaches have advantages and inconvenient described in following
sub-sections.
-In both cases, we assume that developers who add those dependencies explicitly
in their project agree with
-[EPSG terms of use][EPSG-ToU].
+In both cases, we assume that the developers who add those dependencies
explicitly in their project
+have agreed with the [EPSG Terms of Use][EPSG-ToU].
-## As database installer {#maven-epsg}
-
-With `sis-epsg` artifact on the classpath, Apache {{% SIS %}} will create a
local copy of EPSG database when first needed.
-The target database must be specified by users with *one* of the following
choices:
-
-* Set the `SIS_DATA` environment variable to the path of an initially empty
directory _(recommended)_.
- The specified directory must exist, but sub-directories will be created as
needed.
-* Set the `derby.system.home` Java property to the path of an initially empty
directory,
- or a directory that contain other Derby databases. The specified directory
must exist.
-* Register a `DataSource` under the `java:comp/env/jdbc/SpatialMetadata` name
in a JNDI directory
- (see [next section](#jndi)). The database must exist but can be initially
empty.
-* Set a `DataSource` [from Java
code](./apidocs/org.apache.sis.util/org/apache/sis/setup/Configuration.html).
+## As embedded database {#maven-embedded}
-The Maven dependency is as below (the Derby dependency can be replaced by
another database driver
-if that database is specified by JNDI):
+With `sis-embedded-data` artifact on the classpath, there is no need to setup
environment variable, Java property or JNDI.
+However, this simplicity come at the cost of a larger download with no
possibility to choose the database engine
+(i.e. the database software is fixed to Derby), and no possibility to add's
user data (i.e. the database is read-only).
+This embedded data dependency can be declared as below
+(see the [download](downloads.html#epsg) page for more information about Maven
dependency declaration).
```xml
<dependencies>
<dependency>
<groupId>org.apache.sis.non-free</groupId>
- <artifactId>sis-epsg</artifactId>
+ <artifactId>sis-embedded-data</artifactId>
<version>{{% version %}}</version>
<scope>runtime</scope>
</dependency>
- <dependency>
- <groupId>org.apache.derby</groupId>
- <artifactId>derby</artifactId>
- <version>10.14.2.0</version>
- <scope>runtime</scope>
- </dependency>
</dependencies>
```
-See the [download](downloads.html#epsg) page for more information about Maven
dependency declaration.
-
-## As embedded database {#maven-embedded}
+## As database installer {#maven-epsg}
-With `sis-embedded-data` artifact on the classpath, there is no need to setup
environment variable, Java property or JNDI.
-However this simplicity come with the following inconvenient:
+For applications which already have a database engine, or which use a
different version of the Derby database,
+it may be desirable to install the EPSG geodetic dataset in their existing
database rather than having two databases in parallel.
+With `sis-epsg` artifact on the classpath, Apache {{% SIS %}} will create a
local copy of EPSG database when first needed.
+The target database must be specified by users with *one* of the following
choices:
-* a larger download,
-* no option for choosing which data to use (and consequently which license to
accept),
-* no possibility to choose the database engine (i.e. the database software is
fixed to Derby),
-* no possibility to add user data (i.e. the database is read-only),
-* slower execution of `CRS.forCode(…)` and `CRS.findCoordinateOperation(…)`
methods, unless the JAR file is uncompressed.
+* set the `SIS_DATA` environment variable to the path of an initially empty
directory _(recommended for Derby users)_,
+* or set the `derby.system.home` Java property to the path of an initially
empty directory
+ or a directory that contain other Derby databases,
+* or register a `DataSource` under the `java:comp/env/jdbc/SpatialMetadata`
name in a JNDI directory
+ (see [next section](#jndi)),
+* or set a `DataSource` [from Java
code](./apidocs/org.apache.sis.util/org/apache/sis/setup/Configuration.html).
-This dependency can be declared as below
-(see the [download](downloads.html#epsg) page for more information about Maven
dependency declaration).
-Note that `sis-epsg` and `sis-embedded-data` should not be specified in the
same project; only one is needed:
+In all cases, the specified directory or database must exist but may be empty.
+Sub-directories or database schema will be created as needed.
+Then, the Maven dependency can be declared in a project as below,
+with the Derby dependency replaced by another database driver if desired:
```xml
<dependencies>
<dependency>
<groupId>org.apache.sis.non-free</groupId>
- <artifactId>sis-embedded-data</artifactId>
+ <artifactId>sis-epsg</artifactId>
<version>{{% version %}}</version>
<scope>runtime</scope>
</dependency>
+ <dependency>
+ <groupId>org.apache.derby</groupId>
+ <artifactId>derby</artifactId>
+ <version>10.14.2.0</version>
+ <scope>runtime</scope>
+ </dependency>
</dependencies>
```
-The performance issue can be avoided if the JAR file is uncompressed.
-But uncompressed `sis-embedded-data.jar` file is more than 5 times larger than
the compressed file.
-Given that `CRS.forCode(…)` and `CRS.findCoordinateOperation(…)` should not
be invoked too often,
-and that performance degradation does not apply to the `CoordinateOperation`
instances created by those method calls,
-the JAR file is distributed on the Maven repository in its compressed form.
-If desired, better performance can be achieved by using one of the other
configurations described in this page,
-or by uncompressing the `sis-embedded-data.jar` file locally.
+Note that `sis-epsg` and `sis-embedded-data` artifacts should not be specified
in the same project. Only one is needed.
# Use an existing EPSG database {#existing}
@@ -160,8 +149,6 @@ The database must exist but can be empty, in which case it
will be populated wit
if the <code style="white-space:normal">org.apache.sis.non-free:sis-epsg:{{%
version %}}</code> dependency is on the classpath
(see [above section](#maven-epsg)).
If non-empty, the database should contain the tables created by SQL scripts
downloaded from [EPSG][EPSG].
-**Note thas as of Apache SIS 1.2, only EPSG dataset version 9 is supported.
-EPSG datasets version 10 and later are not yet supported.**
## Registration by Java code {#setup}
@@ -184,7 +171,7 @@ public void MyApp {
}
```
-## Registration by Java Naming and Directory Interface {#jndi-java}
+## Registration by Java Naming and Directory Interface {#jndi}
Registration in JNDI can be done programmatically (by Java code) or by
configuring XML files in some environments.
Registration can be done by the following Java code, provided that a JNDI
implementation is available on the classpath:
diff --git a/content/release-management.md b/content/release-management.md
index fe88f077..7af1ac62 100644
--- a/content/release-management.md
+++ b/content/release-management.md
@@ -260,8 +260,8 @@ Those steps are also useful as additional tests, since
failure to generate those
They are temporary hacks for including deprecated codes in the CRS list to
be generated
(those codes will appear with strike for making clear that they are
deprecated):
- * Search `DEPRECATED=0` (it appears in a SQL fragment) and replace by
`(DEPRECATED=0 OR TRUE)`.
- * Comment-out the `if (table.showColumn != null)` block which appears just
above the `DEPRECATED=0` occurrence.
+ * Search `DEPRECATED=FALSE` (it appears in a SQL fragment) and replace by
`(DEPRECATED=FALSE OR TRUE)`.
+ * Comment-out the `if (table.showColumn != null)` block which appears just
above the `DEPRECATED=FALSE` occurrence.
<br><br>
* Run the following commands:
@@ -417,7 +417,26 @@ Apply the following changes:
* Add the following line in-place of deleted lines (omit the
`org.opengis.geoapi` module if not desired):
```
---module
org.opengis.geoapi,org.apache.sis.util,org.apache.sis.metadata,org.apache.sis.referencing,org.apache.sis.referencing.gazetteer,org.apache.sis.feature,org.apache.sis.storage,org.apache.sis.storage.sql,org.apache.sis.storage.xml,org.apache.sis.storage.netcdf,org.apache.sis.storage.geotiff,org.apache.sis.storage.earthobservation,org.apache.sis.cloud.aws,org.apache.sis.portrayal,org.apache.sis.profile.france,org.apache.sis.profile.japan,org.apache.sis.openoffice,org.apache.sis.conso
[...]
+--module \
+org.opengis.geoapi,\
+org.apache.sis.util,\
+org.apache.sis.metadata,\
+org.apache.sis.referencing,\
+org.apache.sis.referencing.gazetteer,\
+org.apache.sis.feature,\
+org.apache.sis.storage,\
+org.apache.sis.storage.sql,\
+org.apache.sis.storage.xml,\
+org.apache.sis.storage.netcdf,\
+org.apache.sis.storage.geotiff,\
+org.apache.sis.storage.earthobservation,\
+org.apache.sis.cloud.aws,\
+org.apache.sis.portrayal,\
+org.apache.sis.profile.france,\
+org.apache.sis.profile.japan,\
+org.apache.sis.openoffice,\
+org.apache.sis.console,\
+org.apache.sis.gui
```
The following commands temporarily create links to optional modules for
inclusion in the Javadoc.
@@ -688,7 +707,8 @@ unzip apache-sis-$NEW_VERSION-bin.zip
cd apache-sis-$NEW_VERSION
unset SIS_DATA
./bin/sis about --verbose
-./bin/sis crs
https://raw.githubusercontent.com/apache/sis/main/endorsed/src/org.apache.sis.referencing/test/org/apache/sis/referencing/crs/ProjectedCRS.xml
--format WKT
+./bin/sis crs --format WKT \
+https://raw.githubusercontent.com/apache/sis/main/endorsed/src/org.apache.sis.referencing/test/org/apache/sis/referencing/crs/ProjectedCRS.xml
```
diff --git a/content/source.md b/content/source.md
index 20705f8f..50047b56 100644
--- a/content/source.md
+++ b/content/source.md
@@ -9,7 +9,7 @@ which is subject to licensing terms different than Apache ones.
This page describes two ways to checkout Apache {{% SIS %}} source code:
* A basic checkout with only the main repository, the most stable branch, and
no configuration requirement.
-* A more advanced configuration for active SIS developments, using uncommitted
(for now) API
+* A more advanced configuration for active {{% SIS %}} developments, using
uncommitted (for now) API
and including optional data for more extensive tests.
It is possible to start with the basic checkout and migrate to the advanced
configuration later,
@@ -21,21 +21,18 @@ or to cherry-pick only the interesting parts of the
advanced configuration.
# Basic installation {#basic}
Create an empty directory for the Apache {{% SIS %}} project.
-We use `ApacheSIS` directory name in this page, but that name can be anything.
+We use `SIS` directory name in this page, but that name can be anything.
Replace that name in the shell commands below if another name is used.
The Apache {{% SIS %}} source code can be cloned in that directory as below
(lines starting with `#` are comments and can be ignored):
```bash
-mkdir ApacheSIS
-cd ApacheSIS
-git clone https://gitbox.apache.org/repos/asf/sis
-#
+mkdir SIS
+cd SIS
+git clone https://gitbox.apache.org/repos/asf/sis main
+
# Alternatively, GitHub mirror can also be used:
-# git clone https://github.com/apache/sis
-#
-# or Subversion (read-only):
-# svn checkout https://github.com/apache/sis/trunk
+# git clone https://github.com/apache/sis main
```
If JavaFX is available on the local machine,
@@ -43,21 +40,21 @@ its JAR files location can be specified as below
(edit the `/usr/lib/jvm/openjfx` path as needed).
The JavaFX application is excluded by default because it depends on
the [JavaFX platform][JavaFX] which is distributed under GPL license
-(note that the SIS module stay under Apache 2 licence).
+(note that the Apache {{% SIS %}} module using JavaFX stay under Apache 2
licence).
```bash
# Syntax for Unix shell
export PATH_TO_FX=/usr/lib/jvm/openjfx
```
-Likewise the [EPSG geodetic dataset](epsg.html) is excluded by default for
licensing reasons.
+Likewise, the [EPSG geodetic dataset](epsg.html) is excluded by default for
licensing reasons.
Then, Apache {{% SIS %}} can be built as below:
```bash
-cd sis
+cd main
gradle assemble
-gradle publishToMavenLocal # If use with Maven projects is desired.
+gradle publishToMavenLocal # If usage with Maven projects is desired.
```
Outputs will be located in the following sub-directories:
@@ -73,7 +70,7 @@ The remaining of this page describes optional configurations
for more advanced d
# Advanced installation {#advanced}
-This section assumes that above-described basic checkout has been done.
+This section assumes that the above-described basic checkout has been done.
All subsections below are optional, but the "Create data directory" one
is recommended because some other subsections depend on it.
@@ -82,8 +79,8 @@ is recommended because some other subsections depend on it.
Apache {{% SIS %}} needs a directory where to store database, datum shift
files and other optional data.
That directory is specified by the `SIS_DATA` environment variable and can be
located anywhere.
-A convenient location is a subdirectory of the `ApacheSIS` directory created
in the "basic checkout" section.
-For example (with `ApacheSIS` as the current directory):
+A convenient location is a subdirectory of the `SIS` directory created in the
"basic checkout" section.
+For example (with `SIS` as the current directory):
```bash
mkdir Data
@@ -105,34 +102,31 @@ of coordinate reference systems can be created from EPSG
codes.
The EPSG database can be [installed in various ways][epsg-install],
but this section describes an alternative way more suitable to Apache {{% SIS
%}} development.
Before to continue, make sure to agree with [EPSG terms of use][EPSG-ToU].
-Then following command can be executed with `ApacheSIS` as the current
directory:
+Then, the following command can be executed with `SIS` as the current
directory:
```bash
# Executing this command imply agreement with EPSG terms of use.
svn checkout https://svn.apache.org/repos/asf/sis/data/non-free/
```
-Then copy or link the EPSG scripts in the directory where Apache {{% SIS %}}
looks for optional data.
-Adjust the relative paths as needed if the `SIS_DATA` environment variable
-points to another location than the one used in above section:
+Then, link the EPSG scripts in the directory where Apache {{% SIS %}} looks
for optional data.
+Adjust the relative paths as needed if the `main` and `non-free` repositories
have been check out
+in other locations than the ones used in above section:
```bash
-mkdir $SIS_DATA/Databases
-mkdir $SIS_DATA/Databases/ExternalSources
-cd $SIS_DATA/Databases/ExternalSources
-ln -s
../../../non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/Data.sql
EPSG_Data.sql
-ln -s
../../../non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/FKeys.sql
EPSG_FKeys.sql
-ln -s
../../../non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/Tables.sql
EPSG_Tables.sql
+cd
main/optional/src/org.apache.sis.referencing.epsg/main/org/apache/sis/referencing/factory/sql/epsg
+ln --symbolic ../../../../../../../../../../../../non-free/EPSG/* .
cd -
```
-This is sufficient for allowing Apache {{% SIS %}} to create the geodetic
database
-without the need for `sis-epsg` or `sis-embedded-data` module on the classpath.
-This setting is not done automatically because Apache projects cannot introduce
-non-free dependencies without explicit action from user.
-If this action is not taken, some JUnit tests requiring EPSG data may be
skipped.
-If any EPSG file is updated, deleting the
`$SIS_DATA/Databases/SpatialMetadata` directory
-is sufficient for causing Apache {{% SIS %}} to recreate the Derby database
with new data.
+For creating the EPSG database from those scripts, delete the old Derby
database (if it exists) and rebuild Apache {{% SIS %}}.
+Note that it may be useful to test {{% SIS %}} twice for making sure that all
tests were run while the database was present.
+
+```bash
+cd main
+rm --recursive $SIS_DATA/Databases/SpatialMetadata
+gradle test --rerun
+```
## Configure PostgreSQL {#postgres}
@@ -189,15 +183,15 @@ This requirement has been added for avoiding undesired
interference with host.
## Running extensive tests {#tests}
-A simple `gradle test` execution in the `sis` directory
+A simple `gradle test` execution in the `main` directory
will build and test Apache {{% SIS %}} with the default set of JUnit tests.
Some tests are skipped by default, either because they would have some effects
outside
-the `sis` directory (for example writing in `SpatialMetadataTest` database on
PostgreSQL),
+the `main` directory (for example writing in `SpatialMetadataTest` database on
PostgreSQL),
or because those tests take a long time to execute.
For enabling all tests, use the following command:
```bash
-cd sis
+cd main
export SIS_TEST_OPTIONS=extensive,postgresql
gradle test
```
@@ -208,7 +202,7 @@ gradle test
The source code repository contains `main`, `geoapi-3.1` and `geoapi-4.0`
branches.
Apache {{% SIS %}} releases are created from `main`, which depends on the
latest GeoAPI version
released by the Open Geospatial Consortium (OGC), currently [GeoAPI
3.0.2][geoapi-stable].
-However daily developments occur on the `geoapi-4.0` branch before to be
merged (indirectly) to `main`.
+However, daily developments occur on the `geoapi-4.0` branch before to be
merged (indirectly) to `main`.
Those branches exist in order to experiment early new API and technologies —
since they may impact
the library design — while keeping the releases compatible with officially
released API.
In summary:
@@ -222,7 +216,7 @@ When commits reach `main` they become unmodifiable; the
`git push --force` comma
Contributors to Apache {{% SIS %}} project should switch to the current
development branch before submitting patches:
```bash
-cd sis
+cd main
git checkout geoapi-4.0
```
@@ -242,12 +236,14 @@ All resource files are copied to the build directory,
except those with the foll
The `properties` files are handled in a special way.
Localized resources are provided in `*.properties` files as specified by the
`java.util.PropertyResourceBundle` standard class.
-However SIS does not use those resources files directly. Instead
`*.properties` files are transformed into binary files having
-the same filename but the `.utf` extension. This conversion is done for
efficiency, for convenience (the compiler applies the
-`java.text.MessageFormat` _doubled single quotes_ rule itself), and for
compile-time safety.
+However, Apache {{% SIS %}} does not use those resources files directly.
+Instead `*.properties` files are transformed into binary files having the same
filename but the `.utf` extension.
+This conversion is done for efficiency,
+for convenience (the compiler applies the `java.text.MessageFormat` _doubled
single quotes_ rule itself),
+and for compile-time safety.
In addition to generating the `*.utf` files, the resource compiler may modify
the `*.java` files having the same name than the
-resource files. For example given a set of `Vocabulary*.properties` files (one
for each supported language), the compiler will
+resource files. For example, given a set of `Vocabulary*.properties` files
(one for each supported language), the compiler will
generate the corresponding `Vocabulary*.utf` files, then look for a
`Vocabulary.java` source file. If such source file is found
and contains a public static inner class named `Keys`, then the compiler will
rewrite the constants declared in that inner class
with the list of keys found in the `Vocabulary*.properties` files.
@@ -265,11 +261,12 @@ and can be [browsed online][viewvc].
Tags for Apache {{% SIS %}} versions 0.1 to 0.8 should be fetched from the
[SVN repository][svn-sis-tags].
The development branches on that repository were named `JDK8`, `JDK7`, `JDK6`
and `trunk`.
-[subversion]: http://subversion.apache.org
-[git]: http://git-scm.com
+[subversion]: https://subversion.apache.org
+[git]: https://git-scm.com
[viewvc]: http://svn.apache.org/viewvc/sis/
+[JavaFX]: https://openjfx.io/
[epsg-install]: epsg.html
[EPSG-ToU]: https://epsg.org/terms-of-use.html
[svn-sis-tags]: https://svn.apache.org/repos/asf/sis/tags/
-[geoapi-stable]: http://www.geoapi.org/3.0/index.html
-[geoapi-snapshot]: http://www.geoapi.org/snapshot/index.html
+[geoapi-stable]: https://www.geoapi.org/3.0/index.html
+[geoapi-snapshot]: https://www.geoapi.org/snapshot/index.html
diff --git a/layouts/shortcodes/version.html b/layouts/shortcodes/version.html
index 840ca8cb..400122e6 100644
--- a/layouts/shortcodes/version.html
+++ b/layouts/shortcodes/version.html
@@ -1 +1 @@
-1.4
\ No newline at end of file
+1.5
\ No newline at end of file
