com.mapinfo.midev.feature

## Interface IFeatureCollection

All Superinterfaces:
  Serializable

All Known Subinterfaces:
  IDataSourceTable

All Known Implementing Classes:
  FeatureCollection

    public interface IFeatureCollection
    extends Serializable

Represents a collection of simple features. An IFeatureCollection is restricted to contain only instances of IFeature. Furthermore, each IFeature contained within the collection must share the same schema (e.g. same collection of attribute definitions - IAttributeDefinition).

Refer to the package level documentation for a detailed discussion of the Feature Model.

See Also:
  `IFeature`, `IAttributeDefinition`, `IGeometryAttributeDefinition`, `Feature`

### Method Summary

All Methods Instance Methods Abstract Methods Default Methods
`default void` `add(IFeature feature)` Adds the specified feature to this feature collection or throws an UnsupportedOperationException if this feature collection does not support adding a feature.
`default void` `addAll(IFeatureCollection features)` Adds all of the feature instances in the specified feature collection to this feature collection.
`default void` `clear()` Removes all features from this feature collection.
`IFeatureCollectionMetadata` `getMetadata()` Accesses the metadata that describes this feature collection.
`boolean` `isReadOnly()` Indicates if the feature collection is read only.
`boolean` `isTransient()` Indicates if this `IFeatureCollection` is transient.
`IFeatureIterator` `iterator()` Returns an iterator for accessing each of the `IFeature` instances contained within this feature collection.
`default void` `remove(IFeature feature)` Removes the specified feature from this collection.
`default void` `removeAll(IFeatureCollection features)` Removes all of the supplied features from this feature collection.

### Method Detail

#### getMetadata

    IFeatureCollectionMetadata getMetadata()

Accesses the metadata that describes this feature collection.

Returns:
  An instance of `IFeatureCollectionMetadata`.

#### isTransient

    boolean isTransient()

Indicates if this `IFeatureCollection` is transient. An instance of `IFeatureCollection` may have a lifetime that is controlled by an iterator, cursor, or other entity. A typical occurrence of transient features occurs when searching a database table. The feature iterator used to return the data in the result set returns `IFeatureCollection` instances whose data is connected to the memory of the cursor. When the next feature is accessed, the same memory is reused, thus making the previous feature invalid. These features are said to be transient.

There is no guarantee that repositioning a cursor returns the same feature each time, however, even if different feature instances are returned, the previous feature instance should be assumed to be invalid and cannot be accessed.

Transient does not have any relationship to the editability of the data. Features, feature collections, and tables may be edited even if they are designated as transient. Transient simply refers to the lifetime of the `IFeatureCollection` and whether or not its memory may be reclaimed or reused as the result of some other action such as advancing an iterator or cursor.

Returns:
  `true` if this feature is transient; false otherwise.

#### isReadOnly

    boolean isReadOnly()

Indicates if the feature collection is read only.

Refer to the Read Only Properties and Determination section of the package summary for more comprehensive coverage.

Returns:
  `true` if this feature collection denies edits; `false` otherwise.

#### iterator

    IFeatureIterator iterator()

Returns an iterator for accessing each of the `IFeature` instances contained within this feature collection.

Feature collections that are backed by database management system or other data access technology may have to build and execute a SQL statement such as "Select * From ..." to provide access to the features. If this is the case, it is important to always dispose of the IFeatureIterator. Refer to the `IFeatureIterator.dispose()` documentation for more details.

Returns:
  an iterator for accessing the features in this feature collection.

#### add

    default void add(IFeature feature)

Adds the specified feature to this feature collection or throws an UnsupportedOperationException if this feature collection does not support adding a feature.

The default implementation throws an UnsupportedOperationException.

Parameters:
  `feature` - the feature to add to this feature collection.
Throws:
  `UnsupportedOperationException` - if this feature collection does not support additions.
  `NullPointerException` - if the specified feature is null.
  `MetadataMismatchException` - if the metadata of the specified feature does not match this collections metadata.

#### addAll

    default void addAll(IFeatureCollection features)

Adds all of the feature instances in the specified feature collection to this feature collection. The supplied feature collection must have the same metadata schema as this collection.

The default implementation does the equivalent of thew following: `features.iterator().forEachRemaining(this::add);`

Parameters:
  `features` - the features to add to this feature collection.
Throws:
  `UnsupportedOperationException` - if this feature collection does not support additions.
  `NullPointerException` - if the specified feature collection is null.
  `MetadataMismatchException` - if the feature metadata does not match the collection metadata.

#### remove

    default void remove(IFeature feature)

Removes the specified feature from this collection. Membership in a feature collection is implementation specific. Therefore, removing a feature from a collection may also have implementation specific behavior, particularly as it relates to identifying the feature to remove. Some feature collection implementations may locate the feature using a reference comparison while other implementations may simply build a database DELETE statement using the feature's identifier as a key.

The default implementation throws an UnsupportedOperationException.

Parameters:
  `feature` - the feature to remove from the collection.
Throws:
  `UnsupportedOperationException` - if this feature collection does not support removals.
  `NullPointerException` - if the specified feature is null.
  `MetadataMismatchException` - if the feature metadata does not match the collection metadata.

#### removeAll

    default void removeAll(IFeatureCollection features)

Removes all of the supplied features from this feature collection.

Parameters:
  `features` - the feature to remove from this feature collection.

  The default implementation does the equivalent of thew following: `features.iterator().forEachRemaining(this::remove);`

Throws:
  `UnsupportedOperationException` - if this feature collection does not support removals.
  `NullPointerException` - if the specified feature collection is null.
  `MetadataMismatchException` - if the feature metadata does not match the collection metadata.

#### clear

    default void clear()

Removes all features from this feature collection. The semantics of this operation are implementation dependent. Some feature collection implementations hold onto references to feature objects while others, such as client-side representations of server-based tables, persist features to and from the data store.

Clearing a feature collection may physically remove all of the data in the collection. For feature collections that are client side representations of physical data stored in a server, file, web service, or other data store, this operation is similar to issuing a "DELETE FROM table" command with no where-clause.

The default implementation throws an UnsupportedOperationException.

Throws:
  `UnsupportedOperationException` - if this feature collection does not support clearing features..