Package org.apache.sis.feature

# Class DefaultFeatureType

Object
AbstractIdentifiedType
DefaultFeatureType

All Implemented Interfaces:
  `Serializable`, `Deprecable`

public class DefaultFeatureType extends AbstractIdentifiedType
Abstraction of a real-world phenomena. A `FeatureType` instance describes the class of all feature instances of that type.
Analogy: compared to the Java language, `FeatureType` is equivalent to `Class` while `Feature` instances are equivalent to `Object` instances of that class.
Warning: This class is expected to implement a GeoAPI `FeatureType` interface in a future version. When such interface will be available, most references to `DefaultFeatureType` in the API will be replaced by references to the `FeatureType` interface.

## Naming

The feature type name is mandatory and should be unique. Those names are the main criterion used for deciding if a feature type is assignable from another type. Names can be scoped for avoiding name collision.

## Properties and inheritance

Each feature type can provide descriptions for the following properties:

- Attributes
- Associations to other features
- Operations

In addition, a feature type can inherit the properties of one or more other feature types. Properties defined in the sub-type can override properties of the same name defined in the super-types, provided that values of the sub-type property are assignable to the super-type property.
Analogy: compared to the Java language, the above rule is similar to overriding a method with a more specific return type (a.k.a. covariant return type). This is also similar to Java arrays, which are implicitly covariant (i.e. `String[]` can be casted to `CharSequence[]`, which is safe for read operations but not for write operations — the later may throw `ArrayStoreException`).

## Instantiation

`DefaultFeatureType` can be instantiated directly by a call to its constructor. But a more convenient approach may be to use the `FeatureTypeBuilder` instead, which provides shortcuts for frequently-used operations like creating various `GenericName` instances sharing the same namespace.

## Immutability and thread safety

Instances of this class are immutable if all properties (`GenericName` and `InternationalString` instances) and all arguments (`AttributeType` instances) given to the constructor are also immutable. Such immutable instances can be shared by many objects and passed between threads without synchronization.

Since:
  0.5
See Also:
  - `DefaultAttributeType`
  - `DefaultAssociationRole`
  - `AbstractFeature`
  - `DefaultFeatureTypeInfo`
  - `FeatureNaming`
  - Serialized Form

Defined in the `sis-feature` module

- ## Field Summary

  ### Fields inherited from class AbstractIdentifiedType

  `DEFINITION_KEY, DEPRECATED_KEY, DESCRIPTION_KEY, DESIGNATION_KEY, NAME_KEY`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultFeatureType(Map<String,?> identification, boolean isAbstract, DefaultFeatureType[] superTypes, AbstractIdentifiedType... properties)`
  Constructs a feature type from the given properties.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object obj)`
  Compares this feature type with the given object for equality.
  `GenericName`
  `getName()`
  `Collection<AbstractIdentifiedType>`
  `getProperties(boolean includeSuperTypes)`
  Returns any feature operation, any feature attribute type and any feature association role that carries characteristics of a feature type.
  `AbstractIdentifiedType`
  `getProperty(String name)`
  Returns the attribute, operation or association role for the given name.
  `final Set<DefaultFeatureType>`
  `getSuperTypes()`
  Returns the direct parents of this feature type.
  `int`
  `hashCode()`
  Returns a hash code value for this feature type.
  `final boolean`
  `isAbstract()`
  Returns `true` if the feature type acts as an abstract super-type.
  `boolean`
  `isAssignableFrom(DefaultFeatureType type)`
  Returns `true` if this type is same or a super-type of the given type.
  `boolean`
  `isSimple()`
  Returns `true` if this feature type contains only attributes with [1 … 1] multiplicity, or operations (no feature association).
  `AbstractFeature`
  `newInstance()`
  Creates a new feature instance of this type.
  `String`
  `toString()`
  Formats this feature in a tabular format.

  ### Methods inherited from class AbstractIdentifiedType

  `getDefinition, getDescription, getDesignation, getName, getRemarks, isDeprecated`

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### DefaultFeatureType

    public DefaultFeatureType(Map<String,?> identification, boolean isAbstract, DefaultFeatureType[] superTypes, AbstractIdentifiedType... properties)
    Constructs a feature type from the given properties. The identification map is given unchanged to the super-class constructor. The following table is a reminder of main (not all) recognized map entries:

    Recognized map entries (non exhaustive list)
    Map key | Value type | Returned by
    --- | --- | ---
    "name" | `GenericName` or `String` | `AbstractIdentifiedType.getName()`
    "definition" | `InternationalString` or `String` | `AbstractIdentifiedType.getDefinition()`
    "designation" | `InternationalString` or `String` | `AbstractIdentifiedType.getDesignation()`
    "description" | `InternationalString` or `String` | `AbstractIdentifiedType.getDescription()`
    "deprecated" | `Boolean` | `AbstractIdentifiedType.isDeprecated()`

    Warning: In a future SIS version, the type of array elements may be changed to `org​.opengis​.feature​.FeatureType` and `org​.opengis​.feature​.PropertyType`. This change is pending GeoAPI revision. In the meantime, make sure that the `properties` array contains only attribute types, association roles or operations, not other feature types since the later are not properties in the ISO sense.
    Parameters:
      `identification` - the name and other information to be given to this feature type.
      `isAbstract` - if `true`, the feature type acts as an abstract super-type.
      `superTypes` - the parents of this feature type, or `null` or empty if none.
      `properties` - any feature operation, any feature attribute type and any feature association role that carries characteristics of a feature type.
    See Also:
      - `FeatureTypeBuilder`

