Module org.opengis.geoapi

Package org.opengis.feature

Interface Feature

public interface Feature

An instance of a FeatureType containing values for a real-world phenomena. Each feature instance can provide values for the following properties:

• Attributes, which may be dynamic
• Associations to other features
• Operations

Feature can be instantiated by calls to FeatureType.newInstance().

Simple features

A feature is said “simple” if it complies to all the following conditions:

• the feature allows only attributes and operations (no associations),
• the multiplicity of all attributes is constrained to [1 … 1].

Moving features

A feature is a moving feature if it complies to at least one of the following conditions:

• the feature contains dynamic attributes,
• the geometry value of an attribute is a trajectory.

Since:

3.1

See Also:

• FeatureType

Method Summary

Modifier and Type	Method	Description
Property	getProperty(String name)	Returns the property (attribute, feature association or operation result) of the given name.
Object	getPropertyValue(String name)	Returns the value for the property of the given name.
FeatureType	getType()	Returns information about the feature (name, characteristics, etc.).
Object	getValueOrFallback(String name, Object missingPropertyFallback)	Returns the value for the property of the given name if that property exists, or a fallback value otherwise.
void	setProperty(Property property)	Sets the property (attribute or feature association).
void	setPropertyValue(String name, Object value)	Sets the value for the property of the given name.

Method Details

getType

FeatureType getType()

Returns information about the feature (name, characteristics, etc.).

Returns:

information about the feature.

getProperty

Property getProperty(String name)
              throws PropertyNotFoundException

Returns the property (attribute, feature association or operation result) of the given name. If the property type is a parameterless Operation, then this method may return the result of executing the operation on this feature, at implementation choice.

Performance note

This method returns the property instance. If only the property value is desired, then getPropertyValue(String) is preferred because it gives to implementations a chance to avoid the creation of Attribute or FeatureAssociation instances.

Parameters:

name - the property name.

Returns:

the property of the given name (never null).

Throws:

PropertyNotFoundException - if the given argument is not a property name of this feature.

See Also:

• getPropertyValue(String)
• FeatureType.getProperty(String)

setProperty

void setProperty(Property property)
          throws IllegalArgumentException

Sets the property (attribute or feature association). The given property shall comply to the following conditions:

• It must be non-null.
• Its name shall be the name of the property to set in this feature.
• Its type shall be the same instance as the property type defined by the feature type for the above name. In other words, the following condition shall hold:

assert property.getType() == getType().getProperty(property.getName());

Usage note

This method is useful for storing non-default Attribute or Association implementations in this feature. When default implementations are sufficient, the setPropertyValue(String, Object) method is preferred.

Parameters:

property - the property to set.

Throws:

PropertyNotFoundException - if the name of the given property is not a property name of this feature.

InvalidPropertyValueException - if the value of the given property is not valid.

IllegalArgumentException - if the property cannot be set for another reason (e.g. a library may accept only some specific property instances).

See Also:

• setPropertyValue(String, Object)

getPropertyValue

Object getPropertyValue(String name)
                 throws PropertyNotFoundException

Returns the value for the property of the given name. This convenience method is equivalent to invoking getProperty(String) for the given name, then to perform one of the following actions depending on the property type and the multiplicity:

Class of returned value

Property type	max. occurs	Method invoked	Return type
AttributeType	0 or 1	Attribute.getValue()	Object
AttributeType	2 or more	Attribute.getValues()	Collection<?>
FeatureAssociationRole	0 or 1	FeatureAssociation.getValue()	Feature
FeatureAssociationRole	2 or more	FeatureAssociation.getValues()	Collection<Feature>

Note on occurrences

“max. occurs” is the maximum number of occurrences and does not depend on the actual number of values. If an attribute allows more than one value, then this method will always return a collection for that attribute even if the collection is empty.

Parameters:

name - the property name.

Returns:

value of the specified property, or the default value (which may be null} if none.

Throws:

PropertyNotFoundException - if the given argument is not an attribute or association name of this feature.

See Also:

• Attribute.getValue()
• FeatureAssociation.getValue()

setPropertyValue

void setPropertyValue(String name,
 Object value)
               throws IllegalArgumentException

Sets the value for the property of the given name.

Note on validation

The verifications performed by this method is implementation dependent. For performance reasons, an implementation may verify only the most basic constraints and offer another method for performing more extensive validation. Implementations should document their validation process.

Parameters:

name - the property name.

value - the new value for the specified property (may be null).

Throws:

PropertyNotFoundException - if the given name is not an attribute or association name of this feature.

ClassCastException - if the value is not assignable to the expected value class.

InvalidPropertyValueException - if the given value is not valid for a reason other than its type.

IllegalArgumentException

See Also:

• Attribute.setValue(Object)
• FeatureAssociation.setValue(Feature)

getValueOrFallback

Object getValueOrFallback(String name,
 Object missingPropertyFallback)

Returns the value for the property of the given name if that property exists, or a fallback value otherwise. This method is equivalent to the following code, but potentially more efficient when the property does not exist:

try {
    return getPropertyValue(name);
} catch (PropertyNotFoundException ignore) {
    return missingPropertyFallback
}

Note that if a property of the given name exists but has no value, then this method returns the default value (which may be null). Property without value is not equivalent to non-existent property.

Parameters:

name - the property name.

missingPropertyFallback - the (potentially null) value to return if no attribute or association of the given name exists.

Returns:

value or default value of the specified property, or missingPropertyFallback if no attribute or association of that name exists. This value may be null.