This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
The following commit(s) were added to refs/heads/geoapi-4.0 by this push:
new aae90cf2a1 Documentation, deprecation.
aae90cf2a1 is described below
commit aae90cf2a15d59170df933b199ac7ba0cc12a162
Author: Martin Desruisseaux <[email protected]>
AuthorDate: Fri Oct 2 16:56:32 2026 +0200
Documentation, deprecation.
---
.../main/module-info.java | 10 +++++++---
.../main/org/apache/sis/util/Exceptions.java | 22 +++++++++++++++++++++-
.../main/org/apache/sis/util/Localized.java | 9 ++++++++-
.../org/apache/sis/util/LocalizedException.java | 5 ++++-
4 files changed, 40 insertions(+), 6 deletions(-)
diff --git a/endorsed/src/org.apache.sis.storage.sql/main/module-info.java
b/endorsed/src/org.apache.sis.storage.sql/main/module-info.java
index 416941c47d..c9065ba537 100644
--- a/endorsed/src/org.apache.sis.storage.sql/main/module-info.java
+++ b/endorsed/src/org.apache.sis.storage.sql/main/module-info.java
@@ -39,12 +39,16 @@
* </ul>
*
* <h2>Recommended database configuration</h2>
- * <p><b>PostgreSQL</b> databases should have the PostGIS extension installed
(optional but recommended).</p>
+ * This module has been tested with PostgreSQL, Oracle, SQLite, DuckDB, HSQL,
H2 and Derby.
+ * Other database engines should work if they are <abbr>ANSI</abbr> compliant
but have not been tested.
*
- * <p><b>MySQL/MariaDB</b> databases should set the <abbr>SQL</abbr> mode to
at least {@code NO_BACKSLASH_ESCAPES}.
- * See <a
href="https://mariadb.com/docs/server/server-management/variables-and-modes/sql_mode#no_backslash_escapes";>
+ * <p><b>MySQL/MariaDB</b> databases should set their <abbr>SQL</abbr> mode to
an <abbr>ANSI</abbr>-compliant mode.
+ * The options should contain at least {@code NO_BACKSLASH_ESCAPES}. For
instructions about how to set options, see
+ * <a
href="https://mariadb.com/docs/server/server-management/variables-and-modes/sql_mode#no_backslash_escapes";>
* MariaDB documentation</a>.</p>
*
+ * <p><b>PostgreSQL</b> databases should have the PostGIS extension installed
(optional but recommended).</p>
+ *
* @author Johann Sorel (Geomatys)
* @author Martin Desruisseaux (Geomatys)
* @author Alexis Manin (Geomatys)
diff --git
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/Exceptions.java
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/Exceptions.java
index dce95e41d0..e0826556a6 100644
--- a/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/Exceptions.java
+++ b/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/Exceptions.java
@@ -33,8 +33,25 @@ import org.apache.sis.util.collection.BackingStoreException;
/**
* Static methods working with {@link Exception} instances.
*
+ * <h2>Policy on exception message locale</h2>
+ * Exceptions thrown by Apache <abbr>SIS</abbr> generally applies the
following policy.
+ * This is applied on a best effort basis only:
+ *
+ * <ul>
+ * <li>{@link Exception#getMessage()} returns the message in the {@linkplain
Locale#getDefault() default locale}.
+ * In a client-server architecture, this is often the locale on the
server side.</li>
+ * <li>{@link Exception#getLocalizedMessage()} returns the message in a
locale specified by
+ * {@link Localized#getLocale()}.
+ * In a client-server architecture, this is often the locale on the
client side.</li>
+ * </ul>
+ *
+ * <p><b>Example:</b>
+ * If an error occurred while a Japanese client connected to an European
server, the localized message may be sent
+ * to the client in Japanese language while the same error may be logged on
the server side in the French language.
+ * This allows system administrator to analyze the issue without the need to
understand client's language.</p>
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
- * @version 1.3
+ * @version 1.7
* @since 0.3
*/
public final class Exceptions {
@@ -68,7 +85,10 @@ public final class Exceptions {
* argument was {@code null} or if the exception does not contain
a message.
*
* @see LocalizedException#getLocalizedMessage()
+ *
+ * @deprecated Depends on {@link LocalizedException}, which has been
deprecated.
*/
+ @Deprecated(since = "1.7", forRemoval = true)
public static String getLocalizedMessage(final Throwable exception, final
Locale locale) {
if (exception == null) {
return null;
diff --git
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/Localized.java
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/Localized.java
index c5be805ed9..ae440f7f9b 100644
--- a/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/Localized.java
+++ b/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/Localized.java
@@ -21,7 +21,14 @@ import java.util.Locale;
/**
* Interface of classes for which each instance is configured for a particular
locale.
- * Those classes are often parsers or formatters.
+ * Implementations of {@code Localized} are often parsers or formatters
configured for
+ * a locale specified at construction time.
+ *
+ * <h2>Localized exception messages</h2>
+ * When a class implementing this {@code Localized} interface throws an
exception,
+ * the error message returned by {@link Exception#getLocalizedMessage()} will
often
+ * be in the locale returned by {@link #getLocale()} instead of the default
locale.
+ * This policy is applied on a best effort basis only.
*
* @author Martin Desruisseaux (Geomatys)
* @version 0.3
diff --git
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/LocalizedException.java
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/LocalizedException.java
index 95f1490d33..1f5c1a35cb 100644
---
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/LocalizedException.java
+++
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/LocalizedException.java
@@ -46,13 +46,16 @@ import org.opengis.util.InternationalString;
* other exception usually lost their localization capability.
*
* @author Martin Desruisseaux (Geomatys)
- * @version 0.8
+ * @version 1.7
*
* @see Exceptions#getLocalizedMessage(Throwable, Locale)
* @see org.apache.sis.storage.DataStore#setLocale(Locale)
*
* @since 0.8
+ *
+ * @deprecated Rarely used in practice and support is unequal.
*/
+@Deprecated(since = "1.7", forRemoval = true)
public interface LocalizedException {
/**
* Returns the message in the {@linkplain Locale#getDefault() default
locale}.
