Module org.apache.sis.feature
Package org.apache.sis.feature.builder

# Class AttributeTypeBuilder<V>

Object
TypeBuilder
PropertyTypeBuilder
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
See Also:
  - `FeatureTypeBuilder​.addAttribute(Class)`
  - `DefaultAttributeType`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<C> CharacteristicTypeBuilder<C>`
  `addCharacteristic(Class<C> type)`
  Adds another attribute type that describes this attribute type.
  `<C> CharacteristicTypeBuilder<C>`
  `addCharacteristic(DefaultAttributeType<C> template)`
  Adds another attribute type that describes this attribute type, using an existing one as a template.
  `boolean`
  `addRole(AttributeRole role)`
  Flags this attribute as an input of one of the predefined operations managed by `AttributeTypeBuilder`.
  `DefaultAttributeType<V>`
  `build()`
  Builds the attribute type from the information specified to this builder.
  `List<CharacteristicTypeBuilder<?>>`
  `characteristics()`
  Returns a view of all characteristics added to the `AttributeType` to build.
  `CharacteristicTypeBuilder<?>`
  `getCharacteristic(String name)`
  Returns the builder for the characteristic of the given name.
  `CoordinateReferenceSystem`
  `getCRS()`
  Returns the coordinate reference system associated to attribute values.
  `V`
  `getDefaultValue()`
  Returns the default value for the attribute, or `null` if none.
  `Integer`
  `getMaximalLength()`
  Returns the maximal length that characterizes the `CharSequence` values of this attribute.
  `Unit<?>`
  `getUnit()`
  Returns the unit of measurement associated to attribute values.
  `V[]`
  `getValidValues()`
  Returns an enumeration of valid values for the attribute, or an empty array if none.
  `Class<V>`
  `getValueClass()`
  Returns the class of attribute values.
  `void`
  `remove()`
  Removes this property from the `FeatureTypeBuilder`.
  `Set<AttributeRole>`
  `roles()`
  Returns the roles that the attribute play in the predefined operations managed by `AttributeTypeBuilder`.
  `AttributeTypeBuilder<V>`
  `setCRS(CoordinateReferenceSystem crs)`
  Sets the coordinate reference system that characterizes the values of this attribute.
  `AttributeTypeBuilder<V>`
  `setDefaultValue(V value)`
  Sets the default value for the attribute.
  `AttributeTypeBuilder<V>`
  `setDefinition(CharSequence definition)`
  Sets a concise definition of the element.
  `AttributeTypeBuilder<V>`
  `setDeprecated(boolean deprecated)`
  Sets whether the type is deprecated.
  `AttributeTypeBuilder<V>`
  `setDescription(CharSequence description)`
  Sets optional information beyond that required for concise definition of the element.
  `AttributeTypeBuilder<V>`
  `setDesignation(CharSequence designation)`
  Sets a natural language designator for the element.
  `AttributeTypeBuilder<V>`
  `setMaximalLength(Integer length)`
  Sets the maximal length that characterizes the `CharSequence` values of this attribute.
  `AttributeTypeBuilder<V>`
  `setMaximumOccurs(int occurs)`
  Sets the maximum number of attribute values.
  `AttributeTypeBuilder<V>`
  `setMinimumOccurs(int occurs)`
  Sets the minimum number of attribute values.
  `AttributeTypeBuilder<V>`
  `setName(CharSequence localPart)`
  Sets the `AttributeType` name as a simple string (local name).
  `AttributeTypeBuilder<V>`
  `setName(CharSequence... components)`
  Sets the `AttributeType` name as a string in the given scope.
  `AttributeTypeBuilder<V>`
  `setName(GenericName name)`
  Sets the `AttributeType` name as a generic name.
  `AttributeTypeBuilder<V>`
  `setUnit(Unit<?> unit)`
  Sets the unit of measurement that characterizes the values of this attribute.
  `final AttributeTypeBuilder<V>`
  `setValidValues(V... values)`
  Sets an enumeration of valid values for the attribute.
  `<N> AttributeTypeBuilder<N>`
  `setValueClass(Class<N> type)`
  Sets the class of attribute values.

  ### Methods inherited from class PropertyTypeBuilder

  `getMaximumOccurs, getMinimumOccurs`

  ### Methods inherited from class TypeBuilder

  `getDefinition, getDescription, getDesignation, getLocale, getName, isDeprecated, toString`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Method Details

  - ### setName

    public AttributeTypeBuilder<V> setName(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 attribute name (cannot be `null`).
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `TypeBuilder​.getName()`
      - `TypeBuilder​.setName(CharSequence)`
      - `AbstractIdentifiedType​.NAME_KEY`

  - ### 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:
      - `TypeBuilder​.getName()`
      - `TypeBuilder​.setName(CharSequence...)`
      - `FeatureTypeBuilder​.getNameSpace()`

  - ### 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:
      - `TypeBuilder​.getName()`
      - `TypeBuilder​.setName(CharSequence)`
      - `FeatureTypeBuilder​.getNameSpace()`

  - ### 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:
      - `PropertyTypeBuilder​.getMinimumOccurs()`

  - ### 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:
      - `PropertyTypeBuilder​.getMaximumOccurs()`

  - ### getValueClass

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

  - ### 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:
      - `getValueClass()`

  - ### 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(Object)`

  - ### 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:
      - `getDefaultValue()`

  - ### 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:
      - `characteristics()`

  - ### 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:
      - `characteristics()`

  - ### getUnit

    public 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(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:
      - `characteristics()`

  - ### getCRS

    public 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(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:
      - `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:
      - `characteristics()`

  - ### 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

        attribute.addCharacteristic(Unit.class).setName("Unit of measurement").setDefaultValue(Units.CELSIUS);

    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:
      - `characteristics()`

  - ### 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()`

  - ### 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:
      - `getCharacteristic(String)`
      - `addCharacteristic(Class)`
      - `addCharacteristic(DefaultAttributeType)`
      - `setValidValues(Object...)`
      - `setCRS(CoordinateReferenceSystem)`

  - ### 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.

  - ### 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:
      - `TypeBuilder​.getDefinition()`
      - `AbstractIdentifiedType​.DEFINITION_KEY`

  - ### 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:
      - `TypeBuilder​.getDesignation()`
      - `AbstractIdentifiedType​.DESIGNATION_KEY`

  - ### 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:
      - `TypeBuilder​.getDescription()`
      - `AbstractIdentifiedType​.DESCRIPTION_KEY`

  - ### 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:
      - `TypeBuilder​.isDeprecated()`
      - `AbstractIdentifiedType​.DEPRECATED_KEY`

  - ### 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.

        FeatureTypeBuilder builder = new FeatureTypeBuilder().setName("City");
        AttributeType<String> name = builder.addAttribute(String.class).setName("name").build();
        FeatureType city = builder.build();

        assert city.getProperty("name") == name : "AttributeType instance should be the same.";

    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.