Class Merger

java.lang.Object
org.apache.sis.internal.metadata.Merger

public class Merger extends Object
Merges the content of two metadata instances. For each non-null and non-empty property value from the source metadata, the merge operation is defined as below:
  • If the target metadata does not have a non-null and non-empty value for the same property, then the reference to the value from the source metadata is stored as-is in the target metadata.
  • Otherwise if the target value is a collection, then:
    • For each element of the source collection, a corresponding element of the target collection is searched. A pair of source and target elements is established if the pair meets all of the following conditions:
      • The standard type of the source element is assignable to the type of the target element.
      • There is no conflict, i.e. no property value that are not collection and not equal. This condition can be modified by overriding resolve(Object, ModifiableMetadata).
      If such pair is found, then the merge operation if performed recursively for that pair of source and target elements.
    • All other source elements will be added as new elements in the target collection.
  • Otherwise the copy(…) method is invoked.
Since:
0.8
Version:
1.0
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private final class 
    Helper class for merging the content of two maps where values may be other metadata objects.
    static enum 
    The action to perform when a source metadata element is about to be written in an existing target element.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final Map<Object,Boolean>
    The source and target values that have already been copied, for avoiding never-ending loop in cyclic graphs.
    protected final Locale
    The locale to use for formatting error messages, or null for the default locale.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Merger(Locale locale)
    Creates a new merger.
  • Method Summary

    Modifier and Type
    Method
    Description
    final void
    copy(Object source, ModifiableMetadata target)
    Merges the data from the given source into the given target.
    private boolean
    copy(Object source, ModifiableMetadata target, boolean dryRun)
    Implementation of copy(Object, ModifiableMetadata) method, to be invoked recursively for all child properties to merge.
    private Errors
    Returns the resources for error messages.
    protected void
    merge(ModifiableMetadata target, String propertyName, Object sourceValue, Object targetValue)
    Invoked when Merger cannot merge a metadata value by itself.
    private static String
    name(ModifiableMetadata target, String propertyName)
    Returns the name of the given property in the given metadata instance.
    Invoked when a source metadata element is about to be written in an existing target element.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • done

      private final Map<Object,Boolean> done
      The source and target values that have already been copied, for avoiding never-ending loop in cyclic graphs. The value is Boolean.FALSE if the key is a source, or Boolean.TRUE if the key is a target.
    • locale

      protected final Locale locale
      The locale to use for formatting error messages, or null for the default locale.
  • Constructor Details

    • Merger

      public Merger(Locale locale)
      Creates a new merger.
      Parameters:
      locale - the locale to use for formatting error messages, or null for the default locale.
  • Method Details

    • errors

      private Errors errors()
      Returns the resources for error messages.
    • name

      private static String name(ModifiableMetadata target, String propertyName)
      Returns the name of the given property in the given metadata instance. This is used for formatting error messages.
    • copy

      public final void copy(Object source, ModifiableMetadata target)
      Merges the data from the given source into the given target. See class javadoc for a description of the merge process.
      Parameters:
      source - the source metadata to merge into the target. Will never be modified.
      target - the target metadata where to merge values. Will be modified as a result of this call.
      Throws:
      ClassCastException - if the source and target are not instances of the same metadata standard.
      InvalidMetadataException - if the target metadata cannot hold all source properties, for example because the source class is a more specialized type than the target class.
      IllegalArgumentException - if this method detects a cross-reference between source and target metadata.
    • copy

      private boolean copy(Object source, ModifiableMetadata target, boolean dryRun)
      Implementation of copy(Object, ModifiableMetadata) method, to be invoked recursively for all child properties to merge.
      Parameters:
      dryRun - true for simulating the merge operation instead of performing the actual merge. Used for verifying if there is a merge conflict before to perform the actual operation.
      Returns:
      true if the merge operation is valid, or false if the given arguments are valid metadata but the merge operation can nevertheless not be executed because it could cause data lost.
    • resolve

      protected Merger.Resolution resolve(Object source, ModifiableMetadata target)
      Invoked when a source metadata element is about to be written in an existing target element. The default implementation returns Merger.Resolution.MERGE if writing in the given target would only fill holes, without overwriting any existing value. Otherwise this method returns Resolution#SEPARATE.
      Parameters:
      source - the source metadata to copy.
      target - where the source metadata would be copied if this method returns Merger.Resolution.MERGE.
      Returns:
      Merger.Resolution.MERGE for writing source into target, or Merger.Resolution.SEPARATE for writing source in a separated metadata element, or Merger.Resolution.IGNORE for discarding source.
    • merge

      protected void merge(ModifiableMetadata target, String propertyName, Object sourceValue, Object targetValue)
      Invoked when Merger cannot merge a metadata value by itself. The default implementation throws an InvalidMetadataException. Subclasses can override this method if they want to perform a different processing.
      Parameters:
      target - the metadata instance in which the value should have been written.
      propertyName - the name of the property to write.
      sourceValue - the value to write.
      targetValue - the value that already exist in the target metadata.