com.mapinfo.midev.data

## Interface IDataSourceTable

All Superinterfaces:
  AutoCloseable, Closeable, IFeatureCollection, Serializable

    public interface IDataSourceTable
    extends IFeatureCollection, Closeable

Represents a feature collection whose data is actively managed by some underlying data provider. The data in the feature collection typically will physically exist in a persisted format either in a file or relational database, or will be accessed through a web service or other protocol. The table is typically a client-side representation of the data. The ITable interface is intended to expose a full suite of data descriptive, query and edit operations through an entirely common API. In other words, table clients should not be required to know any information about the table's actual storage location, format, access technology, or interface language.

As feature collections, tables expose all of the properties and methods defined for any other feature collection such as iterator, add, remove, isReadOnly, etc.

Unlike a general `IFeatureCollection`, however, tables expose events pertaining to changes to the data or metadata as well as methods for searching and editing the features represented by table. Typically, using the default iterator for accessing the features in a table is a poor choice for most needs as this translates to something like `"Select *"` from the underlying database table. This usually returns more data than is needed and translates to performance and scalability problems in the application. Searching a table is the process of locating the specific attributes of the specific feature members of the collection that you may need for some operation (such as rendering). Searching involves the specification of a search (using a language) and the evaluation of a search using some sort of engine (database, web service, etc).

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `add(IDataSourceTableListener listener)` Adds the specified `IDataSourceTableListener` to this `IDataSourceTable`.
`void` `close()` Closes the table, closing and/or releasing any resources acquired.
`IDataSource` `getDataSource()` Returns the IDataSource with which this table is associated.
`ITableDefinition` `getDefinition()` Returns the definition for the table.
`LegendMetadata` `getLegendMetadata(String descriptionColumn, Envelope view)` Returns metadata about the legend.
`ITableMetadata` `getMetadata()` Returns the metadata for the table.
`IKey` `insert(IFeature feature)` Inserts the specified `IFeature` to the underlying table and returns the primary key of inserted features.
`List` `insert(IFeatureCollection featureCollection)` Inserts the specified `IFeatureCollection` to the underlying table and returns the list of primary keys of inserted features.
`List` `insert(IFeatureCollection featureCollection, int commitInterval)` Inserts the specified `IFeatureCollection` to the underlying table and returns the list of primary keys of inserted features.
`boolean` `isClosed()` Indicates if the table has been closed.
`void` `remove(IDataSourceTableListener listener)` Removes the specified `IDataSourceTableListener` from this `IDataSourceTable`.
`ICursor` `search(ISearch search)` Queries the table and returns the features requested.
`ICursor` `search(ISearch search, Map cursorProperties)` Queries the table and returns the features requested.

### Methods inherited from interface com.mapinfo.midev.feature.IFeatureCollection

`add, addAll, clear, isReadOnly, isTransient, iterator, remove, removeAll`

### Method Detail

#### getDefinition

    ITableDefinition getDefinition()

Returns the definition for the table.

Changes to the definition while the table is instantiated may or may not alter the behavior of the table. If the definition should not be changed while the table is open, then attempted changes should throw and exception. This behavior is implementation specific.

Returns:
  the definition for the table.

#### getDataSource

    IDataSource getDataSource()

Returns the IDataSource with which this table is associated. Tables that are not affiliated with a datasource will return a null reference for this property.

Returns:
  the IDataSource with which this table is associated, or null.

#### getMetadata

    ITableMetadata getMetadata()

Returns the metadata for the table. Metadata references should not be cached or held onto for lengthy periods of time by applications. Each call to getMetadata may return a new instance of the table's metadata. The table may cache it's metadata.

Specified by:
  `getMetadata` in interface `IFeatureCollection`
Returns:
  the metadata for the table.

#### search

    ICursor search(ISearch search)

Queries the table and returns the features requested. The results of a search are obtained through the cursor as IFeature instances. The features may or may not be transient.

Querying a table involves specifying a search request. RDBMS-based interfaces specify a search request using the SQL language supported by the database vendor. A typical SQL-based query would look like:

`Select City, State, Population From Cities Where State = 'NY'`

Web services such as WFS specify searches using an XML syntax. Both of these examples provide some interface for defining the search to perform. Once defined, the results are conceptually identical (assuming comparable search definitions).

Querying an ITable uses an abstracted representation of a search request, identified by the `ISearch` interface. The ISearch interface is a marker interface that identifies an object that specifies a table search defined in terms of a "language". A language is a collection of symbols and objects along with rules (or semantics) applied to the symbols that communicates a desired action. For an ISearch, the language implementations communicate a type of query to perform on a table. There will be two query languages pre-defined. Those two languages are the MapInfo SQL language which is a richly expressive and powerful language and the filter language which is more simplistic and geared toward easier and wider acceptance among Data Provider implementations.

Tables indicate, through their metadata, which languages are supported. More specifically, each table indicates which capabilities of each language are supported. For the Filter language, the table's metadata indicates which filter types are supported and other capabilities such as sorting. Supplying a search for which the table does not support will result in an exception being thrown.

The parameters argument is a collection of name-value pairs that are to be used wherever the search refers to a bound variable. The relationship between the names and their meaning to the specified search is dependent upon the semantics of the language.

Parameters:
  `search` - Specifies the query to perform.
Throws:
  `UnsupportedOperationException` - if the specified search is not supported by this table or if the table is unable to execute the search.
See Also:
  `ISearch`, `ILanguage`

#### search

    ICursor search(ISearch search,
                   Map cursorProperties)

