Package org.apache.sis.feature.builder

# Class TypeBuilder

Object
TypeBuilder

All Implemented Interfaces:
  `Localized`

Direct Known Subclasses:
  `CharacteristicTypeBuilder`, `FeatureTypeBuilder`, `PropertyTypeBuilder`

public abstract class TypeBuilder extends Object implements Localized
Information common to all kind of types (feature, association, characteristics). Those information are:

- 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 name is mandatory and can be specified as either `LocalName`, `ScopedName`, `String` or `InternationalString` instance. All other properties are optional.

## Default namespace

In many cases, the names of all `AttributeType`s and `AssociationRole`s to create within a `FeatureType` share the same namespace. For making name creations more convenient, the namespace can be specified once and applied automatically to all names created by the `setName(CharSequence)` method. Note that namespaces will not be visible in the name string representation unless the fully qualified name is requested. Example:

>     FeatureTypeBuilder builder = new FeatureTypeBuilder().setNameSpace("MyNameSpace").setName("City");
>     FeatureType city = builder.build();

>     System.out.println(city.getName());                              // Prints "City"
>     System.out.println(city.getName().toFullyQualifiedName());       // Prints "MyNameSpace:City"

Since:
  0.8

Defined in the `sis-feature` module

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract AbstractIdentifiedType`
  `build()`
  Builds the feature or property type from the information specified to this builder.
  `CharSequence`
  `getDefinition()`
  Returns a concise definition of the element.
  `CharSequence`
  `getDescription()`
  Returns optional information beyond that required for concise definition of the element.
  `CharSequence`
  `getDesignation()`
  Returns a natural language designator for the element.
  `Locale`
  `getLocale()`
  Returns the locale used for formatting error messages, or `null` if unspecified.
  `GenericName`
  `getName()`
  Returns the name of the `IdentifiedType` to create, or `null` if undefined.
  `boolean`
  `isDeprecated()`
  Returns `true` if the type is deprecated.
  `TypeBuilder`
  `setDefinition(CharSequence definition)`
  Sets a concise definition of the element.
  `TypeBuilder`
  `setDeprecated(boolean deprecated)`
  Sets whether the type is deprecated.
  `TypeBuilder`
  `setDescription(CharSequence description)`
  Sets optional information beyond that required for concise definition of the element.
  `TypeBuilder`
  `setDesignation(CharSequence designation)`
  Sets a natural language designator for the element.
  `TypeBuilder`
  `setName(CharSequence localPart)`
  Sets the `IdentifiedType` name as a simple string (local name).
  `TypeBuilder`
  `setName(CharSequence... components)`
  Sets the `IdentifiedType` name as a string in the given scope.
  `TypeBuilder`
  `setName(GenericName name)`
  Sets the `IdentifiedType` name as a generic name.
  `String`
  `toString()`
  Returns a string representation of this object.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### getName

    public GenericName getName()
    Returns the name of the `IdentifiedType` to create, or `null` if undefined. This method returns the value built from the last call to a `setName(…)` method, or a default name or `null` if no name has been explicitly specified.
    Returns:
      the name of the `IdentifiedType` to create (may be a default name or `null`).
    See Also:
      - `setName(GenericName)`
      - `AbstractIdentifiedType​.getName()`
      - `FeatureTypeBuilder​.getNameSpace()`

  - ### setName

    public TypeBuilder setName(GenericName name)
    Sets the `IdentifiedType` name as a generic name. If another name was defined before this method call, that previous value will be discarded.
    Note for subclasses: all `setName(…)` convenience methods in this builder delegate to this method. Consequently this method can be used as a central place where to control the creation of all names.
    Parameters:
      `name` - the generic name (can not be `null`).
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `getName()`
      - `setName(CharSequence)`
      - `AbstractIdentifiedType​.NAME_KEY`

  - ### setName

    public TypeBuilder setName(CharSequence localPart)
    Sets the `IdentifiedType` 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)`.

    Parameters:
      `localPart` - the local part of the generic name as a `String` or `InternationalString`.
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `getName()`
      - `setName(CharSequence...)`
      - `FeatureTypeBuilder​.getNameSpace()`

  - ### setName

    public TypeBuilder setName(CharSequence... components)
    Sets the `IdentifiedType` 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. A property 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)`.

    Parameters:
      `components` - the name components as an array of `String` or `InternationalString` instances.
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `getName()`
      - `setName(CharSequence)`
      - `FeatureTypeBuilder​.getNameSpace()`

  - ### getDefinition

    public CharSequence getDefinition()
    Returns a concise definition of the element.
    Returns:
      concise definition of the element, or `null` if none.
    See Also:
      - `AbstractIdentifiedType​.getDefinition()`

  - ### setDefinition

    public TypeBuilder setDefinition(CharSequence definition)
    Sets a concise definition of the element.
    Parameters:
      `definition` - a concise definition of the element, or `null` if none.
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `getDefinition()`
      - `AbstractIdentifiedType​.DEFINITION_KEY`

  - ### getDesignation

    public CharSequence getDesignation()
    Returns a natural language designator for the element. This can be used as an alternative to the name in user interfaces.
    Returns:
      natural language designator for the element, or `null` if none.
    See Also:
      - `AbstractIdentifiedType​.getDesignation()`

  - ### setDesignation

    public TypeBuilder setDesignation(CharSequence designation)
    Sets a natural language designator for the element. This can be used as an alternative to the name in user interfaces.
    Parameters:
      `designation` - a natural language designator for the element, or `null` if none.
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `getDesignation()`
      - `AbstractIdentifiedType​.DESIGNATION_KEY`

  - ### getDescription

    public CharSequence getDescription()
    Returns optional information beyond that required for concise definition of the element. The description may assist in understanding the element scope and application.
    Returns:
      information beyond that required for concise definition of the element, or `null` if none.
    See Also:
      - `AbstractIdentifiedType​.getDescription()`

  - ### setDescription

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

  - ### isDeprecated

    public boolean isDeprecated()
    Returns `true` if the type is deprecated. If this method returns `true`, then the description should give indication about the replacement (e.g. "superceded by …").
    Returns:
      whether this type is deprecated.
    See Also:
      - `AbstractIdentifiedType​.isDeprecated()`

  - ### setDeprecated

    public TypeBuilder 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 …").
    Parameters:
      `deprecated` - whether this type is deprecated.
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `isDeprecated()`
      - `AbstractIdentifiedType​.DEPRECATED_KEY`

  - ### getLocale

    public Locale getLocale()
    Returns the locale used for formatting error messages, or `null` if unspecified. If unspecified, the system default locale will be used.
    Specified by:
      `getLocale` in interface `Localized`
    Returns:
      the locale used for formatting error messages, or `null` if unspecified.

  - ### toString

    public String toString()
    Returns a string representation of this object. The returned string is for debugging purpose only and may change in any future SIS version.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of this object for debugging purpose.

  - ### build

    public abstract AbstractIdentifiedType build() throws IllegalStateException
    Builds the feature or property 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 `IdentifiedType` instance is returned.
    Warning: In a future SIS version, the return type may be changed to the `org​.opengis​.feature​.IdentifiedType` interface. This change is pending GeoAPI revision.
    Returns:
      the feature or property type.
    Throws:
      `IllegalStateException` - if the builder contains inconsistent information.