Package org.apache.sis.metadata

Enum ValueExistencePolicy

java.lang.Object
java.lang.Enum<ValueExistencePolicy>
org.apache.sis.metadata.ValueExistencePolicy
All Implemented Interfaces:
Serializable, Comparable<ValueExistencePolicy>
public enum ValueExistencePolicy extends Enum<ValueExistencePolicy>
Whatever MetadataStandard.asValueMap(…) shall contain entries for null, nil or empty values. By default the value map does not provide entries for null metadata properties, nil objects or empty collections. This enumeration allows to control this behavior.

Difference between null and nil

A null property is a reference which is null in the Java sense. Null references can be used for missing properties when no information is provided about why the property is missing. On the other hand, a nil object is a placeholder for a missing property similar in purpose to null references, except that an explanation about why the property is missing can be attached to those objects. Those explanations can be obtained by calls to the NilReason.forObject(Object) method.
Since:
0.3
Version:
0.8
See Also:

  • Enum Constant Details

    • ALL

      public static final ValueExistencePolicy ALL
      Includes all entries in the map, including those having a null value or an empty collection.

    • NON_NULL

      public static final ValueExistencePolicy NON_NULL
      Includes only the non-null properties. NilObjects are included. Collections are included no matter if they are empty or not.

      The set of NON_NULL properties is a subset of ALL properties.

    • NON_NIL

      public static final ValueExistencePolicy NON_NIL
      Includes only the non-null and non-nil properties. Collections are included no matter if they are empty or not.

      The set of NON_NIL properties is a subset of NON_NULL properties.

      Since:
      0.4

    • NON_EMPTY

      public static final ValueExistencePolicy NON_EMPTY
      Includes only the properties that are non-null, non-nil and non empty. A non-null and non-nil property is considered empty in any of the following cases: This is the default behavior of AbstractMetadata.asMap().

      The set of NON_EMPTY properties is a subset of NON_NIL properties.

    • COMPACT

      public static final ValueExistencePolicy COMPACT
      Includes non-empty properties but omits title properties. Values associated to title properties are instead associated with the parent node. This policy is relevant for metadata classes annotated with TitleProperty; for all other classes, this policy is identical to NON_EMPTY.
      Example: the DefaultCitation and DefaultCitationDate classes are annotated with @TitleProperty(name="title") and @TitleProperty(name="date") respectively. The following table compares the trees produced by two policies:
      Comparison of "non-empty" and "compact" policy on the same metadata
      NON_EMPTY COMPACT
      This policy is the default behavior of AbstractMetadata.asTreeTable(), and consequently defines the default rendering of AbstractMetadata.toString().
      Since:
      0.8
      See Also:

  • Constructor Details

    • ValueExistencePolicy

      private ValueExistencePolicy()

  • Method Details

    • values

      public static ValueExistencePolicy[] values()
      Returns an array containing the constants of this enum type, in the order they are declared.
      Returns:
      an array containing the constants of this enum type, in the order they are declared

    • valueOf

      public static ValueExistencePolicy valueOf(String name)
      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum type has no constant with the specified name
      NullPointerException - if the argument is null

    • isSkipped

      abstract boolean isSkipped(Object value)
      Returns true if the given value shall be skipped for this policy.

    • substituteByNullElement

      abstract boolean substituteByNullElement(Collection<?> values)
      Returns true if TreeNode shall substitute the given collection by a singleton containing only a null element.

      Purpose

      When a collection is null or empty, while not excluded according this ValueExistencePolicy, we need an empty space for making the metadata property visible in TreeNode.

    • isNullOrEmpty

      static boolean isNullOrEmpty(Object value)
      Returns true if the specified object is null or an empty collection, array or string.

      This method intentionally does not inspect array or collection elements, since this method is invoked from methods doing shallow copy or comparison. If we were inspecting elements, we would need to add a check against infinite recursivity.

      This method does not check for the Emptiable interface because the isEmpty() method may be costly (for example AbstractMetadata.isEmpty() iterates over all the metadata tree). Instead, the check for Emptiable will be done explicitly by the caller when appropriate.

    • isEmpty

      private static boolean isEmpty(CharSequence value)
      Returns true if the given character sequence shall be considered empty. The current implementation returns true if the sequence contains only whitespaces in the sense of Java (i.e. ignoring line feeds, but not ignoring non-breaking spaces). The exact criterion is not a committed part of the API and may change in future SIS versions according experiences.