Class AttributeTypeBuilder<V>

Type Parameters:
V - the class of attribute values.
All Implemented Interfaces:
Localized

public final class AttributeTypeBuilder<V> extends PropertyTypeBuilder
Describes one AttributeType which will be part of the feature type to be built by a FeatureTypeBuilder. An attribute can be for example a city name, a temperature (together with its units of measurement and uncertainty if desired) or a geometric shape. Attribute types contain the following information:
  • the name — a unique name which can be defined within a scope (or namespace).
  • the definition — a concise definition of the element.
  • the designation — a natural language designator for the element for user interfaces.
  • the description — information beyond that required for concise definition of the element.
  • the value class — often String, Float or Geometry. Must be specified at construction time.
  • a default value — to be used when an attribute instance does not provide an explicit value.
  • characteristics — for example the units of measurement for all attributes of the same type.
  • multiplicity — the minimum and maximum occurrences of attribute values.
Since:
0.8
Version:
0.8
See Also:
  • Field Details

    • valueClass

      private final Class<V> valueClass
      The class of attribute values. Cannot be changed after construction because this value determines the parameterized type <V>.
    • defaultValue

      private V defaultValue
      The default value for the attribute, or null if none.
    • isIdentifier

      private boolean isIdentifier
      Whether this attribute will be used in a compound key named "sis:identifier". If only one attribute has this flag and FeatureTypeBuilder.idPrefix and isSuffix are null, then "sis:identifier" will be a link to idAttributes[0].
      See Also:
    • characteristics

      final List<CharacteristicTypeBuilder<?>> characteristics
      Builders for the characteristics associated to the attribute.
    • property

      private transient DefaultAttributeType<V> property
      The attribute type created by this builder, or null if not yet created. This field must be cleared every time that a setter method is invoked on this builder.
  • Constructor Details

    • AttributeTypeBuilder

      private AttributeTypeBuilder(AttributeTypeBuilder<?> builder, Class<V> valueClass) throws UnconvertibleObjectException
      Creates a new builder initialized to the values of the given builder. This constructor is for setValueClass(Class) implementation only.
      Throws:
      UnconvertibleObjectException - if the default value cannot be converted to the given class.
    • AttributeTypeBuilder

      AttributeTypeBuilder(FeatureTypeBuilder owner, Class<V> valueClass)
      Creates a new AttributeType builder for values of the given class.
      Parameters:
      owner - the builder of the FeatureType for which to add the attribute.
      valueClass - the class of attribute values.
    • AttributeTypeBuilder

      AttributeTypeBuilder(FeatureTypeBuilder owner, DefaultAttributeType<V> template)
      Creates a new AttributeType builder initialized to the values of an existing attribute.
      Parameters:
      owner - the builder of the FeatureType for which to add the attribute.
  • Method Details

    • clearCache

      final void clearCache()
      If the AttributeType created by the last call to build() has been cached, clears that cache. This method must be invoked every time that a setter method is invoked.
      Overrides:
      clearCache in class PropertyTypeBuilder
      See Also:
    • getDefaultName

      final String getDefaultName()
      Returns a default name to use if the user did not specified a name. The first letter will be changed to lower case (unless the name looks like an acronym) for compliance with Java convention on attribute names.
      Overrides:
      getDefaultName in class TypeBuilder
    • setName

      public AttributeTypeBuilder<V> setName(org.opengis.util.GenericName name)
      Sets the AttributeType name as a generic name. If another name was defined before this method call, that previous value will be discarded.
      Overrides:
      setName in class PropertyTypeBuilder
      Parameters:
      name - the generic name (cannot be null).
      Returns:
      this for allowing method calls chaining.
      See Also:
    • setName

      public AttributeTypeBuilder<V> setName(CharSequence localPart)
      Sets the AttributeType name as a simple string (local name). The namespace will be the value specified by the last call to FeatureTypeBuilder.setNameSpace(CharSequence), but that namespace will not be visible in the string representation unless the fully qualified name is requested.

      This convenience method creates a LocalName instance from the given CharSequence, then delegates to setName(GenericName).

      Overrides:
      setName in class PropertyTypeBuilder
      Parameters:
      localPart - the local part of the generic name as a String or InternationalString.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • setName

      public AttributeTypeBuilder<V> setName(CharSequence... components)
      Sets the AttributeType name as a string in the given scope. The components array must contain at least one element. The last component (the tip) will be sufficient in many cases for calls to the AbstractFeature.getProperty(String) method. The other elements before the last one are optional and can be used for resolving ambiguity. They will be visible as the name path.
      Example: a call to setName("A", "B", "C") will create a "A:B:C" name. An attribute built with this name can be obtained from a feature by a call to feature.getProperty("C") if there is no ambiguity, or otherwise by a call to feature.getProperty("B:C") (if non-ambiguous) or feature.getProperty("A:B:C").
      In addition to the path specified by the components array, the name may also contain a namespace specified by the last call to FeatureTypeBuilder.setNameSpace(CharSequence). But contrarily to the specified components, the namespace will not be visible in the name string representation unless the fully qualified name is requested.

      This convenience method creates a LocalName or ScopedName instance depending on whether the names array contains exactly 1 element or more than 1 element, then delegates to setName(GenericName).

      Overrides:
      setName in class PropertyTypeBuilder
      Parameters:
      components - the name components as an array of String or InternationalString instances.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • setMinimumOccurs

      public AttributeTypeBuilder<V> setMinimumOccurs(int occurs)
      Sets the minimum number of attribute values. If the given number is greater than the maximal number of attribute values, than the maximum is also set to that value.
      Overrides:
      setMinimumOccurs in class PropertyTypeBuilder
      Parameters:
      occurs - the new minimum number of attribute values.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • setMaximumOccurs

      public AttributeTypeBuilder<V> setMaximumOccurs(int occurs)
      Sets the maximum number of attribute values. If the given number is less than the minimal number of attribute values, than the minimum is also set to that value. Integer.MAX_VALUE means that there is no maximum.
      Overrides:
      setMaximumOccurs in class PropertyTypeBuilder
      Parameters:
      occurs - the new maximum number of attribute values.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • getValueClass

      public Class<V> getValueClass()
      Returns the class of attribute values.
      Returns:
      the class of attribute values.
      See Also:
    • setValueClass

      public <N> AttributeTypeBuilder<N> setValueClass(Class<N> type) throws UnconvertibleObjectException
      Sets the class of attribute values. Callers must use the builder returned by this method instead of this builder after this method call, since the returned builder may be a new instance.
      Type Parameters:
      N - the compile-time value of the type argument.
      Parameters:
      type - the new class of attribute values.
      Returns:
      the attribute builder — not necessarily this instance.
      Throws:
      UnconvertibleObjectException - if the default value cannot be converted to the given <N> class.
      See Also:
    • getDefaultValue

      public V getDefaultValue()
      Returns the default value for the attribute, or null if none.
      Returns:
      the default attribute value, or null if none.
      See Also:
    • setDefaultValue

      public AttributeTypeBuilder<V> setDefaultValue(V value)
      Sets the default value for the attribute.
      Parameters:
      value - default attribute value, or null if none.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • getValidValues

      public V[] getValidValues()
      Returns an enumeration of valid values for the attribute, or an empty array if none. This convenience method returns the value of the characteristic set by setValidValues(Object...).
      Returns:
      valid values for the attribute, or an empty array if none.
    • setValidValues

      @SafeVarargs public final AttributeTypeBuilder<V> setValidValues(V... values)
      Sets an enumeration of valid values for the attribute.

      This is a convenience method for addCharacteristic(Class) with a value of type Set and a conventional name.

      Parameters:
      values - valid values.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • getMaximalLength

      public Integer getMaximalLength()
      Returns the maximal length that characterizes the CharSequence values of this attribute. This convenience method returns the value of the characteristic set by setMaximalLength(Integer).
      Returns:
      the maximal length of CharSequence attribute values, or null.
    • setMaximalLength

      public AttributeTypeBuilder<V> setMaximalLength(Integer length)
      Sets the maximal length that characterizes the CharSequence values of this attribute. While this characteristic can be applied to any kind of attribute, it is meaningful only with character sequences.

      This is a convenience method for addCharacteristic(Class) with a value of type Integer and a conventional name.

      Parameters:
      length - maximal length of CharSequence attribute values, or null.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • getUnit

      public javax.measure.Unit<?> getUnit()
      Returns the unit of measurement associated to attribute values. This convenience method returns the value of the characteristic set by setUnit(Unit).
      Returns:
      the unit of measurement associated to attribute values, or null.
    • setUnit

      public AttributeTypeBuilder<V> setUnit(javax.measure.Unit<?> unit)
      Sets the unit of measurement that characterizes the values of this attribute. While this characteristic can be applied to any kind of attribute, it is meaningful only with numeric values.

      This is a convenience method for addCharacteristic(Class) with a value of type Unit and a conventional name.

      Parameters:
      unit - unit of measurement associated to attribute values, or null.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • getCRS

      public org.opengis.referencing.crs.CoordinateReferenceSystem getCRS()
      Returns the coordinate reference system associated to attribute values. This convenience method returns the value of the characteristic set by setCRS(CoordinateReferenceSystem).
      Returns:
      the coordinate reference system associated to attribute values, or null.
    • setCRS

      public AttributeTypeBuilder<V> setCRS(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Sets the coordinate reference system that characterizes the values of this attribute. While this characteristic can be applied to any kind of attribute, it is meaningful only with georeferenced values like geometries or coverages.

      This is a convenience method for addCharacteristic(Class) with a value of type CoordinateReferenceSystem and a conventional name.

      Parameters:
      crs - coordinate reference system associated to attribute values, or null.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • getCharacteristic

      private Object getCharacteristic(org.opengis.util.GenericName name)
      Implementation of all getter methods for characteristics.
    • setCharacteristic

      private <C> AttributeTypeBuilder<V> setCharacteristic(org.opengis.util.GenericName name, Class<C> type, C value)
      Implementation of all setter methods for characteristics.
    • getCharacteristic

      public CharacteristicTypeBuilder<?> getCharacteristic(String name)
      Returns the builder for the characteristic of the given name. The given name does not need to contains all elements of a ScopedName; it is okay to specify only the tip (for example "myName" instead of "myScope:myName") provided that ignoring the name head does not create ambiguity.
      Parameters:
      name - name of the characteristic to search.
      Returns:
      characteristic of the given name, or null if none.
      Throws:
      IllegalArgumentException - if the given name is ambiguous.
      See Also:
    • addCharacteristic

      public <C> CharacteristicTypeBuilder<C> addCharacteristic(Class<C> type)
      Adds another attribute type that describes this attribute type. See "Attribute characterization" in DefaultAttributeType Javadoc for more information.

      Usage example:

      The default characteristic name is the name of the given type, but callers should invoke one of the CharacteristicTypeBuilder.setName(…) methods on the returned instance with a better name.
      Type Parameters:
      C - the compile-time type of type argument.
      Parameters:
      type - the class of characteristic values.
      Returns:
      a builder for a characteristic of this attribute.
      See Also:
    • addCharacteristic

      public <C> CharacteristicTypeBuilder<C> addCharacteristic(DefaultAttributeType<C> template)
      Adds another attribute type that describes this attribute type, using an existing one as a template. See "Attribute characterization" in DefaultAttributeType Javadoc for more information.
      Warning: The template argument type will be changed to AttributeType if and when such interface will be defined in GeoAPI.
      Type Parameters:
      C - the compile-time type of values in the template argument.
      Parameters:
      template - an existing attribute type to use as a template.
      Returns:
      a builder for a characteristic of this attribute, initialized with the values of the given template.
      See Also:
    • characteristics

      public List<CharacteristicTypeBuilder<?>> characteristics()
      Returns a view of all characteristics added to the AttributeType to build. The returned list is live: changes in this builder are reflected in that list and conversely. However, the returned list allows only remove operations; new characteristics can be added only by calls to one of the set/addCharacteristic(…) methods.
      Returns:
      a live list over the characteristics declared to this builder.
      See Also:
    • roles

      public Set<AttributeRole> roles()
      Returns the roles that the attribute play in the predefined operations managed by AttributeTypeBuilder. The set returned by this method is live: additions or removal on that set are reflected back on this builder, and conversely.
      Returns:
      the roles that the attribute play in the predefined operations managed by AttributeTypeBuilder.
    • addRole

      public boolean addRole(AttributeRole role)
      Flags this attribute as an input of one of the predefined operations managed by AttributeTypeBuilder. Invoking this method is equivalent to invoking roles().add(role).
      Parameters:
      role - the role to add to the attribute (shall not be null).
      Returns:
      true if the given role has been added to the attribute.
    • isIdentifier

      boolean isIdentifier()
      Returns true if AttributeRole.IDENTIFIER_COMPONENT has been associated to this attribute.
      Overrides:
      isIdentifier in class PropertyTypeBuilder
    • setDefinition

      public AttributeTypeBuilder<V> setDefinition(CharSequence definition)
      Sets a concise definition of the element.
      Overrides:
      setDefinition in class PropertyTypeBuilder
      Parameters:
      definition - a concise definition of the element, or null if none.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • setDesignation

      public AttributeTypeBuilder<V> setDesignation(CharSequence designation)
      Sets a natural language designator for the element. This can be used as an alternative to the name in user interfaces.
      Overrides:
      setDesignation in class PropertyTypeBuilder
      Parameters:
      designation - a natural language designator for the element, or null if none.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • setDescription

      public AttributeTypeBuilder<V> setDescription(CharSequence description)
      Sets optional information beyond that required for concise definition of the element. The description may assist in understanding the feature scope and application. If the type is deprecated, then the description should give indication about the replacement (e.g. "superceded by …").
      Overrides:
      setDescription in class PropertyTypeBuilder
      Parameters:
      description - information beyond that required for concise definition of the element, or null if none.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • setDeprecated

      public AttributeTypeBuilder<V> setDeprecated(boolean deprecated)
      Sets whether the type is deprecated. If the type is deprecated, then the description should be set to an indication about the replacement (e.g. "superceded by …").
      Overrides:
      setDeprecated in class PropertyTypeBuilder
      Parameters:
      deprecated - whether this type is deprecated.
      Returns:
      this for allowing method calls chaining.
      See Also:
    • toStringInternal

      final void toStringInternal(StringBuilder buffer)
      Appends a text inside the value returned by TypeBuilder.toString(), before the closing bracket.
      Overrides:
      toStringInternal in class TypeBuilder
    • remove

      public void remove()
      Removes this property from the FeatureTypeBuilder. After this method has been invoked, this PropertyTypeBuilder instance is no longer in the list returned by FeatureTypeBuilder.properties() and attempts to invoke any setter method on this will cause an IllegalStateException to be thrown.
      Overrides:
      remove in class PropertyTypeBuilder
    • build

      public DefaultAttributeType<V> build()
      Builds the attribute type from the information specified to this builder. If a type has already been built and this builder state has not changed since the type creation, then the previously created AttributeType instance is returned.
      Example: the following lines of code add a "name" attribute to a "City" feature, then get the corresponding AttributeType<String> instance. If no setter method is invoked on the builder of the "name" attribute after those lines, then the name variable below will reference the same instance than the "name" attribute in the city type. Note that city.getProperty("name") returns AttributeType<?>, i.e. the value class is lost at compile-time. By comparison, this build() method has a more accurate return type.
      Warning: In a future SIS version, the return type may be changed to the org.opengis.feature.AttributeType interface. This change is pending GeoAPI revision.
      Specified by:
      build in class PropertyTypeBuilder
      Returns:
      the attribute type.