Package org.apache.sis.feature

## Class AbstractAssociation

- Object
- - AbstractAssociation

- All Implemented Interfaces:
    `Serializable`, `Cloneable`

      public abstract class AbstractAssociation
      extends Object
      implements Cloneable, Serializable

  An instance of an feature association role containing the associated feature. `AbstractAssociation` can be instantiated by calls to `DefaultAssociationRole​.newInstance()`.
  Limitations
  - Multi-threading: `AbstractAssociation` 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.
  Since:
    0.5
  See Also:
    `AbstractFeature`, `DefaultAssociationRole`, Serialized Form

  Defined in the `sis-feature` module

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `AbstractAssociation​(DefaultAssociationRole role)` | Creates a new association of the given role.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `AbstractAssociation` | `clone()` | Returns a copy of this association.
    `static AbstractAssociation` | `create​(DefaultAssociationRole role)` | Creates a new association of the given role.
    `GenericName` | `getName()` | Returns the name of this association as defined by its role.
    `DefaultAssociationRole` | `getRole()` | Returns information about the association.
    `abstract AbstractFeature` | `getValue()` | Returns the associated feature, or `null` if none.
    `Collection<AbstractFeature>` | `getValues()` | Returns all features, or an empty collection if none.
    `DataQuality` | `quality()` | Verifies if the current association value mets the constraints defined by the association role.
    `abstract void` | `setValue​(AbstractFeature value)` | Sets the associated feature.
    `void` | `setValues​(Collection<? extends AbstractFeature> values)` | Sets the features.
    `String` | `toString()` | Returns a string representation of this association.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### AbstractAssociation

          protected AbstractAssociation​(DefaultAssociationRole role)

      Creates a new association of the given role.
      Parameters:
        `role` - information about the association.
      See Also:
        `create(DefaultAssociationRole)`

  - ### Method Detail

    - #### create

          public static AbstractAssociation create​(DefaultAssociationRole role)

      Creates a new association of the given role.
      Parameters:
        `role` - information about the association.
      Returns:
        the new association.
      See Also:
        `DefaultAssociationRole​.newInstance()`

    - #### getName

          public GenericName getName()

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

    - #### getRole

          public DefaultAssociationRole getRole()

      Returns information about the association.
      Warning: In a future SIS version, the return type may be changed to `org​.opengis​.feature​.AssociationRole`. This change is pending GeoAPI revision.
      Returns:
        information about the association.

    - #### getValue

          public abstract AbstractFeature getValue()
                                            throws IllegalStateException

      Returns the associated feature, or `null` if none. This convenience method can be invoked in the common case where the maximum number of features is restricted to 1 or 0.
      Warning: In a future SIS version, the return type may be changed to `org​.opengis​.feature​.Feature`. This change is pending GeoAPI revision.
      Returns:
        the associated feature (may be `null`).
      Throws:
        `IllegalStateException` - if this association contains more than one value.
      See Also:
        `AbstractFeature​.getPropertyValue(String)`

    - #### getValues

          public Collection<AbstractFeature> getValues()

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

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

      Returns:
        the features in a live collection.

    - #### setValue

          public abstract void setValue​(AbstractFeature value)
                                 throws IllegalArgumentException

      Sets the associated feature.
      Warning: In a future SIS version, the argument type may be changed to `org​.opengis​.feature​.Feature`. This change is pending GeoAPI revision.
      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`.
      Throws:
        `IllegalArgumentException` - if the given feature is not valid for this association.
      See Also:
        `AbstractFeature​.setPropertyValue(String, Object)`

    - #### setValues

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

      Sets the features. 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(AbstractFeature)`.

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

    - #### quality

          public DataQuality quality()

      Verifies if the current association value mets the constraints defined by the association role. This method returns at most one report with a result for each constraint violations found, if any. See `AbstractAttribute​.quality()` for an example.

      This association is valid if this method does not report any conformance result having a pass value of `false`.

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

    - #### toString

          public String toString()

      Returns a string representation of this association. The returned string is for debugging purpose and may change in any future SIS version.
      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of this association for debugging purpose.

    - #### clone

          public AbstractAssociation clone()
                                    throws CloneNotSupportedException

      Returns a copy of this association. The default implementation returns a shallow copy: the association value is not cloned. However subclasses may choose to do otherwise.
      Overrides:
        `clone` in class `Object`
      Returns:
        a clone of this association.
      Throws:
        `CloneNotSupportedException` - if this association can not be cloned. The default implementation never throw this exception. However subclasses may throw it.