Package org.apache.sis.feature

## Class DefaultAssociationRole

- Object
- - AbstractIdentifiedType
  - - DefaultAssociationRole

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

      public class DefaultAssociationRole
      extends AbstractIdentifiedType

  Indicates the role played by the association between two features. In the area of geographic information, there exist multiple kinds of associations:
  - Aggregation represents associations between features which can exist even if the aggregate is destroyed.
  - Composition represents relationships where the owned features are destroyed together with the composite.
  - Spatial association represents spatial or topological relationships that may exist between features (e.g. “east of”).
  - Temporal association may represent for example a sequence of changes over time involving the replacement of some feature instances by other feature instances.
  Immutability and thread safety
  Instances of this class are immutable if all properties (`GenericName` and `InternationalString` instances) and all arguments (e.g. `valueType`) given to the constructor are also immutable. Such immutable instances can be shared by many objects and passed between threads without synchronization.
  Since:
    0.5
  See Also:
    `DefaultFeatureType`, `AbstractAssociation`, Serialized Form

  Defined in the `sis-feature` module

- - ### Field Summary

    - ### Fields inherited from class AbstractIdentifiedType

      `DEFINITION_KEY, DEPRECATED_KEY, DESCRIPTION_KEY, DESIGNATION_KEY, NAME_KEY`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DefaultAssociationRole​(Map<String,​?> identification, DefaultFeatureType valueType, int minimumOccurs, int maximumOccurs)` | Constructs an association to the given feature type.
    `DefaultAssociationRole​(Map<String,​?> identification, GenericName valueType, int minimumOccurs, int maximumOccurs)` | Constructs an association to a feature type of the given name.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object obj)` | Compares this association role with the given object for equality.
    `int` | `getMaximumOccurs()` | Returns the maximum number of occurrences of the association within its containing entity.
    `int` | `getMinimumOccurs()` | Returns the minimum number of occurrences of the association within its containing entity.
    `DefaultFeatureType` | `getValueType()` | Returns the type of feature values.
    `int` | `hashCode()` | Returns a hash code value for this association role.
    `boolean` | `isResolved()` | Returns `true` if the associated `FeatureType` is complete (not just a name).
    `AbstractAssociation` | `newInstance()` | Creates a new association instance of this role.
    `String` | `toString()` | Returns a string representation of this association role.

    - ### Methods inherited from class AbstractIdentifiedType

      `getDefinition, getDescription, getDesignation, getName, getRemarks, isDeprecated`

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### DefaultAssociationRole

          public DefaultAssociationRole​(Map<String,​?> identification,
                                        DefaultFeatureType valueType,
                                        int minimumOccurs,
                                        int maximumOccurs)

      Constructs an association to the given feature type. The properties map is given unchanged to the super-class constructor. The following table is a reminder of main (not all) recognized map entries:

      Recognized map entries (non exhaustive list)
      Map key | Value type | Returned by
      --- | --- | ---
      "name" | `GenericName` or `String` | `AbstractIdentifiedType.getName()`
      "definition" | `InternationalString` or `String` | `AbstractIdentifiedType.getDefinition()`
      "designation" | `InternationalString` or `String` | `AbstractIdentifiedType.getDesignation()`
      "description" | `InternationalString` or `String` | `AbstractIdentifiedType.getDescription()`
      "deprecated" | `Boolean` | `AbstractIdentifiedType.isDeprecated()`

      Parameters:
        `identification` - the name and other information to be given to this association role.
        `valueType` - the type of feature values.
        `minimumOccurs` - the minimum number of occurrences of the association within its containing entity.
        `maximumOccurs` - the maximum number of occurrences of the association within its containing entity, or `Integer​.MAX_VALUE` if there is no restriction.
      See Also:
        `AssociationRoleBuilder`

    - #### DefaultAssociationRole

          public DefaultAssociationRole​(Map<String,​?> identification,
                                        GenericName valueType,
                                        int minimumOccurs,
                                        int maximumOccurs)

      Constructs an association to a feature type of the given name. This constructor can be used when creating a cyclic graph of `DefaultFeatureType` instances. In such cases, at least one association needs to be created while its `FeatureType` is not yet available.
      Example: The following establishes a bidirectional association between feature types A and B:

      >     String    namespace = "My model";
      >     GenericName nameOfA = Names.createTypeName(namespace, ":", "Feature type A");
      >     GenericName nameOfB = Names.createTypeName(namespace, ":", "Feature type B");
      >     FeatureType typeA = new DefaultFeatureType(nameOfA, false, null,
      >         new DefaultAssociationRole(Names.createLocalName("Association to B"), nameOfB),
      >         // More properties if desired.
      >     );
      >     FeatureType typeB = new DefaultFeatureType(nameOfB, false, null,
      >         new DefaultAssociationRole(Names.createLocalName("Association to A"), featureA),
      >         // More properties if desired.
      >     );

      After the above code completed, the value type of "association to B" has been automatically set to the `typeB` instance.
      Callers shall make sure that the feature types graph will not contain more than one feature of the given name. If more than one `FeatureType` instance of the given name is found at resolution time, the selected one is undetermined.
      Parameters:
        `identification` - the name and other information to be given to this association role.
        `valueType` - the name of the type of feature values.
        `minimumOccurs` - the minimum number of occurrences of the association within its containing entity.
        `maximumOccurs` - the maximum number of occurrences of the association within its containing entity, or `Integer​.MAX_VALUE` if there is no restriction.

  - ### Method Detail

    - #### isResolved

          public final boolean isResolved()

      Returns `true` if the associated `FeatureType` is complete (not just a name). This method returns `false` if this `FeatureAssociationRole` has been constructed with only a feature name and that named feature has not yet been resolved.
      Returns:
        `true` if the associated feature is complete, or `false` if only its name is known.
      Since:
        0.8
      See Also:
        `getValueType()`

    - #### getValueType

          public final DefaultFeatureType getValueType()

      Returns the type of feature values.

      This method can not be invoked if `isResolved()` returns `false`. However it is still possible to get the associated feature type name.

      Warning: In a future SIS version, the return type may be changed to `org​.opengis​.feature​.FeatureType`. This change is pending GeoAPI revision.
      Returns:
        the type of feature values.
      Throws:
        `IllegalStateException` - if the feature type has been specified only by its name and not yet resolved.
      See Also:
        `isResolved()`

    - #### getMinimumOccurs

          public final int getMinimumOccurs()

      Returns the minimum number of occurrences of the association within its containing entity. The returned value is greater than or equal to zero.
      Returns:
        the minimum number of occurrences of the association within its containing entity.

    - #### getMaximumOccurs

          public final int getMaximumOccurs()

      Returns the maximum number of occurrences of the association within its containing entity. The returned value is greater than or equal to the `getMinimumOccurs()` value. If there is no maximum, then this method returns `Integer​.MAX_VALUE`.
      Returns:
        the maximum number of occurrences of the association within its containing entity, or `Integer​.MAX_VALUE` if none.

    - #### newInstance

          public AbstractAssociation newInstance()

      Creates a new association instance of this role.
      Returns:
        a new association instance.
      See Also:
        `AbstractAssociation​.create(DefaultAssociationRole)`

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this association role.
      Returns:
        the hash code for this type.

    - #### equals

          public boolean equals​(Object obj)

      Compares this association role with the given object for equality.
      Parameters:
        `obj` - the object to compare with this type.
      Returns:
        `true` if the given object is equals to this type.

    - #### toString

          public String toString()

      Returns a string representation of this association role. 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 role for debugging purpose.