Package org.apache.sis.internal.feature

Class AttributeConvention

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.internal.feature.AttributeConvention
public final class AttributeConvention extends Static
Defines the names of some properties or characteristics for which we assign a conventional usage. Properties with the names defined in this 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.
Example: one of the most frequently used synthetic property is "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.
This class defines names for two kinds of usage:

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 Details

    • SCOPE

      private static final org.opengis.util.LocalName SCOPE
      Scope of all names defined by SIS convention.

    • IDENTIFIER_PROPERTY

      public static final org.opengis.util.ScopedName IDENTIFIER_PROPERTY
      Conventional name for a property used as a unique identifier. The identifier should be unique in the DataStore instance containing the feature (for example a DataStore opened for a XML file), but does not need to be unique between two independent DataStore 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_PROPERTY
      Conventional 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 the Geometry class from Java Topology Suite (JTS) library, or any other class defined in future SIS versions. See isGeometryAttribute(IdentifiedType) for testing whether the value is a supported type.

      See Also:

    • ENVELOPE_PROPERTY

      public static final org.opengis.util.ScopedName ENVELOPE_PROPERTY
      Conventional name for fetching the envelope encompassing all geometries in a feature. Most FeatureTypes have at most one geometry, which is also the default 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_CHARACTERISTIC
      Conventional 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 the DefaultAttributeType.characteristics() method on the attribute referenced by GEOMETRY_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 this CRS_CHARACTERISTIC.

      The value class should be CoordinateReferenceSystem.

      See Also:

    • UNIT_CHARACTERISTIC

      public static final org.opengis.util.ScopedName UNIT_CHARACTERISTIC
      Conventional name for fetching the unit of measurement of a property. This characteristic is typically an entry in the map returned by a call to the DefaultAttributeType.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_CHARACTERISTIC
      Conventional 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_CHARACTERISTIC
      Conventional 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

      public static final String IDENTIFIER
      String representation of the IDENTIFIER_PROPERTY name. This can be used in calls to AbstractFeature.getPropertyValue(String).
      See Also:

    • GEOMETRY

      public static final String GEOMETRY
      String representation of the GEOMETRY_PROPERTY name. This can be used in calls to AbstractFeature.getPropertyValue(String).
      See Also:

    • ENVELOPE

      public static final String ENVELOPE
      String representation of the ENVELOPE_PROPERTY name. This can be used in calls to Feature#getPropertyValue(String).
      See Also:

    • CRS

      public static final String CRS
      String representation of the CRS_CHARACTERISTIC name.
      See Also:

    • UNIT

      public static final String UNIT
      String representation of the UNIT_CHARACTERISTIC name.
      See Also:

    • MAXIMAL_LENGTH

      public static final String MAXIMAL_LENGTH
      String representation of the MAXIMAL_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)
      Returns true if the given name stands for one of the synthetic properties defined by convention. Conventional properties are properties added by the DataStore to the FeatureType 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, or null.
      Returns:
      true if the given name is non-null and in the SIS namespace.

    • hasIdentifier

      public static boolean hasIdentifier(DefaultFeatureType feature)
      Returns true if the given feature type is non-null and has a "sis:identifier" property.
      Parameters:
      feature - the feature type to test, or null.
      Returns:
      whether the given feature type is non-null and has a "sis:identifier" property.

    • isGeometryAttribute

      public static boolean isGeometryAttribute(AbstractIdentifiedType type)
      Returns true if the given type is an AttributeType or an Operation 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.
      The above list may be expanded in any future SIS version.
      Parameters:
      type - the type to test, or null.
      Returns:
      true if the given type is (directly or indirectly) an attribute type for one of the recognized geometry types.
      See Also:

    • characterizedByCRS

      public static boolean characterizedByCRS(AbstractIdentifiedType type)
      Returns whether the given operation or attribute type is characterized by a coordinate reference system. This method verifies whether a characteristic named CRS_CHARACTERISTIC with values assignable to CoordinateReferenceSystem exists (directly or indirectly) for the given type.
      Parameters:
      type - the operation or attribute type for which to get the CRS, or null.
      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, or null if none. This method gets the value or default value from the characteristic named CRS_CHARACTERISTIC.
      Parameters:
      attribute - the attribute for which to get the CRS, or null.
      Returns:
      the Coordinate Reference System characteristic of the given attribute, or null if none.
      Throws:
      ClassCastException - if CRS_CHARACTERISTIC has been found but is associated to an object which is not a CoordinateReferenceSystem 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, or null if none. This method gets the default value from the characteristic named CRS_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, or null if none.
      attribute - the attribute type for which to get the CRS, or null.
      Returns:
      the Coordinate Reference System characteristic of the given property type, or null if none.
      Throws:
      ClassCastException - if CRS_CHARACTERISTIC has been found but is associated to an object which is not a CoordinateReferenceSystem instance.

    • characterizedByMaximalLength

      public static boolean characterizedByMaximalLength(AbstractIdentifiedType type)
      Returns whether the given operation or attribute type is characterized by a maximal length. This method verifies whether a characteristic named MAXIMAL_LENGTH_CHARACTERISTIC with values of class Integer exists (directly or indirectly) for the given type.
      Parameters:
      type - the operation or attribute type for which to get the maximal length, or null.
      Returns:
      true if a characteristic for maximal length has been found.

    • getMaximalLengthCharacteristic

      public static Integer getMaximalLengthCharacteristic(Object attribute)
      Returns the maximal length characteristic for the given attribute, or null if none. This method gets the value or default value from the characteristic named MAXIMAL_LENGTH_CHARACTERISTIC.
      Parameters:
      attribute - the attribute for which to get the maximal length, or null.
      Returns:
      the maximal length characteristic of the given attribute, or null if none.
      Throws:
      ClassCastException - if MAXIMAL_LENGTH_CHARACTERISTIC has been found but is associated to an object which is not an Integer instance.
      See Also:

    • getMaximalLengthCharacteristic

      public static Integer getMaximalLengthCharacteristic(DefaultFeatureType feature, AbstractIdentifiedType attribute)
      Returns the maximal length characteristic for the given property type, or null if none. This method gets the default value from the characteristic named MAXIMAL_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, or null if none.
      attribute - the attribute type for which to get the maximal length, or null.
      Returns:
      the maximal length characteristic of the given property type, or null if none.
      Throws:
      ClassCastException - if MAXIMAL_LENGTH_CHARACTERISTIC has been found but is associated to an object which is not a CoordinateReferenceSystem instance.

    • hasCharacteristic

      private static boolean hasCharacteristic(AbstractIdentifiedType type, String name, Class<?> valueClass)
      Returns true if the given operation or attribute type has a characteristic of the given name, and the values of that characteristic are assignable to the given valueClass.
      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

      private static Object getCharacteristic(Object attribute, String name)
      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 returns null.
      Parameters:
      attribute - the attribute from which to get the characteristic value or default value, or null.
      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, or null if none.
      property - the property from which to get the characteristic value, or null.
      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.