(sis) 01/03: Document the limitations of the current GDAL modules. Tune the exception to throw when GDAL is not available.

[desruisseaux]

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 363f81c359a82bef705f49ba0e4c18aedda47558
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Tue Oct 1 13:01:17 2024 +0200

    Document the limitations of the current GDAL modules.
    Tune the exception to throw when GDAL is not available.
---
 .../main/org/apache/sis/storage/gdal/package-info.java      |  7 +++++--
 .../main/org/apache/sis/storage/panama/LibraryStatus.java   | 13 +++++++++----
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git 
a/incubator/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/package-info.java
 
b/incubator/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/package-info.java
index 8ad298dee7..97e15ce179 100644
--- 
a/incubator/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/package-info.java
+++ 
b/incubator/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/package-info.java
@@ -30,8 +30,11 @@
  * If a different <abbr>GDAL</abbr> library is desired, it can be specified 
explicitly
  * to the {@link org.apache.sis.storage.gdal.GDALStoreProvider} 
constructor.</p>
  *
- * <p>The current implementation can read rasters.
- * Write operations and support of vector data will be provided in a future 
version.</p>
+ * <h2>Limitations</h2>
+ * The current implementation can only read two-dimensional rasters.
+ * It does not yet support vector data, cannot write any data,
+ * and does not yet use the multi-dimensional <abbr>API</abbr> of 
<abbr>GDAL</abbr>.
+ * Those operations will be added progressively in future versions of this 
module.
  *
  * @author  Quentin Bialota (Geomatys)
  * @author  Martin Desruisseaux (Geomatys)
diff --git 
a/incubator/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/panama/LibraryStatus.java
 
b/incubator/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/panama/LibraryStatus.java
index 775089e1cf..57b4c0952a 100644
--- 
a/incubator/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/panama/LibraryStatus.java
+++ 
b/incubator/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/panama/LibraryStatus.java
@@ -16,6 +16,7 @@
  */
 package org.apache.sis.storage.panama;
 
+import org.apache.sis.storage.DataStoreException;
 import org.apache.sis.storage.DataStoreClosedException;
 
 
@@ -72,13 +73,17 @@ public enum LibraryStatus {
      *
      * @param  library  the library name, of formatting the error message.
      * @param  cause    the cause of the error, or {@code null} if none.
-     * @throws DataStoreClosedException if this enumeration value is not 
{@link #LOADED}
-     *         or if the given cause is not null.
+     * @throws DataStoreException if this enumeration value is not {@link 
#LOADED} or if the given cause is not null.
      */
-    public void report(String library, Exception cause) throws 
DataStoreClosedException {
+    public void report(String library, Exception cause) throws 
DataStoreException {
         if (message != 0 || cause != null) {
             // Note: `NativeAccessNotAllowed` will ignore the `library` 
argument.
-            throw new DataStoreClosedException(Resources.format(message, 
library), cause);
+            String text = Resources.format(message, library);
+            if (cause != null) {
+                throw new DataStoreException(text, cause);
+            } else {
+                throw new DataStoreClosedException(text);
+            }
         }
     }
 }