com.mapinfo.midev.dp.tab

## Class NativeDataProvider

- java.lang.Object
- - com.mapinfo.midev.dp.tab.NativeDataProvider

All Implemented Interfaces:
  IDataProvider, IFileDataProvider

    public final class NativeDataProvider
    extends Object
    implements IFileDataProvider

A data provider implementation for opening MapInfo Native Tables.

Below is an example of how to:

1. Use the NativeDataProvider in order to open a native (.tab) file.
2. Create a list of columns to be returned from the TAB file
3. Apply a filter that will be used to search the TAB file
4. Get features from the result set (i.e. ICursor).
5. Get columns (by name) from features
6. Close the cursor after iterating through all features.

Once a table is opened, it represents the client side representation of the data.

    //opens the TAB file
    File tabFile = new File("path/to/tabfile.tab");
    try (IDataSourceTable table = NativeDataProvider.getInstance().openTable(tabFile)) {
        // ...
    }

You could search a table and return all the data, or use a supported filter and return part of the data

    //creates the list of attributes (columns) to be selected from the TAB file
    List<QueryAttribute> queryAttributes = new ArrayList<>();
    queryAttributes.add(new QueryAttribute("State_name"));
    queryAttributes.add(new QueryAttribute("State"));
    queryAttributes.add(new QueryAttribute("Obj"));
    queryAttributes.add(new QueryAttribute("MapInfo_ID"));
    queryAttributes.add(new QueryAttribute("MI_Style"));
    SelectList selectList = new SelectList(queryAttributes);

    //creates the filter to be used when searching the table
    InListFilter inListFilter = new InListFilter("State", new AllType("NY"));

    //Only FilterSearch is supported
    FilterSearch filterSearch = new FilterSearch(selectList, inListFilter, null);

    //apply the filter and return an ICursor, which is a FeatureCollection
    ICursor cursor = table.search(filterSearch);

Iterate through each feature and get different attributes from it. In case you would like to reuse the feature, you have to make a copy of it, as the feature returned from a native table is transient. A transient feature is feature whose data is connected to the memory of the feature iterator. When the next feature is accessed, the same memory is reused, thus making the previous feature invalid.

    //iterate through features
    while (cursor.hasNext()) {
        // get a Feature
        IFeature feature = cursor.next();

        // check if a feature is transient
        boolean isFeatureTransient = feature.isTransient();

        // if a feature is transient and you would like to reuse it later on, then
        // you have to get a copy of that feature
        IFeature featureCopy = feature.getCopy();

        // get information from the feature
        // geometry column
        IFeatureGeometry geometry = feature.getFeatureGeometry("Obj");
        // State_name column
        String stateName = feature.getString("State_name");
        // Primary Key column
        String key = feature.getString("MapInfo_ID");
        // Style column
        IStyle style = feature.getStyle("MI_Style");
    }

When using file base data (such as a TAB file), the cursor may hold on to resources (i.e. file locks, file readers, ...) It is good practice to always dispose of a feature iterator (including implementations of ICursor) to indicate that it may release its resources.

    try {
        // ...
    } finally {
        cursor.dispose();
    }

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`NativeDataSourceDefinition` `createDataSourceDefinition(FileConnectionDefinition connectionDefinition)` Create a data source definition specific to the data source.
`static NativeDataProvider` `getInstance()` Get an instance of this data provider.
`NativeDataSource` `openDataSource(IDataSourceDefinition dataSourceDefinition)` Returns an `IDataSource` given the specified `IDataSourceDefinition`.
`IDataSourceTable` `openTable(File file)` Convenience method for opening a TAB file as a Table.
`IDataSourceTable` `openTable(File file, boolean isVolatile)` Convenience method for opening a TAB file as a Table.
`IDataSourceTable` `openTable(File file, boolean isVolatile, boolean isReadOnly)` Convenience method for opening a TAB file as a Table.
`IDataSourceTable` `openTable(File dir, String name)` Convenience method for opening a TAB file as a Table.
`IDataSourceTable` `openTable(File dir, String name, boolean isVolatile)` Convenience method for opening a TAB file as a Table.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Method Detail

#### getInstance

    public static NativeDataProvider getInstance()

Get an instance of this data provider.

#### openDataSource

    public NativeDataSource openDataSource(IDataSourceDefinition dataSourceDefinition)

Description copied from interface: `IDataProvider`
Returns an `IDataSource` given the specified `IDataSourceDefinition`. The `IDataSource` that is returned is implementation specific. For example, some implementations will cache `IDataSource`s and return the same instance for `IDataSourceDefinition`s that are equal while other may not.

Specified by:
  `openDataSource` in interface `IDataProvider`
Parameters:
  `dataSourceDefinition` - the `IDataSourceDefinition` used to create/open an `IDataSource`.
Returns:
  an `IDataSource` given the specified `IDataSourceDefinition`.

#### openTable

    public IDataSourceTable openTable(File dir,
                                      String name)

Convenience method for opening a TAB file as a Table.

Parameters:
  `dir` - Directory where the .TAB file resides
  `name` - The name of the file.

#### openTable

    public IDataSourceTable openTable(File dir,
                                      String name,
                                      boolean isVolatile)

Convenience method for opening a TAB file as a Table.

Parameters:
  `dir` - Directory where the .TAB file resides
  `name` - The name of the file.
  `isVolatile` - if true then it can be reloaded if the table is modified.

#### openTable

    public IDataSourceTable openTable(File file)

Convenience method for opening a TAB file as a Table.

Parameters:
  `file` - The .TAB file to open as a table.

#### openTable

    public IDataSourceTable openTable(File file,
                                      boolean isVolatile)

Convenience method for opening a TAB file as a Table.

Parameters:
  `file` - The .TAB file to open as a table.
  `isVolatile` - if true then it can be reloaded if the table is modified.

#### openTable

    public IDataSourceTable openTable(File file,
                                      boolean isVolatile,
                                      boolean isReadOnly)

Convenience method for opening a TAB file as a Table.

Parameters:
  `file` - The .TAB file to open as a table.
  `isVolatile` - if true then it can be reloaded if the table is modified.
  `isReadOnly` - if true then insert operation is not allowed.

#### createDataSourceDefinition

    public NativeDataSourceDefinition createDataSourceDefinition(FileConnectionDefinition connectionDefinition)

Description copied from interface: `IFileDataProvider`
Create a data source definition specific to the data source.

Specified by:
  `createDataSourceDefinition` in interface `IFileDataProvider`
Parameters:
  `connectionDefinition` - The connection definition for the data source definition.