Class DefaultAssociationRole

All Implemented Interfaces:
Serializable, Deprecable

public class DefaultAssociationRole extends FieldType
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
Version:
1.0
See Also:
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • valueType

      private volatile FeatureType valueType
      The type of feature instances to be associated.
      See Also:
    • titleProperty

      private transient volatile String titleProperty
      The name of the property to use as a title for the associated feature, or an empty string if none. This field is initially null, then computed when first needed. This information is used only by AbstractAssociation.toString() implementation.
  • 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:
    • DefaultAssociationRole

      public DefaultAssociationRole(Map<String,?> identification, org.opengis.util.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: 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:
    • resolve

      final boolean resolve(DefaultFeatureType creating, Collection<AbstractIdentifiedType> properties)
      If the associated feature type is a placeholder for a FeatureType to be defined later, replaces the placeholder by the actual instance if available. Otherwise do nothing. This method is needed only in case of cyclic graph, e.g. feature A has an association to feature B which has an association back to A. It may also be A having an association to itself, etc.
      Parameters:
      creating - the feature type in process of being constructed.
      properties - creating.getProperties(false) given as a direct reference to the internal field, without invoking getProperties(…). We do that because resolve(…) is invoked while the given DefaultFeatureType is under creation. Since getProperties(…) can be overridden, invoking that method on creating may cause a failure with user code.
      Returns:
      true if this association references a resolved feature type after this method call.
    • search

      private static DefaultFeatureType search(DefaultFeatureType feature, Collection<? extends AbstractIdentifiedType> properties, org.opengis.util.GenericName name, List<DefaultFeatureType> deferred)
      Searches in the given feature for an associated feature type of the given name. This method does not search recursively in the associations of the associated features. Such recursive search will be performed by deepSearch(List, GenericName) only if we do not find the desired feature in the most direct way.

      Current implementation does not check that there are no duplicated names. See deepSearch(List, GenericName) for a rational.

      Parameters:
      feature - the feature in which to search.
      properties - feature.getProperties(false), or null for letting this method performing the call.
      name - the name of the feature to search.
      deferred - where to store FeatureTypes to be eventually used for a deep search.
      Returns:
      the feature of the given name, or null if none.
    • deepSearch

      private static DefaultFeatureType deepSearch(List<DefaultFeatureType> deferred, org.opengis.util.GenericName name)
      Potentially invoked after search(FeatureType, Collection, GenericName, List) for searching in associations of associations.

      Current implementation does not check that there are no duplicated names. Even if we did so, a graph of feature types may have no duplicated names at this time but some duplicated names later. We rather put a warning in DefaultAssociationRole(Map, GenericName, int, int) javadoc.

      Parameters:
      deferred - the feature types collected by search(FeatureType, Collection, GenericName, List).
      name - the name of the feature to search.
      Returns:
      the feature of the given name, or null if none.
    • getValueType

      public final DefaultFeatureType getValueType()
      Returns the type of feature values.

      This method cannot 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:
    • getValueTypeName

      static org.opengis.util.GenericName getValueTypeName(DefaultAssociationRole role)
      Returns the name of the feature type. This information is always available even when the name has not yet been resolved.
    • getTitleProperty

      static String getTitleProperty(DefaultAssociationRole role)
      Returns the name of the property to use as a title for the associated feature, or null if none. This method applies the following heuristic rules:
      • If associated feature has a property named "sis:identifier", then this method returns that name.
      • Otherwise if the associated feature has a mandatory property of type CharSequence, GenericName or Identifier, then this method returns the name of that property.
      • Otherwise if the associated feature has an optional property of type CharSequence, GenericName or Identifier, then this method returns the name of that property.
      • Otherwise this method returns null.
      This method should be used only for display purpose, not as a reliable or stable way to get the identifier. The heuristic rules implemented in this method may change in any future Apache SIS version.

      API note: a non-static method would be more elegant in this "SIS for GeoAPI 3.0" branch. However this method needs to be static in other SIS branches, because they work with interfaces rather than SIS implementation. We keep the method static in this branch too for easier merges.

    • searchTitleProperty

      private static String searchTitleProperty(DefaultFeatureType ft)
      Implementation of getTitleProperty(DefaultAssociationRole) for first search, or for non-SIS FeatureAssociationRole implementations.
    • 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.
      Overrides:
      getMinimumOccurs in class FieldType
      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.
      Overrides:
      getMaximumOccurs in class FieldType
      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:
    • hashCode

      public int hashCode()
      Returns a hash code value for this association role.
      Overrides:
      hashCode in class FieldType
      Returns:
      the hash code for this type.
    • equals

      public boolean equals(Object obj)
      Compares this association role with the given object for equality.
      Overrides:
      equals in class FieldType
      Parameters:
      obj - the object to compare with this type.
      Returns:
      true if the given object is equal 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.