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 cd06a450f02fd074cff6ae0fbf9701c09b67f38d
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Wed Aug 19 13:16:14 2020 +0200
Add a DefaultMetadata.deepCopy(Metadata) convenience method.
For now we add that convenience method only for the root Metadata object
because it is the kind of objects returned by DataStore.getMetadata() methods.
---
.../apache/sis/metadata/ModifiableMetadata.java | 7 +++-
.../apache/sis/metadata/iso/DefaultMetadata.java | 41 ++++++++++++++++++++--
.../java/org/apache/sis/storage/DataStore.java | 1 +
.../main/java/org/apache/sis/storage/Resource.java | 7 ++++
4 files changed, 53 insertions(+), 3 deletions(-)
diff --git a/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
b/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
index 40a0add..dee99d7 100644
--- a/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
+++ b/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
@@ -31,6 +31,7 @@ import java.lang.reflect.Modifier;
import java.nio.charset.Charset;
import javax.xml.bind.annotation.XmlTransient;
import org.opengis.util.CodeList;
+import org.opengis.metadata.Metadata; // For javadoc
import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.collection.Containers;
import org.apache.sis.util.collection.CodeListSet;
@@ -150,7 +151,10 @@ public abstract class ModifiableMetadata extends AbstractMetadata {
*
* @author Martin Desruisseaux (Geomatys)
* @version 1.0
- * @since 1.0
+ *
+ * @see ModifiableMetadata#state()
+ *
+ * @since 1.0
* @module
*/
public enum State {
@@ -330,6 +334,7 @@ public abstract class ModifiableMetadata extends AbstractMetadata {
* @return a copy (except in above-cited special case) of this metadata in the specified
state.
*
* @see MetadataCopier
+ * @see org.apache.sis.metadata.iso.DefaultMetadata#deepCopy(Metadata)
*
* @since 1.1
*/
diff --git a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
index e80b0d9..bf7db5f 100644
--- a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
+++ b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/DefaultMetadata.java
@@ -60,6 +60,8 @@ import org.opengis.referencing.ReferenceSystem;
import org.opengis.util.InternationalString;
import org.apache.sis.util.iso.SimpleInternationalString;
import org.apache.sis.util.Emptiable;
+import org.apache.sis.metadata.MetadataCopier;
+import org.apache.sis.metadata.MetadataStandard;
import org.apache.sis.metadata.iso.citation.DefaultCitation;
import org.apache.sis.metadata.iso.citation.DefaultCitationDate;
import org.apache.sis.metadata.iso.citation.DefaultOnlineResource;
@@ -135,8 +137,11 @@ import org.apache.sis.math.FunctionProperty;
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
* @author Cullen Rombach (Image Matters)
- * @version 1.0
- * @since 0.3
+ * @version 1.1
+ *
+ * @see org.apache.sis.storage.Resource#getMetadata()
+ *
+ * @since 0.3
* @module
*/
@XmlType(name = "MD_Metadata_Type", propOrder = {
@@ -386,6 +391,12 @@ public class DefaultMetadata extends ISOMetadata implements Metadata
{
* metadata contained in the given object are not recursively copied.</li>
* </ul>
*
+ * <h4>Use case</h4>
+ * This method is useful before {@linkplain org.apache.sis.xml.XML#marshal(Object) XML
marshalling}
+ * or serialization, which may not be supported by all implementations.
+ * However the returned metadata is not guaranteed to be {@linkplain State#EDITABLE editable}.
+ * For editable metadata, see {@link #deepCopy(Metadata)}.
+ *
* @param object the object to get as a SIS implementation, or {@code null} if none.
* @return a SIS implementation containing the values of the given object (may be the
* given object itself), or {@code null} if the argument was null.
@@ -397,6 +408,32 @@ public class DefaultMetadata extends ISOMetadata implements Metadata
{
return new DefaultMetadata(object);
}
+ /**
+ * Returns an editable copy of the given metadata. All children are also copied.
+ * This method is more expensive than {@link #castOrCopy(Metadata)} because the
+ * copy is unconditional and much deeper.
+ * However the result is guaranteed to be editable.
+ *
+ * <h4>Use case</h4>
+ * Metadata returned by {@link org.apache.sis.storage.Resource#getMetadata()} are typically
unmodifiable.
+ * This {@code deepCopy(…)} method is useful for completing those metadata with new
elements, for example
+ * before insertion in a catalog.
+ *
+ * @param object the metadata to copy, or {@code null} if none.
+ * @return a deep copy of the given object, or {@code null} if the argument was null.
+ *
+ * @see #deepCopy(State)
+ * @see State#EDITABLE
+ *
+ * @since 1.1
+ */
+ public static DefaultMetadata deepCopy(final Metadata object) {
+ if (object == null) {
+ return null;
+ }
+ return (DefaultMetadata) new MetadataCopier(MetadataStandard.ISO_19115).copy(Metadata.class,
object);
+ }
+
/*
* Note about deprecated methods implementation: as a general guideline in our metadata
implementation,
* the deprecated getter methods invoke only the non-deprecated getter replacement, and
the deprecated
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java b/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
index e4368b1..5487b25 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStore.java
@@ -356,6 +356,7 @@ public abstract class DataStore implements Resource, Localized, AutoCloseable
{
* @throws DataStoreException if an error occurred while reading the metadata.
*
* @see #getIdentifier()
+ * @see org.apache.sis.metadata.iso.DefaultMetadata#deepCopy(Metadata)
*/
@Override
public abstract Metadata getMetadata() throws DataStoreException;
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java b/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java
index e37a1ca..0ed22e5 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java
@@ -126,10 +126,17 @@ public interface Resource {
* sample dimension names (or band numbers in simpler cases) of coverages or rasters
included in this resource.</li>
* </ul>
*
+ * <h4>Metadata edition</h4>
+ * This method often returns an {@linkplain org.apache.sis.metadata.ModifiableMetadata.State#FINAL
unmodifiable}
+ * metadata, for making possible to return efficiently a cached instance.
+ * If the caller wants to modify some metadata elements, it may be necessary to perform
a
+ * {@linkplain org.apache.sis.metadata.iso.DefaultMetadata#deepCopy(Metadata) deep copy}
first.
+ *
* @return information about this resource. Should not be {@code null}.
* @throws DataStoreException if an error occurred while reading the metadata.
*
* @see DataStore#getMetadata()
+ * @see org.apache.sis.metadata.iso.DefaultMetadata#deepCopy(Metadata)
*/
Metadata getMetadata() throws DataStoreException;
|