Package org.apache.sis.feature

## Class AbstractAttribute<V>

- Object
- - AbstractAttribute<V>

- Type Parameters:
    `V` - the type of attribute values.
  All Implemented Interfaces:
    `Serializable`

      public abstract class AbstractAttribute<V>
      extends Object
      implements Serializable

  An instance of an attribute type containing the value of an attribute in a feature. `Attribute` holds three main information:
  - A reference to an attribute type which defines the base Java type and domain of valid values.
  - One or more values, which may be a singleton ([0 … 1] multiplicity) or multi-valued ([0 … ∞] multiplicity).
  - Optional characteristics about the attribute (e.g. a temperature attribute may have a characteristic holding the measurement accuracy). Characteristics are often, but not necessarily, constant for all attributes of the same type in a dataset.
  `AbstractAttribute` can be instantiated by calls to `DefaultAttributeType​.newInstance()`.
  Limitations
  - Multi-threading: `AbstractAttribute` instances are not thread-safe. Synchronization, if needed, shall be done externally by the caller.
  - Serialization: serialized objects of this class are not guaranteed to be compatible with future versions. Serialization should be used only for short term storage or RMI between applications running the same SIS version.
  - Cloning: despite providing a public `clone()` method, this base class is not cloneable by default. Subclasses shall implement the `Cloneable` interface themselves if they choose to support cloning.
  Since:
    0.5
  See Also:
    `AbstractFeature`, `DefaultAttributeType`, Serialized Form

  Defined in the `sis-feature` module

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `AbstractAttribute​(DefaultAttributeType<V> type)` | Creates a new attribute of the given type.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Map<String,​AbstractAttribute<?>>` | `characteristics()` | Other attributes that describes this attribute.
    `AbstractAttribute<V>` | `clone()` | Returns a copy of this attribute if cloning is supported.
    `static <V> AbstractAttribute<V>` | `create​(DefaultAttributeType<V> type)` | Creates a new attribute of the given type initialized to the default value.
    `GenericName` | `getName()` | Returns the name of this attribute as defined by its type.
    `DefaultAttributeType<V>` | `getType()` | Returns information about the attribute (base Java class, domain of values, etc.).
    `abstract V` | `getValue()` | Returns the attribute value, or `null` if none.
    `Collection<V>` | `getValues()` | Returns all attribute values, or an empty collection if none.
    `DataQuality` | `quality()` | Evaluates the quality of this attribute at this method invocation time.
    `abstract void` | `setValue​(V value)` | Sets the attribute value.
    `void` | `setValues​(Collection<? extends V> values)` | Sets the attribute values.
    `String` | `toString()` | Returns a string representation of this attribute.

    - ### Methods inherited from class Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### AbstractAttribute

          protected AbstractAttribute​(DefaultAttributeType<V> type)

      Creates a new attribute of the given type.
      Parameters:
        `type` - information about the attribute (base Java class, domain of values, etc.).
      See Also:
        `create(DefaultAttributeType)`

  - ### Method Detail

    - #### create

          public static <V> AbstractAttribute<V> create​(DefaultAttributeType<V> type)

      Creates a new attribute of the given type initialized to the default value.
      Type Parameters:
        `V` - the type of attribute values.
      Parameters:
        `type` - information about the attribute (base Java class, domain of values, etc.).
      Returns:
        the new attribute.
      See Also:
        `DefaultAttributeType​.newInstance()`

    - #### getName

          public GenericName getName()

      Returns the name of this attribute as defined by its type. This convenience method delegates to `AbstractIdentifiedType​.getName()`.
      Returns:
        the attribute name specified by its type.

    - #### getType

          public DefaultAttributeType<V> getType()

      Returns information about the attribute (base Java class, domain of values, etc.).
      Warning: In a future SIS version, the return type may be changed to `org​.opengis​.feature​.AttributeType`. This change is pending GeoAPI revision.
      Returns:
        information about the attribute.

    - #### getValue

          public abstract V getValue()
                              throws IllegalStateException

      Returns the attribute value, or `null` if none. This convenience method can be invoked in the common case where the maximum number of attribute values is restricted to 1 or 0.
      Returns:
        the attribute value (may be `null`).
      Throws:
        `IllegalStateException` - if this attribute contains more than one value.
      See Also:
        `AbstractFeature​.getPropertyValue(String)`

    - #### getValues

          public Collection<V> getValues()

      Returns all attribute values, or an empty collection if none. The returned collection is live: changes in the returned collection will be reflected immediately in this `Attribute` instance, and conversely.

      The default implementation returns a collection which will delegate its work to `getValue()` and `setValue(Object)`.

      Returns:
        the attribute values in a live collection.

    - #### setValue

          public abstract void setValue​(V value)
                                 throws IllegalArgumentException

      Sets the attribute value. All previous values are replaced by the given singleton.
      Validation
      The amount of validation performed by this method is implementation dependent. Usually, only the most basic constraints are verified. This is so for performance reasons and also because some rules may be temporarily broken while constructing a feature. A more exhaustive verification can be performed by invoking the `quality()` method.
      Parameters:
        `value` - the new value, or `null` for removing all values from this attribute.
      Throws:
        `IllegalArgumentException` - if this method verifies argument validity and the given value does not met the attribute constraints.
      See Also:
        `AbstractFeature​.setPropertyValue(String, Object)`

    - #### setValues

          public void setValues​(Collection<? extends V> values)
                         throws IllegalArgumentException

      Sets the attribute values. All previous values are replaced by the given collection.

      The default implementation ensures that the given collection contains at most one element, then delegates to `setValue(Object)`.

      Parameters:
        `values` - the new values.
      Throws:
        `IllegalArgumentException` - if the given collection contains too many elements.

    - #### characteristics

          public Map<String,​AbstractAttribute<?>> characteristics()

      Other attributes that describes this attribute. For example if this attribute carries a measurement, then a characteristic of this attribute could be the measurement accuracy. See "Attribute characterization" in `DefaultAttributeType` Javadoc for more information.

      The map returned by this method contains only the characteristics explicitly defined for this attribute. If the map contains no characteristic for a given name, a default value may still exist. In such cases, callers may also need to inspect the `DefaultAttributeType​.characteristics()` as shown in the Reading a characteristic section below.

      Rational: Very often, all attributes of a given type in the same dataset have the same characteristics. For example it is very common that all temperature measurements in a dataset have the same accuracy, and setting a different accuracy for a single measurement is relatively rare. Consequently, `characteristics​.isEmpty()` is a convenient way to check that an attribute have all the "standard" characteristics and need no special processing.
      Reading a characteristic
      The characteristic values are enumerated in the map values. The map keys are the `String` representations of characteristics name, for more convenient lookups.

      If an attribute is known to be a measurement with a characteristic named "accuracy" of type `Float`, then the accuracy value could be read as below:

      >     Float getAccuracy(Attribute<?> measurement) {
      >         Attribute<?> accuracy = measurement.characteristics().get("accuracy");
      >         if (accuracy != null) {
      >             return (Float) accuracy.getValue(); // Value may be null.
      >         } else {
      >             return (Float) measurement.getType().characteristics().get("accuracy").getDefaultValue();
      >             // A more sophisticated implementation would probably cache the default value somewhere.
      >         }
      >     }

      Adding a characteristic
      A new characteristic can be added in the map in three different ways:
      1. Putting the (name, characteristic) pair explicitly. If an older characteristic existed for that name, it will be replaced. Example:

         >     Attribute<?> accuracy = ...;                               // To be created by the caller.
         >     characteristics.put("accuracy", accuracy);

      2. Adding the new characteristic to the values collection. The name is inferred automatically from the characteristic type. If an older characteristic existed for the same name, an `IllegalStateException` will be thrown. Example:

         >     Attribute<?> accuracy = ...;                               // To be created by the caller.
         >     characteristics.values().add(accuracy);

      3. Adding the characteristic name to the key set. If no characteristic existed for that name, a default one will be created. Example:

         >     characteristics.keySet().add("accuracy");                  // Ensure that an entry will exist for that name.
         >     Attribute<?> accuracy = characteristics.get("accuracy");
         >     Features.cast(accuracy, Float.class).setValue(...);        // Set new accuracy value here as a float.

      Returns:
        other attribute types that describes this attribute type, or an empty map if none.
      See Also:
        `DefaultAttributeType​.characteristics()`

    - #### quality

          public DataQuality quality()

      Evaluates the quality of this attribute at this method invocation time. The data quality reports may include information about whether the attribute value mets the constraints defined by the attribute type, or any other criterion at implementation choice.

      The default implementation reports data quality with at least the following information:

      - The scope level is set to `ScopeCode​.ATTRIBUTE`.
      - At most one domain consistency element is added to the reports list (implementations are free to omit that element if they have nothing to report). If a report is provided, then it will contain at least the following information:

        - The attribute name as the data quality measure identification.

          Note: strictly speaking, `measureIdentification` identifies the quality measurement, not the “real” measurement itself. However this implementation uses the same set of identifiers for both for simplicity.

        - If the attribute value is not an instance of the expected value class, or if the number of occurrences is not inside the multiplicity range, or if any other constraint is violated, then a conformance result is added for each violation with an explanation set to the error message.

          Note: this is a departure from ISO intent, since `explanation` should be a statement about what a successful conformance means. This point may be reformulated in a future SIS version.
      This attribute is valid if this method does not report any conformance result having a pass value of `false`.
      Example: given an attribute named “population” with [1 … 1] multiplicity, if no value has been assigned to that attribute, then this `quality()` method will return the following data quality report:

      >     Data quality
      >       ├─Scope
      >       │   └─Level………………………………………………… Attribute
      >       └─Report
      >           ├─Measure identification
      >           │   └─Code………………………………………… population
      >           ├─Evaluation method type…… Direct internal
      >           └─Result
      >               ├─Explanation……………………… Missing value for “population” property.
      >               └─Pass………………………………………… false

      Returns:
        reports on all constraint violations found.
      See Also:
        `AbstractFeature​.quality()`

    - #### toString

          public String toString()

      Returns a string representation of this attribute. The returned string is for debugging purpose and may change in any future SIS version. The current implementation is like below:

      >     Attribute[“temperature” : Float] = {20.3, 17.8, 21.1}
      >     └─ characteristics: units=°C, accuracy=0.1

      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of this attribute for debugging purpose.

    - #### clone

          public AbstractAttribute<V> clone()
                                     throws CloneNotSupportedException

      Returns a copy of this attribute if cloning is supported. The decision to support cloning or not is left to subclasses. If the subclass does not implement the `Cloneable` interface, then this method throws a `CloneNotSupportedException`. Otherwise the default implementation returns a shallow copy of this `Attribute`: the attribute value and characteristics are not cloned. However subclasses may choose to do otherwise.
      Overrides:
        `clone` in class `Object`
      Returns:
        a clone of this attribute.
      Throws:
        `CloneNotSupportedException` - if this attribute, the value or one of its characteristics can not be cloned.