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 <martin.desruisse...@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.
