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

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object obj)`
  Compares this association role with the given object for equality.
  `final int`
  `getMaximumOccurs()`
  Returns the maximum number of occurrences of the association within its containing entity.
  `final int`
  `getMinimumOccurs()`
  Returns the minimum number of occurrences of the association within its containing entity.
  `final DefaultFeatureType`
  `getValueType()`
  Returns the type of feature values.
  `int`
  `hashCode()`
  Returns a hash code value for this association role.
  `final 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 Details

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

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