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

# Class CharacteristicTypeBuilder<V>

Object
TypeBuilder
CharacteristicTypeBuilder<V>

Type Parameters:
  `V` - the class of characteristic values.

All Implemented Interfaces:
  `Localized`

public final class CharacteristicTypeBuilder<V> extends TypeBuilder
Describes one characteristic of the `AttributeType` will will be built by a `FeatureTypeBuilder`. Characteristics can describe additional information useful for interpreting an attribute value, like the units of measurement and uncertainties of a numerical value, or the coordinate reference system (CRS) of a geometry.

In many cases, all instances of the same `AttributeType` have the same characteristics. For example, all values of the "temperature" attribute typically have the same units of measurement. Such common value can be specified as the characteristic default value.

Since:
  0.8
See Also:
  - `AttributeTypeBuilder​.addCharacteristic(Class)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DefaultAttributeType<V>`
  `build()`
  Builds the characteristic type from the information specified to this builder.
  `V`
  `getDefaultValue()`
  Returns the default value for the characteristic, or `null` if none.
  `Class<V>`
  `getValueClass()`
  Returns the class of characteristic values.
  `void`
  `remove()`
  Removes this characteristics from the `AttributeTypeBuilder`.
  `CharacteristicTypeBuilder<V>`
  `setDefaultValue(V value)`
  Sets the default value for the characteristic.
  `CharacteristicTypeBuilder<V>`
  `setDefinition(CharSequence definition)`
  Sets a concise definition of the element.
  `CharacteristicTypeBuilder<V>`
  `setDeprecated(boolean deprecated)`
  Sets whether the type is deprecated.
  `CharacteristicTypeBuilder<V>`
  `setDescription(CharSequence description)`
  Sets optional information beyond that required for concise definition of the element.
  `CharacteristicTypeBuilder<V>`
  `setDesignation(CharSequence designation)`
  Sets a natural language designator for the element.
  `CharacteristicTypeBuilder<V>`
  `setName(CharSequence localPart)`
  Sets the characteristic name as a simple string (local name).
  `CharacteristicTypeBuilder<V>`
  `setName(CharSequence... components)`
  Sets the characteristic name as a string in the given scope.
  `CharacteristicTypeBuilder<V>`
  `setName(GenericName name)`
  Sets the characteristic name as a generic name.
  `<N> CharacteristicTypeBuilder<N>`
  `setValueClass(Class<N> type)`
  Sets the class of characteristic values.

  ### 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 CharacteristicTypeBuilder<V> setName(GenericName name)
    Sets the characteristic name as a generic name. If another name was defined before this method call, that previous value will be discarded.
    Overrides:
      `setName` in class `TypeBuilder`
    Parameters:
      `name` - the generic name (cannot be `null`).
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `TypeBuilder​.getName()`
      - `TypeBuilder​.setName(CharSequence)`
      - `AbstractIdentifiedType​.NAME_KEY`

  - ### setName

    public CharacteristicTypeBuilder<V> setName(CharSequence localPart)
    Sets the characteristic 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 `TypeBuilder`
    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 CharacteristicTypeBuilder<V> setName(CharSequence... components)
    Sets the characteristic 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 getting values from the characteristics map. The other elements before the last one are optional and can be used for resolving ambiguity. They will be visible as the name path.

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

  - ### getValueClass

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

  - ### setValueClass

    public <N> CharacteristicTypeBuilder<N> setValueClass(Class<N> type) throws UnconvertibleObjectException
    Sets the class of characteristic 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 characteristic values.
    Returns:
      the characteristic 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 characteristic, or `null` if none.
    Returns:
      the default characteristic value, or `null` if none.
    See Also:
      - `setDefaultValue(Object)`

  - ### setDefaultValue

    public CharacteristicTypeBuilder<V> setDefaultValue(V value)
    Sets the default value for the characteristic.
    Parameters:
      `value` - characteristic default value, or `null` if none.
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `getDefaultValue()`

  - ### setDefinition

    public CharacteristicTypeBuilder<V> setDefinition(CharSequence definition)
    Sets a concise definition of the element.
    Overrides:
      `setDefinition` in class `TypeBuilder`
    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 CharacteristicTypeBuilder<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 `TypeBuilder`
    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 CharacteristicTypeBuilder<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 `TypeBuilder`
    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 CharacteristicTypeBuilder<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 `TypeBuilder`
    Parameters:
      `deprecated` - whether this type is deprecated.
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `TypeBuilder​.isDeprecated()`
      - `AbstractIdentifiedType​.DEPRECATED_KEY`

  - ### build

    public DefaultAttributeType<V> build()
    Builds the characteristic 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.
    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 `TypeBuilder`
    Returns:
      the characteristic type.

  - ### remove

    public void remove()
    Removes this characteristics from the `AttributeTypeBuilder`. After this method has been invoked, this `CharacteristicTypeBuilder` instance is no longer in the list returned by `AttributeTypeBuilder​.characteristics()` and attempts to invoke any setter method on `this` will cause an `IllegalStateException` to be thrown.