- ## Method Details

  - ### isAbstract

    public final boolean isAbstract()
    Returns `true` if the feature type acts as an abstract super-type. Abstract types can not be instantiated.
    Returns:
      `true` if the feature type acts as an abstract super-type.

  - ### isSimple

    public boolean isSimple()
    Returns `true` if this feature type contains only attributes with [1 … 1] multiplicity, or operations (no feature association). Such feature types can be handled as a records.
    Returns:
      `true` if this feature type contains only simple attributes or operations.

  - ### isAssignableFrom

    public boolean isAssignableFrom(DefaultFeatureType type)
    Returns `true` if this type is same or a super-type of the given type. The check is based mainly on the feature type name, which should be unique. However as a safety, this method also checks that all properties in this feature type is assignable from a property of the same name in the given type.

    #### Constraints

    - If A is assignable from B and B is assignable from C, then A is assignable from C.
    Analogy: if we compare `FeatureType` to `Class` in the Java language, then this method is equivalent to `Class​.isAssignableFrom(Class)`.
    Parameters:
      `type` - the type to be checked.
    Returns:
      `true` if instances of the given type can be assigned to association of this type.

  - ### getSuperTypes

    public final Set<DefaultFeatureType> getSuperTypes()
    Returns the direct parents of this feature type.
    Analogy: if we compare `FeatureType` to `Class` in the Java language, then this method is equivalent to `Class​.getSuperclass()` except that feature types allow multi-inheritance.
    Warning: The type of list elements will be changed to `FeatureType` if and when such interface will be defined in GeoAPI.
    Note for subclasses: this method is final because it is invoked (indirectly) by constructors, and invoking a user-overrideable method at construction time is not recommended. Furthermore, many Apache SIS methods need guarantees about the stability of this collection.
    Returns:
      the parents of this feature type, or an empty set if none.

  - ### getProperties

    public Collection<AbstractIdentifiedType> getProperties(boolean includeSuperTypes)
    Returns any feature operation, any feature attribute type and any feature association role that carries characteristics of a feature type. The returned collection will include the properties inherited from the super-types only if `includeSuperTypes` is `true`.
    Warning: The type of list elements will be changed to `PropertyType` if and when such interface will be defined in GeoAPI.
    Parameters:
      `includeSuperTypes` - `true` for including the properties inherited from the super-types, or `false` for returning only the properties defined explicitly in this type.
    Returns:
      feature operation, attribute type and association role that carries characteristics of this feature type (not including parent types).

  - ### getProperty

    public AbstractIdentifiedType getProperty(String name) throws IllegalArgumentException
    Returns the attribute, operation or association role for the given name.
    Warning: The type of returned element will be changed to `PropertyType` if and when such interface will be defined in GeoAPI.
    Parameters:
      `name` - the name of the property to search.
    Returns:
      the property for the given name, or `null` if none.
    Throws:
      `IllegalArgumentException` - if the given argument is not a property name of this feature.
    See Also:
      - `AbstractFeature​.getProperty(String)`

  - ### newInstance

    public AbstractFeature newInstance() throws IllegalStateException
    Creates a new feature instance of this type.
    Analogy: if we compare `FeatureType` to `Class` and `Feature` to `Object` in the Java language, then this method is equivalent to `Class​.newInstance()`.
    Returns:
      a new feature instance.
    Throws:
      `IllegalStateException` - if this feature type is abstract.

  - ### hashCode

    public int hashCode()
    Returns a hash code value for this feature type.
    Overrides:
      `hashCode` in class `AbstractIdentifiedType`
    Returns:
      the hash code for this type.

  - ### equals

    public boolean equals(Object obj)
    Compares this feature type with the given object for equality.
    Overrides:
      `equals` in class `AbstractIdentifiedType`
    Parameters:
      `obj` - the object to compare with this type.
    Returns:
      `true` if the given object is equals to this type.

  - ### toString

    public String toString()
    Formats this feature in a tabular format.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of this feature in a tabular format.
    See Also:
      - `FeatureFormat`

  - ### getName

    GenericName getName()