Package org.apache.sis.metadata

## Enum ValueExistencePolicy

- Object
- - Enum<ValueExistencePolicy>
  - - 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
  See Also:
    `MetadataStandard​.asValueMap(Object, Class, KeyNamePolicy, ValueExistencePolicy)`

  Defined in the `sis-metadata` module

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant | Description
    --- | ---
    `ALL` | Includes all entries in the map, including those having a null value or an empty collection.
    `COMPACT` | Includes non-empty properties but omits title properties.
    `NON_EMPTY` | Includes only the properties that are non-null, non-nil and non empty.
    `NON_NIL` | Includes only the non-null and non-nil properties.
    `NON_NULL` | Includes only the non-null properties.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static ValueExistencePolicy` | `valueOf​(String name)` | Returns the enum constant of this type with the specified name.
    `static ValueExistencePolicy[]` | `values()` | Returns an array containing the constants of this enum type, in the order they are declared.

    - ### Methods inherited from class Enum

      `clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

    - ### Methods inherited from class Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Enum Constant Detail

    - #### 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. `NilObject`s 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:
      - It is a character sequence containing only whitespaces.
      - It is an empty collection.
      - It is an empty map.
      - It is an empty array (of length 0).
      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`
      --- | ---
      >     Citation
      >      ├─Title……………………… My document
      >      └─Date
      >         ├─Date………………… 2012/01/01
      >         └─Date type…… Creation
      >     Citation……………………… My document
      >      └─Date………………………… 2012/01/01
      >         └─Date type…… Creation

      This policy is the default behavior of `AbstractMetadata​.asTreeTable()`, and consequently defines the default rendering of `AbstractMetadata​.toString()`.
      Since:
        0.8
      See Also:
        `TitleProperty`

  - ### Method Detail

    - #### values

          public static ValueExistencePolicy[] values()

      Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

          for (ValueExistencePolicy c : ValueExistencePolicy.values())
              System.out.println(c);

      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