Module org.apache.sis.metadata
Package org.apache.sis.metadata

# Enum Class ValueExistencePolicy

Object
Enum<ValueExistencePolicy>
ValueExistencePolicy

All Implemented Interfaces:
  `Serializable`, `Comparable<ValueExistencePolicy>`, `Constable`

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)`

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class Enum

  `Enum​.EnumDesc<E extends Enum<E>>`

- ## 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

  Modifier and Type
  Method
  Description
  `static ValueExistencePolicy`
  `valueOf(String name)`
  Returns the enum constant of this class with the specified name.
  `static ValueExistencePolicy[]`
  `values()`
  Returns an array containing the constants of this enum class, in the order they are declared.

  ### Methods inherited from class Enum

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

  ### Methods inherited from class Object

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

- ## 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. `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 Details

  - ### values

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

  - ### valueOf

    public static ValueExistencePolicy valueOf(String name)
    Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (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 class has no constant with the specified name
      `NullPointerException` - if the argument is null