Class DefaultAssociationRole
- All Implemented Interfaces:
Serializable
,Deprecable
- 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 Summary
FieldsModifier and TypeFieldDescriptionprivate static final long
For cross-version compatibility.private String
The name of the property to use as a title for the associated feature, or an empty string if none.private FeatureType
The type of feature instances to be associated.Fields inherited from class org.apache.sis.feature.AbstractIdentifiedType
DEFINITION_KEY, deprecated, DEPRECATED_KEY, DESCRIPTION_KEY, DESIGNATION_KEY, NAME_KEY
-
Constructor Summary
ConstructorsConstructorDescriptionDefaultAssociationRole
(Map<String, ?> identification, DefaultFeatureType valueType, int minimumOccurs, int maximumOccurs) Constructs an association to the given feature type.DefaultAssociationRole
(Map<String, ?> identification, org.opengis.util.GenericName valueType, int minimumOccurs, int maximumOccurs) Constructs an association to a feature type of the given name. -
Method Summary
Modifier and TypeMethodDescriptionprivate static DefaultFeatureType
deepSearch
(List<DefaultFeatureType> deferred, org.opengis.util.GenericName name) Potentially invoked aftersearch(FeatureType, Collection, GenericName, List)
for searching in associations of associations.boolean
Compares this association role with the given object for equality.final int
Returns the maximum number of occurrences of the association within its containing entity.final int
Returns the minimum number of occurrences of the association within its containing entity.(package private) static String
Returns the name of the property to use as a title for the associated feature, ornull
if none.final DefaultFeatureType
Returns the type of feature values.(package private) static org.opengis.util.GenericName
Returns the name of the feature type.int
hashCode()
Returns a hash code value for this association role.final boolean
Returnstrue
if the associatedFeatureType
is complete (not just a name).Creates a new association instance of this role.(package private) final boolean
resolve
(DefaultFeatureType creating, Collection<AbstractIdentifiedType> properties) If the associated feature type is a placeholder for aFeatureType
to be defined later, replaces the placeholder by the actual instance if available.private static DefaultFeatureType
search
(DefaultFeatureType feature, Collection<? extends AbstractIdentifiedType> properties, org.opengis.util.GenericName name, List<DefaultFeatureType> deferred) Searches in the givenfeature
for an associated feature type of the given name.private static String
Implementation ofgetTitleProperty(DefaultAssociationRole)
for first search, or for non-SISFeatureAssociationRole
implementations.toString()
Returns a string representation of this association role.Methods inherited from class org.apache.sis.feature.AbstractIdentifiedType
createName, getDefinition, getDescription, getDesignation, getName, getRemarks, isDeprecated, toString
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
valueType
The type of feature instances to be associated.- See Also:
-
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 byAbstractAssociation.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
orString
AbstractIdentifiedType.getName()
"definition" InternationalString
orString
AbstractIdentifiedType.getDefinition()
"designation" InternationalString
orString
AbstractIdentifiedType.getDesignation()
"description" InternationalString
orString
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, orInteger.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 ofDefaultFeatureType
instances. In such cases, at least one association needs to be created while itsFeatureType
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 theCallers shall make sure that the feature types graph will not contain more than one feature of the given name. If more than onetypeB
instance.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, orInteger.MAX_VALUE
if there is no restriction.
-
-
Method Details
-
isResolved
public final boolean isResolved()Returnstrue
if the associatedFeatureType
is complete (not just a name). This method returnsfalse
if thisFeatureAssociationRole
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, orfalse
if only its name is known.- Since:
- 0.8
- See Also:
-
resolve
If the associated feature type is a placeholder for aFeatureType
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 invokinggetProperties(…)
. We do that becauseresolve(…)
is invoked while the givenDefaultFeatureType
is under creation. SincegetProperties(…)
can be overridden, invoking that method oncreating
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 givenfeature
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 bydeepSearch(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)
, ornull
for letting this method performing the call.name
- the name of the feature to search.deferred
- where to storeFeatureType
s 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 aftersearch(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 bysearch(FeatureType, Collection, GenericName, List)
.name
- the name of the feature to search.- Returns:
- the feature of the given name, or
null
if none.
-
getValueType
Returns the type of feature values.This method cannot be invoked if
isResolved()
returnsfalse
. However, it is still possible to get the associated feature type name.Warning: In a future SIS version, the return type may be changed toorg.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
Returns the name of the feature type. This information is always available even when the name has not yet been resolved. -
getTitleProperty
Returns the name of the property to use as a title for the associated feature, ornull
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
orIdentifier
, then this method returns the name of that property. - Otherwise if the associated feature has an optional property of type
CharSequence
,GenericName
orIdentifier
, then this method returns the name of that property. - Otherwise this method returns
null
.
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.
- If associated feature has a property named
-
searchTitleProperty
Implementation ofgetTitleProperty(DefaultAssociationRole)
for first search, or for non-SISFeatureAssociationRole
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 classFieldType
- 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 thegetMinimumOccurs()
value. If there is no maximum, then this method returnsInteger.MAX_VALUE
.- Overrides:
getMaximumOccurs
in classFieldType
- Returns:
- the maximum number of occurrences of the association within its containing entity,
or
Integer.MAX_VALUE
if none.
-
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. -
equals
Compares this association role with the given object for equality. -
toString
Returns a string representation of this association role. The returned string is for debugging purpose and may change in any future SIS version.
-