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 11025a742e68f3d578532ef90851d25ee77ebc3d
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Sat Dec 9 11:48:29 2023 +0100
Deprecate `OptionKey.BYTE_BUFFER` because it forces unconditional
allocation of byte buffer.
---
.../main/org/apache/sis/storage/DataOptionKey.java | 24 +++++++++++
.../org/apache/sis/storage/StorageConnector.java | 6 ++-
.../org/apache/sis/storage/DataOptionKeyTest.java | 46 ++++++++++++++++++++++
.../main/org/apache/sis/setup/OptionKey.java | 12 ++++--
.../test/org/apache/sis/setup/OptionKeyTest.java | 4 +-
5 files changed, 86 insertions(+), 6 deletions(-)
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/DataOptionKey.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/DataOptionKey.java
index 89ef371110..44d069e4e1 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/DataOptionKey.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/DataOptionKey.java
@@ -17,6 +17,10 @@
package org.apache.sis.storage;
import java.nio.file.Path;
+import java.io.ObjectStreamException;
+import static java.util.logging.Logger.getLogger;
+import org.apache.sis.util.logging.Logging;
+import org.apache.sis.system.Modules;
import org.apache.sis.setup.OptionKey;
import org.apache.sis.storage.event.StoreListeners;
import org.apache.sis.feature.FoliationRepresentation;
@@ -76,4 +80,24 @@ public final class DataOptionKey<T> extends OptionKey<T> {
private DataOptionKey(final String name, final Class<T> type) {
super(name, type);
}
+
+ /**
+ * Resolves this option key on deserialization. This method is invoked only
+ * for instance of the exact {@code DataOptionKey} class, not subclasses.
+ *
+ * @return the unique {@code DataOptionKey} instance.
+ * @throws ObjectStreamException required by specification but should
never be thrown.
+ */
+ private Object readResolve() throws ObjectStreamException {
+ try {
+ return DataOptionKey.class.getField(getName()).get(null);
+ } catch (ReflectiveOperationException e) {
+ /*
+ * This may happen if we are deserializing a stream produced by a
more recent SIS library
+ * than the one running in this JVM.
+ */
+ Logging.recoverableException(getLogger(Modules.STORAGE),
DataOptionKey.class, "readResolve", e);
+ return this;
+ }
+ }
}
diff --git
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/StorageConnector.java
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/StorageConnector.java
index 708d431156..1c568e4694 100644
---
a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/StorageConnector.java
+++
b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/StorageConnector.java
@@ -641,7 +641,8 @@ public class StorageConnector implements Serializable {
}
/**
- * Sets the option value for the given key. The default implementation
recognizes the following options:
+ * Sets the option value for the given key.
+ * The {@code StorageConnector} class uses the following options, if
present:
*
* <ul>
* <li>{@link OptionKey#ENCODING} for decoding characters in an
input stream, if needed.</li>
@@ -650,6 +651,8 @@ public class StorageConnector implements Serializable {
* <li>{@link OptionKey#BYTE_BUFFER} for allowing users to control the
byte buffer to be created.</li>
* </ul>
*
+ * In addition, each {@link DataStore} implementation may use more options.
+ *
* @param <T> the type of option value.
* @param key the option for which to set the value.
* @param value the new value for the given option, or {@code null} for
removing the value.
@@ -1191,6 +1194,7 @@ public class StorageConnector implements Serializable {
* @return the byte buffer to use with {@link ChannelDataInput} or {@link
ChannelDataOutput}.
*/
private ByteBuffer getChannelBuffer(final ChannelFactory factory) {
+ @SuppressWarnings("deprecated")
ByteBuffer buffer = getOption(OptionKey.BYTE_BUFFER); //
User-supplied buffer.
if (buffer == null) {
if (factory.suggestDirectBuffer) {
diff --git
a/endorsed/src/org.apache.sis.storage/test/org/apache/sis/storage/DataOptionKeyTest.java
b/endorsed/src/org.apache.sis.storage/test/org/apache/sis/storage/DataOptionKeyTest.java
new file mode 100644
index 0000000000..7313a72bc5
--- /dev/null
+++
b/endorsed/src/org.apache.sis.storage/test/org/apache/sis/storage/DataOptionKeyTest.java
@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.storage;
+
+// Test dependencies
+import org.junit.Test;
+import static org.junit.jupiter.api.Assertions.*;
+import org.apache.sis.test.TestCase;
+import static org.apache.sis.test.Assertions.assertSerializedEquals;
+
+
+/**
+ * Tests {@link DataOptionKey}.
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ */
+public final class DataOptionKeyTest extends TestCase {
+ /**
+ * Creates a new test case.
+ */
+ public DataOptionKeyTest() {
+ }
+
+ /**
+ * Tests the serialization of constants.
+ * Those constants shall be resolved to their singleton instance on
deserialization.
+ */
+ @Test
+ public void testSerialization() {
+ assertSame(DataOptionKey.METADATA_PATH,
assertSerializedEquals(DataOptionKey.METADATA_PATH));
+ }
+}
diff --git
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/OptionKey.java
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/OptionKey.java
index 0fc616d6f8..19b1f40705 100644
--- a/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/OptionKey.java
+++ b/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/OptionKey.java
@@ -154,8 +154,8 @@ public class OptionKey<T> implements Serializable {
public static final OptionKey<String> URL_ENCODING = new
OptionKey<>("URL_ENCODING", String.class);
/**
- * Whether a storage object (e.g. a {@link
org.apache.sis.storage.DataStore}) shall be opened in read,
- * write, append or other modes. The main options that can be provided are:
+ * Whether a storage object shall be opened in read, write, append or
other modes.
+ * The main options that can be provided are:
*
* <table class="sis">
* <caption>Supported open options</caption>
@@ -179,7 +179,13 @@ public class OptionKey<T> implements Serializable {
* <li>The buffer does not contains any valuable data, as it will be
{@linkplain ByteBuffer#clear() cleared}.</li>
* <li>The same buffer is not used concurrently by two different {@code
DataStore} instances.</li>
* </ul>
+ *
+ * @deprecated This option forces unconditional allocation of byte buffer,
even if the data store does not use it.
+ * It should be replaced by a {@link java.util.function.Supplier} or
{@link java.util.function.Function}, but the
+ * exact form has not been determined yet.
*/
+ @Deprecated(since="1.5")
+ // TODO: provide replacement in DataOptionKey, because this option is
specific to data stores.
public static final OptionKey<ByteBuffer> BYTE_BUFFER = new
OptionKey<>("BYTE_BUFFER", ByteBuffer.class);
/**
@@ -361,7 +367,7 @@ public class OptionKey<T> implements Serializable {
* This may happen if we are deserializing a stream produced by a
more recent SIS library
* than the one running in this JVM. This class should be robust
to this situation, since
* we override the `equals` and `hashCode` methods. This option is
likely to be ignored,
- * but options are expected to be optional...
+ * but options are expected to be optional.
*/
Logging.recoverableException(getLogger(Modules.UTILITIES),
OptionKey.class, "readResolve", e);
return this;
diff --git
a/endorsed/src/org.apache.sis.util/test/org/apache/sis/setup/OptionKeyTest.java
b/endorsed/src/org.apache.sis.util/test/org/apache/sis/setup/OptionKeyTest.java
index ebf68f0924..eea89891a3 100644
---
a/endorsed/src/org.apache.sis.util/test/org/apache/sis/setup/OptionKeyTest.java
+++
b/endorsed/src/org.apache.sis.util/test/org/apache/sis/setup/OptionKeyTest.java
@@ -22,7 +22,7 @@ import static org.apache.sis.setup.OptionKey.*;
// Test dependencies
import org.junit.Test;
-import static org.junit.Assert.*;
+import static org.junit.jupiter.api.Assertions.*;
import org.apache.sis.test.TestCase;
import static org.apache.sis.test.TestUtilities.getSingleton;
import static org.apache.sis.test.Assertions.assertSerializedEquals;
@@ -86,7 +86,7 @@ public final class OptionKeyTest extends TestCase {
@Test
public void testSerialization() {
assertSame(URL_ENCODING, assertSerializedEquals(URL_ENCODING));
- assertSame(BYTE_BUFFER, assertSerializedEquals(BYTE_BUFFER ));
+ assertSame(OPEN_OPTIONS, assertSerializedEquals(OPEN_OPTIONS));
}
/**
