# Package org.apache.sis.feature

package org.apache.sis.feature
Defines the structure and content of views of real-world phenomenon. The phenomenon to represent (or a fundamental unit of information) is called a feature. The term “feature” may be used in different contexts:

- Feature types
  Define the structure of real-world representations. A feature type lists the attributes, operations or associations to other features (collectively called “properties” or “characteristics”) that a feature can have.
  Analogy: a `FeatureType` in a Spatial Information System is equivalent to a `Class` in the Java language. By extension, `AttributeType` and `Operation` are equivalent to `Field` and `Method` respectively.
- Feature instances (often called only Features)
  Hold the content (or values) that describe one specific real-world object.
  Example: the “Eiffel tower” is a feature instance belonging to the “Tower” feature type.
- Simple features
  Are instances of a feature type with no association to other features, and where all attributes have [1 … 1] multiplicity. Such simple features are very common.

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.

## Naming

Each feature type has a name, which should be unique. Those names are the main criterion used for checking if a feature type is assignable from another type. Names can be scoped for avoiding name collision.

## Class hierarchy

The class hierarchy for feature types is derived from ISO 19109 specification. The class hierarchy for feature instances is closely related:

Feature class hierarchy
Types | Instances
--- | ---
Identified type `├─` Feature type `└─` Property type `├─` Attribute type `├─` Feature association role `└─` Operation | Object `├─` Feature (sparse or dense) `└─` Property `├─` Attribute (singleton or multi-valued) `└─` Feature association (singleton or multi-valued)

## Instantiation

Classes defined in this package are rarely instantiated directly (by a `new` statement). Instead, those classes are instantiated indirectly by invoking a method on a parent container, or by using a builder. The starting point is `FeatureType`, which may be created by a `FeatureTypeBuilder` or may be provided by a `DataStore` reading a data file. Once a `FeatureType` has been obtained, `Feature`s can be instantiated by calls to the `FeatureType​.newInstance()` method. Once a `Feature` instance has been obtained, `Attribute`s can be instantiated indirectly by calls to the `Feature​.setPropertyValue(…)` method.

Since:
  0.5

- Related Packages
  Package
  Description
  org.apache.sis.feature.builder
  Helper classes for creating `FeatureType` instances.
- Class
  Description
  AbstractAssociation
  An instance of an feature association role containing the associated feature.
  AbstractAttribute<V>
  An instance of an attribute type containing the value of an attribute in a feature.
  AbstractFeature
  An instance of a feature type containing values for a real-world phenomena.
  AbstractIdentifiedType
  Identification and description information inherited by property types and feature types.
  AbstractOperation
  Describes the behaviour of a feature type as a function or a method.
  DefaultAssociationRole
  Indicates the role played by the association between two features.
  DefaultAttributeType<V>
  Definition of an attribute in a feature type.
  DefaultFeatureType
  Abstraction of a real-world phenomena.
  FeatureFormat
  Formats features or feature types in a tabular format.
  FeatureFormat.Column
  Identifies the columns to include in the table formatted by `FeatureFormat`.
  FeatureOperations
  A set of predefined operations expecting a `Feature` as input and producing an `Attribute` as output.
  Features
  Static methods working on features or attributes.
  FoliationRepresentation
  Specifies whether trajectories are represented in a single moving feature instance or fragmented in distinct static feature instances.