sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] 01/02: 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.
Date Wed, 19 Aug 2020 17:38:34 GMT
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;
 


Mime
View raw message