Queries the table and returns the features requested. The results of a search are obtained through the cursor as IFeature instances. The features may or may not be transient.

Querying a table involves specifying a search request. RDBMS-based interfaces specify a search request using the SQL language supported by the database vendor. A typical SQL-based query would look like:

`Select City, State, Population From Cities Where State = 'NY'`

Web services such as WFS specify searches using an XML syntax. Both of these examples provide some interface for defining the search to perform. Once defined, the results are conceptually identical (assuming comparable search definitions).

Querying an ITable uses an abstracted representation of a search request, identified by the `ISearch` interface. The ISearch interface is a marker interface that identifies an object that specifies a table search defined in terms of a "language". A language is a collection of symbols and objects along with rules (or semantics) applied to the symbols that communicates a desired action. For an ISearch, the language implementations communicate a type of query to perform on a table. There will be two query languages pre-defined. Those two languages are the MapInfo SQL language which is a richly expressive and powerful language and the filter language which is more simplistic and geared toward easier and wider acceptance among Data Provider implementations.

Tables indicate, through their metadata, which languages are supported. More specifically, each table indicates which capabilities of each language are supported. For the Filter language, the table's metadata indicates which filter types are supported and other capabilities such as sorting. Supplying a search for which the table does not support will result in an exception being thrown.

The parameters argument is a collection of name-value pairs that are to be used wherever the search refers to a bound variable. The relationship between the names and their meaning to the specified search is dependent upon the semantics of the language.

Parameters:
  `search` - Specifies the query to perform.
  `cursorProperties` - object of `Map` contains `CursorProperties` as key.
Throws:
  `UnsupportedOperationException` - if the specified search is not supported by this table or if the table is unable to execute the search.
See Also:
  `ISearch`, `ILanguage`

#### close

    void close()

Closes the table, closing and/or releasing any resources acquired.

When close is invoked on a table, there are a series of events that are involved with the closing process. The first event raised is a tableClosingRequest event. This event is cancellable and if a listener cancels the event, then the table will not be closed or altered in any way. While a user may wish to close a table, he/she may not realize that it is in use or shouldn't be closed. For example, there may be a layer in a map that is referencing the table. The map, or the user of the map, may wish to prevent a table from being closed. Another example would be if the table may contain pending edits. The application may want to ask the user if the edits should be saved or not by displaying a dialog box. By selecting Cancel in the dialog box, the close request would simply be canceled and no action would be taken.

If the close request is not canceled, then a second event would be raised indicating that the table will be closing. During that event, the table is still open and available for use. After that event is when the actual closing work would be performed. When complete, a third event is raised indicating that the table is closed and should no longer be used.

Any metadata, cursor, search processor, or transient feature obtained from the table should be assumed to be invalid and should not be accessed after the table is closed. Cursors and search processors should be closed according to specific rules as discussed under the ITableSearchProcessor interface documentation. If a call had been made to beginAccess without a corresponding call to endAccess, closing the table will implicitly call endAccess. Closing a table also will result in all event listeners being automatically unregistered. There is no need for a listener to be removed as part of the closing process.

After closing a table, no properties or methods may be called except for isClosed and close. Implementations must ensure that calls to close do not penalize a user for closing an already closed table.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Closeable`

#### isClosed

    boolean isClosed()

Indicates if the table has been closed. A table that has been closed will throw an exception if any property or method is accessed except for `isClosed` and `close`.

Returns:
  `true` if the table is closed; `false` otherwise.

#### add

    void add(IDataSourceTableListener listener)

Adds the specified `IDataSourceTableListener` to this `IDataSourceTable`. The listener will be notified of any events that happen to this `IDataSourceTable`. The same listener may be added more than once but will only be notified of an even once. If null is specified nothing happens.

Parameters:
  `listener` - The listener to add.

#### remove

    void remove(IDataSourceTableListener listener)

Removes the specified `IDataSourceTableListener` from this `IDataSourceTable`. If null is specified nothing happens.

Parameters:
  `listener` - The listener to remove.

#### getLegendMetadata

    LegendMetadata getLegendMetadata(String descriptionColumn,
                                     Envelope view)

Returns metadata about the legend. Metadata includes: unique geometry type to unique style and possible description.

Parameters:
  `descriptionColumn` - The column to get the description from. May be null.
  `view` - view to restrict the legend metadata generation to. If null then all features are used.
Returns:
  metadata about the legend.

#### insert

    IKey insert(IFeature feature)

Inserts the specified `IFeature` to the underlying table and returns the primary key of inserted features. Also determines whether table supports insertion or not. If the table is read-only then the operation fails.

Parameters:
  `feature` - The feature to be insert.
Returns:
  IKey as a primary key of the feature inserted.

#### insert

    List insert(IFeatureCollection featureCollection)

Inserts the specified `IFeatureCollection` to the underlying table and returns the list of primary keys of inserted features. Also determines whether table supports insertion or not. If the table is read-only then the operation fails.

Parameters:
  `featureCollection` - The collection of features to be insert.
Returns:
  list of IKey as a primary key of the collection of features inserted.

#### insert

    List insert(IFeatureCollection featureCollection,
                int commitInterval)

Inserts the specified `IFeatureCollection` to the underlying table and returns the list of primary keys of inserted features. Also determines whether table supports insertion or not. If the table is read-only then the operation fails.

Parameters:
  `featureCollection` - The collection of features to be insert.
  `commitInterval` - The maximum number of records to put in a batch insert. Larger collections will be broken up into multiple batches.
Returns:
  list of IKey as a primary key of the collection of features inserted.