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

    All Methods Instance Methods Abstract Methods Concrete Methods
    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.
    `Set<DefaultFeatureType>` | `getSuperTypes()` | Returns the direct parents of this feature type.
    `int` | `hashCode()` | Returns a hash code value for this feature type.
    `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 Detail

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

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

          public abstract GenericName getName()