Class AttributeConvention
AttributeConvention
class are often aliases generated
by the SIS implementation of various file readers. Those synthetic properties redirect to the most
appropriate "real" property in the feature.
"sis:identifier"
, which contains a unique
identifier (or primary key) for the feature. This property is usually (but not necessarily)
a link to an existing attribute.
By using the "sis:identifier"
alias, users do not need to know the name of the "real" attribute.
- Names ending with
"_PROPERTY"
are used for attributes or operations that are members of the collection returned byDefaultFeatureType.getProperties(boolean)
. - Names ending with
"_CHARACTERISTIC"
are used for characteristics that are entries of the map returned byDefaultAttributeType.characteristics()
.
Mixing with other conventions
The conventions defined in this class are specific to Apache SIS. Current implementation does not support any other convention than the SIS one, but we may refactor this class in future SIS versions if there is a need to support different conventions.In order to reduce the risk of name collision with properties in user-defined features
(e.g. the user may already have an attribute named "identifier"
for his own purpose),
all names defined in this class begin with the "@"
character.
- Since:
- 0.7
- Version:
- 1.1
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
String representation of theCRS_CHARACTERISTIC
name.static final org.opengis.util.ScopedName
Conventional name for fetching the Coordinate Reference System (CRS) of a geometry or a coverage.static final String
String representation of theENVELOPE_PROPERTY
name.static final org.opengis.util.ScopedName
Conventional name for fetching the envelope encompassing all geometries in a feature.static final String
String representation of theGEOMETRY_PROPERTY
name.static final org.opengis.util.ScopedName
Conventional name for a property containing the geometric object to use by default.static final String
String representation of theIDENTIFIER_PROPERTY
name.static final org.opengis.util.ScopedName
Conventional name for a property used as a unique identifier.static final String
String representation of theMAXIMAL_LENGTH_CHARACTERISTIC
name.static final org.opengis.util.ScopedName
Conventional name for fetching the maximal length of string values.private static final org.opengis.util.LocalName
Scope of all names defined by SIS convention.static final String
String representation of theUNIT_CHARACTERISTIC
name.static final org.opengis.util.ScopedName
Conventional name for fetching the unit of measurement of a property.static final org.opengis.util.GenericName
Conventional name for fetching the enumeration of valid values. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Do not allow instantiation of this class. -
Method Summary
Modifier and TypeMethodDescriptionstatic boolean
Returns whether the given operation or attribute type is characterized by a coordinate reference system.static boolean
Returns whether the given operation or attribute type is characterized by a maximal length.static boolean
contains
(org.opengis.util.GenericName name) Returnstrue
if the given name stands for one of the synthetic properties defined by convention.private static Object
getCharacteristic
(Object attribute, String name) Fetches from the given property the value or default value of the named characteristic.private static Object
getCharacteristic
(DefaultFeatureType feature, AbstractIdentifiedType property, String characteristic) Fetches from the given property the default value of the characteristic of the given name.static org.opengis.referencing.crs.CoordinateReferenceSystem
getCRSCharacteristic
(Object attribute) Returns the Coordinate Reference Systems characteristic for the given attribute, ornull
if none.static org.opengis.referencing.crs.CoordinateReferenceSystem
getCRSCharacteristic
(DefaultFeatureType feature, AbstractIdentifiedType attribute) Returns the Coordinate Reference Systems characteristic for the given property type, ornull
if none.static Integer
getMaximalLengthCharacteristic
(Object attribute) Returns the maximal length characteristic for the given attribute, ornull
if none.static Integer
getMaximalLengthCharacteristic
(DefaultFeatureType feature, AbstractIdentifiedType attribute) Returns the maximal length characteristic for the given property type, ornull
if none.private static boolean
hasCharacteristic
(AbstractIdentifiedType type, String name, Class<?> valueClass) Returnstrue
if the given operation or attribute type has a characteristic of the given name, and the values of that characteristic are assignable to the givenvalueClass
.static boolean
hasIdentifier
(DefaultFeatureType feature) Returnstrue
if the given feature type is non-null and has a "sis:identifier" property.static boolean
Returnstrue
if the given type is anAttributeType
or anOperation
computing an attribute, and the attribute value is one of the geometry types recognized by SIS.
-
Field Details
-
SCOPE
private static final org.opengis.util.LocalName SCOPEScope of all names defined by SIS convention. -
IDENTIFIER_PROPERTY
public static final org.opengis.util.ScopedName IDENTIFIER_PROPERTYConventional name for a property used as a unique identifier. The identifier should be unique in theDataStore
instance containing the feature (for example aDataStore
opened for a XML file), but does not need to be unique between two independentDataStore
instances.Properties of this name are usually aliases for existing attributes, or compound keys made by concatenation of two or more other attributes.
The value class is usually
String
,Integer
,UUID
or other types commonly used as identifiers. -
GEOMETRY_PROPERTY
public static final org.opengis.util.ScopedName GEOMETRY_PROPERTYConventional name for a property containing the geometric object to use by default. Some features may contain more than one geometric object; this property tells which geometry to render on a map for example.Properties of this name are usually operations acting as a redirection to another attribute.
The value class can be the
Geometry
class from ESRI's API, or theGeometry
class from Java Topology Suite (JTS) library, or any other class defined in future SIS versions. SeeisGeometryAttribute(IdentifiedType)
for testing whether the value is a supported type. -
ENVELOPE_PROPERTY
public static final org.opengis.util.ScopedName ENVELOPE_PROPERTYConventional name for fetching the envelope encompassing all geometries in a feature. MostFeatureType
s have at most one geometry, which is also thedefault geometry
. But if several geometries exist, then the value for this synthetic property is the union of all geometries.Properties of this name are usually operations.
The value class should be
Envelope
. -
CRS_CHARACTERISTIC
public static final org.opengis.util.ScopedName CRS_CHARACTERISTICConventional name for fetching the Coordinate Reference System (CRS) of a geometry or a coverage. This characteristic is typically an entry in the map returned by a call to theDefaultAttributeType.characteristics()
method on the attribute referenced byGEOMETRY_PROPERTY
.While it is technically possible to have different CRS for different feature instances, in most cases the CRS is the same for all geometries found in
GEOMETRY_PROPERTY
. In such cases, the CRS can be specified only once as the default value of thisCRS_CHARACTERISTIC
.The value class should be
CoordinateReferenceSystem
.- See Also:
-
UNIT_CHARACTERISTIC
public static final org.opengis.util.ScopedName UNIT_CHARACTERISTICConventional name for fetching the unit of measurement of a property. This characteristic is typically an entry in the map returned by a call to theDefaultAttributeType.characteristics()
method on any attribute of numeric type.While it is technically possible to have different units of measurement for the same property on different feature instances, in most cases the unit is the same for all feature instances. In such cases, the unit can be specified only once as the default value.
The value class should be
Unit
. -
MAXIMAL_LENGTH_CHARACTERISTIC
public static final org.opengis.util.ScopedName MAXIMAL_LENGTH_CHARACTERISTICConventional name for fetching the maximal length of string values. The maximal length is stored as the default value of the characteristic associated to the attribute on which the maximal length applies.The value class should be
Integer
.- See Also:
-
VALID_VALUES_CHARACTERISTIC
public static final org.opengis.util.GenericName VALID_VALUES_CHARACTERISTICConventional name for fetching the enumeration of valid values. The set of valid values is stored stored as the default value of the characteristic associated to the attribute on which the restriction applies. -
IDENTIFIER
String representation of theIDENTIFIER_PROPERTY
name. This can be used in calls toAbstractFeature.getPropertyValue(String)
.- See Also:
-
GEOMETRY
String representation of theGEOMETRY_PROPERTY
name. This can be used in calls toAbstractFeature.getPropertyValue(String)
.- See Also:
-
ENVELOPE
String representation of theENVELOPE_PROPERTY
name. This can be used in calls toFeature#getPropertyValue(String)
.- See Also:
-
CRS
String representation of theCRS_CHARACTERISTIC
name.- See Also:
-
UNIT
String representation of theUNIT_CHARACTERISTIC
name.- See Also:
-
MAXIMAL_LENGTH
String representation of theMAXIMAL_LENGTH_CHARACTERISTIC
name.- See Also:
-
-
Constructor Details
-
AttributeConvention
private AttributeConvention()Do not allow instantiation of this class.
-
-
Method Details
-
contains
public static boolean contains(org.opengis.util.GenericName name) Returnstrue
if the given name stands for one of the synthetic properties defined by convention. Conventional properties are properties added by theDataStore
to theFeatureType
in order to provide a uniform way to access commonly used information.Synthetic properties should generally not be written by the user. Those properties are calculated most of the time and have only a meaning within SIS.
Current implementation returns
true
if the given name is in the SIS namespace.- Parameters:
name
- the name of the property or characteristic to test, ornull
.- Returns:
true
if the given name is non-null and in the SIS namespace.
-
hasIdentifier
Returnstrue
if the given feature type is non-null and has a "sis:identifier" property.- Parameters:
feature
- the feature type to test, ornull
.- Returns:
- whether the given feature type is non-null and has a "sis:identifier" property.
-
isGeometryAttribute
Returnstrue
if the given type is anAttributeType
or anOperation
computing an attribute, and the attribute value is one of the geometry types recognized by SIS. The types currently recognized by SIS are:Geometry
of the ESRI's API.
- Parameters:
type
- the type to test, ornull
.- Returns:
true
if the given type is (directly or indirectly) an attribute type for one of the recognized geometry types.- See Also:
-
characterizedByCRS
Returns whether the given operation or attribute type is characterized by a coordinate reference system. This method verifies whether a characteristic namedCRS_CHARACTERISTIC
with values assignable toCoordinateReferenceSystem
exists (directly or indirectly) for the given type.- Parameters:
type
- the operation or attribute type for which to get the CRS, ornull
.- Returns:
true
if a characteristic for Coordinate Reference System has been found.
-
getCRSCharacteristic
public static org.opengis.referencing.crs.CoordinateReferenceSystem getCRSCharacteristic(Object attribute) Returns the Coordinate Reference Systems characteristic for the given attribute, ornull
if none. This method gets the value or default value from the characteristic namedCRS_CHARACTERISTIC
.- Parameters:
attribute
- the attribute for which to get the CRS, ornull
.- Returns:
- the Coordinate Reference System characteristic of the given attribute, or
null
if none. - Throws:
ClassCastException
- ifCRS_CHARACTERISTIC
has been found but is associated to an object which is not aCoordinateReferenceSystem
instance.- See Also:
-
getCRSCharacteristic
public static org.opengis.referencing.crs.CoordinateReferenceSystem getCRSCharacteristic(DefaultFeatureType feature, AbstractIdentifiedType attribute) Returns the Coordinate Reference Systems characteristic for the given property type, ornull
if none. This method gets the default value from the characteristic namedCRS_CHARACTERISTIC
. If the given property is a link, then this method follows the link in the given feature type (if non-null).This method should be used only when the actual property instance is unknown. Otherwise,
getCRSCharacteristic(Property)
should be used because the CRS may vary for each property instance.- Parameters:
feature
- the feature type in which to follow links, ornull
if none.attribute
- the attribute type for which to get the CRS, ornull
.- Returns:
- the Coordinate Reference System characteristic of the given property type, or
null
if none. - Throws:
ClassCastException
- ifCRS_CHARACTERISTIC
has been found but is associated to an object which is not aCoordinateReferenceSystem
instance.
-
characterizedByMaximalLength
Returns whether the given operation or attribute type is characterized by a maximal length. This method verifies whether a characteristic namedMAXIMAL_LENGTH_CHARACTERISTIC
with values of classInteger
exists (directly or indirectly) for the given type.- Parameters:
type
- the operation or attribute type for which to get the maximal length, ornull
.- Returns:
true
if a characteristic for maximal length has been found.
-
getMaximalLengthCharacteristic
Returns the maximal length characteristic for the given attribute, ornull
if none. This method gets the value or default value from the characteristic namedMAXIMAL_LENGTH_CHARACTERISTIC
.- Parameters:
attribute
- the attribute for which to get the maximal length, ornull
.- Returns:
- the maximal length characteristic of the given attribute, or
null
if none. - Throws:
ClassCastException
- ifMAXIMAL_LENGTH_CHARACTERISTIC
has been found but is associated to an object which is not anInteger
instance.- See Also:
-
getMaximalLengthCharacteristic
public static Integer getMaximalLengthCharacteristic(DefaultFeatureType feature, AbstractIdentifiedType attribute) Returns the maximal length characteristic for the given property type, ornull
if none. This method gets the default value from the characteristic namedMAXIMAL_LENGTH_CHARACTERISTIC
. If the given property is a link, then this method follows the link in the given feature type (if non-null).This method should be used only when the actual property instance is unknown. Otherwise,
getMaximalLengthCharacteristic(Property)
should be used because the maximal length may vary for each property instance.- Parameters:
feature
- the feature type in which to follow links, ornull
if none.attribute
- the attribute type for which to get the maximal length, ornull
.- Returns:
- the maximal length characteristic of the given property type, or
null
if none. - Throws:
ClassCastException
- ifMAXIMAL_LENGTH_CHARACTERISTIC
has been found but is associated to an object which is not aCoordinateReferenceSystem
instance.
-
hasCharacteristic
private static boolean hasCharacteristic(AbstractIdentifiedType type, String name, Class<?> valueClass) Returnstrue
if the given operation or attribute type has a characteristic of the given name, and the values of that characteristic are assignable to the givenvalueClass
.- Parameters:
type
- the operation or attribute type for which to test the existence of a characteristic.name
- the name of the characteristic to test.valueClass
- the expected characteristic values.- Returns:
true
if a characteristic of the given name exists and has values assignable to the given class.
-
getCharacteristic
Fetches from the given property the value or default value of the named characteristic. If the given property is null, or is not an attribute, or does not have characteristics of the given name, then this method returnsnull
.- Parameters:
attribute
- the attribute from which to get the characteristic value or default value, ornull
.name
- name of the characteristic to get.- Returns:
- the value or default value of the given characteristic in the given property, or
null
if none.
-
getCharacteristic
private static Object getCharacteristic(DefaultFeatureType feature, AbstractIdentifiedType property, String characteristic) Fetches from the given property the default value of the characteristic of the given name. If the given property is a link, then this method follows the link in the given feature type (unless that feature type is null).- Parameters:
feature
- the feature type in which to follow links, ornull
if none.property
- the property from which to get the characteristic value, ornull
.characteristic
- name of the characteristic from which to get the default value.- Returns:
- the default value of the named characteristic in the given property, or
null
if none.
-