You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2024/12/06 13:33:39 UTC

(sis) 01/02: Document an extra step needed for a more complete shutdown of the system.

This is an automated email from the ASF dual-hosted git repository.

desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git

commit e93449f33ca7568da11e401e51cd031b62eeff9a
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Fri Dec 6 11:49:27 2024 +0100

    Document an extra step needed for a more complete shutdown of the system.
---
 .../main/org/apache/sis/setup/Configuration.java   | 31 +++++++++++++++++-----
 settings.gradle.kts                                |  1 +
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/Configuration.java b/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/Configuration.java
index a0f0fa7618..a3e2e10a2c 100644
--- a/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/Configuration.java
+++ b/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/Configuration.java
@@ -151,18 +151,35 @@ public final class Configuration {
     }
 
     /**
-     * Shutdowns the Apache SIS library.
-     * This method close database connections and stops daemon threads.
-     * <strong>The Apache SIS library shall not be used anymore after this method call.</strong>
-     * Any use of Apache SIS after this method call may cause undermined behavior.
+     * Shutdowns the Apache <abbr>SIS</abbr> library.
+     * This method closes database connections and stops the daemon threads that were started by <abbr>SIS</abbr>.
+     * <strong>The Apache <abbr>SIS</abbr> library shall not be used anymore after this method call.</strong>
+     * Any use of Apache <abbr>SIS</abbr> after this method call may have unexpected effects.
      * In particular, it may cause memory leaks.
      *
      * <h4>When to use</h4>
-     * This method should generally <strong>not</strong> be invoked, because Apache SIS registers itself
-     * a {@linkplain Runtime#addShutdownHook(Thread) shutdown hook} to the Java Virtual Machine.
-     * This method may be useful in environments that do not allow the use of shutdown hooks,
+     * This method should generally <strong>not</strong> be invoked, because Apache <abbr>SIS</abbr> registers
+     * itself a {@linkplain Runtime#addShutdownHook(Thread) shutdown hook} to the Java Virtual Machine.
+     * This method may be useful in embedded environments that do not allow the use of shutdown hooks,
      * or when waiting for the <abbr>JVM</abbr> shutdown is overly conservative.
      *
+     * <h4>Complete shutdown</h4>
+     * This method shutdowns only the databases used by Apache <abbr>SIS</abbr>.
+     * If Apache Derby is used for the <abbr>EPSG</abbr> database, some Derby daemon threads may still be running.
+     * Those daemons can be ignored in standalone applications, but may need to be stopped in embedded environments.
+     * A complete Derby shutdown can be requested with the following code:
+     *
+     * {@snippet lang="java" :
+     *     Configuration.current().shutdown();
+     *     try {
+     *         DriverManager.getConnection("jdbc:derby:;shutdown=true");
+     *     } catch (SQLException e) {
+     *         // Expected exception as per Derby documentation.
+     *     }
+     *     }
+     *
+     * @see <a href="https://db.apache.org/derby/docs/10.15/devguide/tdevdvlp40464.html">Shutting down Derby</a>
+     *
      * @since 1.5
      */
     public void shutdown() {
diff --git a/settings.gradle.kts b/settings.gradle.kts
index 794ea37440..2c4a36a3d2 100644
--- a/settings.gradle.kts
+++ b/settings.gradle.kts
@@ -84,6 +84,7 @@ dependencyResolutionManagement {
             version("derby") {
                 strictly("[10.0, 11.0[")
                 prefer("10.15.2.0")         // 10.15 is the last series compatible with JDK 11.
+                // If the derby version is updated, search for that version number in Javadoc.
             }
             // Derby vulnerabiliy: https://nvd.nist.gov/vuln/detail/CVE-2022-46337
             // Fix would require an upgrade to Java 21.