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

# Class AssociationRoleBuilder

Object
TypeBuilder
PropertyTypeBuilder
AssociationRoleBuilder

All Implemented Interfaces:
  `Localized`

public final class AssociationRoleBuilder extends PropertyTypeBuilder
Describes one association from the `FeatureType` to be built by an `FeatureTypeBuilder` to another `FeatureType`. A different instance of `AssociationRoleBuilder` exists for each feature association to describe. Those instances are created preferably by `FeatureTypeBuilder​.addAssociation(FeatureType)`, or in case of cyclic reference by `FeatureTypeBuilder​.addAssociation(GenericName)`.

Since:
  0.8
See Also:
  - `DefaultAssociationRole`
  - `FeatureTypeBuilder​.addAssociation(DefaultFeatureType)`
  - `FeatureTypeBuilder​.addAssociation(GenericName)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DefaultAssociationRole`
  `build()`
  Builds the association role from the information specified to this builder.
  `AssociationRoleBuilder`
  `setDefinition(CharSequence definition)`
  Sets a concise definition of the element.
  `AssociationRoleBuilder`
  `setDeprecated(boolean deprecated)`
  Sets whether the type is deprecated.
  `AssociationRoleBuilder`
  `setDescription(CharSequence description)`
  Sets optional information beyond that required for concise definition of the element.
  `AssociationRoleBuilder`
  `setDesignation(CharSequence designation)`
  Sets a natural language designator for the element.
  `AssociationRoleBuilder`
  `setMaximumOccurs(int occurs)`
  Sets the maximum number of associations.
  `AssociationRoleBuilder`
  `setMinimumOccurs(int occurs)`
  Sets the minimum number of associations.
  `AssociationRoleBuilder`
  `setName(CharSequence localPart)`
  Sets the `FeatureAssociationRole` name as a simple string (local name).
  `AssociationRoleBuilder`
  `setName(CharSequence... components)`
  Sets the `FeatureAssociationRole` name as a string in the given scope.
  `AssociationRoleBuilder`
  `setName(GenericName name)`
  Sets the `FeatureAssociationRole` name as a generic name.

  ### Methods inherited from class PropertyTypeBuilder

  `getMaximumOccurs, getMinimumOccurs, remove`

  ### 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 AssociationRoleBuilder setName(GenericName name)
    Sets the `FeatureAssociationRole` 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:
      - `TypeBuilder​.getName()`
      - `TypeBuilder​.setName(CharSequence)`
      - `AbstractIdentifiedType​.NAME_KEY`

  - ### setName

    public AssociationRoleBuilder setName(CharSequence localPart)
    Sets the `FeatureAssociationRole` 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 AssociationRoleBuilder setName(CharSequence... components)
    Sets the `FeatureAssociationRole` 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 association 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 AssociationRoleBuilder setMinimumOccurs(int occurs)
    Sets the minimum number of associations. If the given number is greater than the maximal number of associations, than the maximum is also set to that value.
    Overrides:
      `setMinimumOccurs` in class `PropertyTypeBuilder`
    Parameters:
      `occurs` - the new minimum number of associations.
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `PropertyTypeBuilder​.getMinimumOccurs()`

  - ### setMaximumOccurs

    public AssociationRoleBuilder setMaximumOccurs(int occurs)
    Sets the maximum number of associations. If the given number is less than the minimal number of associations, 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 associations.
    Returns:
      `this` for allowing method calls chaining.
    See Also:
      - `PropertyTypeBuilder​.getMaximumOccurs()`

  - ### setDefinition

    public AssociationRoleBuilder 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 AssociationRoleBuilder 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 AssociationRoleBuilder 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 AssociationRoleBuilder 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`

  - ### build

    public DefaultAssociationRole build()
    Builds the association role from the information specified to this builder. If a role has already been built and this builder state has not changed since the role creation, then the previously created `FeatureAssociationRole` instance is returned.
    Warning: In a future SIS version, the return type may be changed to the `org​.opengis​.feature​.FeatureAssociationRole` interface. This change is pending GeoAPI revision.
    Specified by:
      `build` in class `PropertyTypeBuilder`
    Returns:
      the association role.