com.mapinfo.midev.dp.shape

## Class ShapeDataProvider

- java.lang.Object
- - com.mapinfo.midev.dp.shape.ShapeDataProvider

All Implemented Interfaces:
  IDataProvider, IFileDataProvider

    public final class ShapeDataProvider
    extends Object
    implements IFileDataProvider

A data provider to open ESRI Shape files. A shape file can be opened with the following code snippet:

    File file = new File("path/to/shapefile.shp");
    try (IDataSourceTable table = ShapeDataProvider.getInstance().openTable(file)) {
         // ...
    }

Once a table is opened, it can be queried with the `IDataSourceTable.search(com.mapinfo.midev.language.ISearch)` method:

    ISearch search = new FilterSearch(new String[]{QueryAttribute.WILDCARD},
            new EnvelopeFilter("geom", new Envelope(-90, -90, 90, 90,
                    SpatialInfo.create(CoordSysConstants.longLatWGS84))),
            null);
    ICursor cursor = table.search(search);
    while (cursor.hasNext()) {
        IFeature feature = cursor.next();
        // ...
    }

When using file base data (such as a shape 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();
    }

### Field Summary

Fields
`static String` `DEFAULT_FEATURE_GEOMETRY_COLUMN_NAME`
`static String` `PRIMARY_KEY_COLUMN_NAME`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`ShapeDataSourceDefinition` `createDataSourceDefinition(FileConnectionDefinition connectionDefinition)` Creates a new data source definition for the given file connection definition.
`static ShapeDataProvider` `getInstance()` Returns the singleton instance of this data provider.
`ShapeDataSource` `openDataSource(IDataSourceDefinition dataSourceDefinition)` Opens a new data source described by the given data source definition.
`IDataSourceTable` `openTable(File file)` Opens the given file as a data source table.
`IDataSourceTable` `openTable(File file, CoordSys coordSys, Charset charset)` Opens the given file as a data source table, using the provided coordinate system and character set to interpret spatial and text data.
`IDataSourceTable` `openTable(File file, CoordSys coordSys, Charset charset, boolean generateSpatialIndex, boolean isVolatile, List hints)` Opens the given file as a data source table, using the provided coordinate system and character set to interpret spatial and text data.

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

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

### Field Detail

#### DEFAULT_FEATURE_GEOMETRY_COLUMN_NAME

    public static final String DEFAULT_FEATURE_GEOMETRY_COLUMN_NAME

See Also:
  Constant Field Values

#### PRIMARY_KEY_COLUMN_NAME

    public static final String PRIMARY_KEY_COLUMN_NAME

See Also:
  Constant Field Values

### Method Detail

#### getInstance

    public static ShapeDataProvider getInstance()

Returns the singleton instance of this data provider.

#### createDataSourceDefinition

    public ShapeDataSourceDefinition createDataSourceDefinition(FileConnectionDefinition connectionDefinition)

Creates a new data source definition for the given file connection definition.

Specified by:
  `createDataSourceDefinition` in interface `IFileDataProvider`
Parameters:
  `connectionDefinition` - a file connection definition, which will be used to resolve the location of subsequently opened Shape files.

#### openDataSource

    public ShapeDataSource openDataSource(IDataSourceDefinition dataSourceDefinition)

Opens a new data source described by the given data source definition.

Specified by:
  `openDataSource` in interface `IDataProvider`
Parameters:
  `dataSourceDefinition` - an instance of `ShapeDataSourceDefinition`.
Returns:
  an `IDataSource` given the specified `IDataSourceDefinition`.

#### openTable

    public IDataSourceTable openTable(File file)

Opens the given file as a data source table.

Parameters:
  `file` - A file object pointing to a `*.shp` file on the file system.

#### openTable

    public IDataSourceTable openTable(File file,
                                      CoordSys coordSys,
                                      Charset charset)

Opens the given file as a data source table, using the provided coordinate system and character set to interpret spatial and text data.

Parameters:
  `file` - A file object pointing to a `*.shp` file on the file system.
  `coordSys` - the coordinate system to interpret spatial data in.
  `charset` - the character set to interpret texutal data in.
Returns:
  a new data source table.

#### openTable

    public IDataSourceTable openTable(File file,
                                      CoordSys coordSys,
                                      Charset charset,
                                      boolean generateSpatialIndex,
                                      boolean isVolatile,
                                      List hints)

Opens the given file as a data source table, using the provided coordinate system and character set to interpret spatial and text data. If `generateSpatialIndex` is `true` a quad-tree based spatial index will be generated alongside the opened `*.shp` file. The index will be generated on the first spatial search and saved in a `*.qix` file. If the `isVolatile` flag is set to `false`, the caller indicates that the underlying shape files cannot be modified by another process. In that case, the data provider will apply certain performance optimizations like the reuse of file descriptors in order to avoid repetitive opening and closing of files. The `hints` parameter can be used to provide a list of column hints to override the attribute metadata determined from the shape file.

Parameters:
  `file` - A file object pointing to a `*.shp` file on the file system.
  `coordSys` - the coordinate system to interpret spatial data in.
  `charset` - the character set to interpret textual data in.
  `generateSpatialIndex` - a boolean flag to indicate if a quad tree index should be created to improve the efficiency of spatial queries.
  `isVolatile` - a boolean flag to indicate if the opened shape file data can be changed by other processes. This is indicated by the value being set to `true`.
  `hints` - a list of column hints to override the default attribute metadata.
Returns:
  a new data source table.