com.mapinfo.midev.data

## Interface IDataSource

All Superinterfaces:
  Iterable

All Known Implementing Classes:
  NativeDataSource, ShapeDataSource

    public interface IDataSource
    extends Iterable

A datasource is an object that represents (or communicates with) a database management system, a web service, or some other engine or software API that exposes data and data access capabilities. Examples of datasources that would be exposed using the `IDataSource` interface would include an Oracle DBMS, a SQL Server DBMS, a WFS Server, a Microsoft Access database, etc.

Interacting with a datasource typically involves commands expressed in terms of a syntax that is unique to the datasource. For example, when accessing an Oracle database, commands that can be utilized are documented by Oracle and have some differences to commands that would be used when accessing SQL Server or DB2. All of those examples are variations of the SQL language with vendor-specific differences. Some datasources may be completely different and not SQL-based. For example, a WFS web service exposes an XML-based interface for comparable metadata, query, and editing commands.

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `close()` Closes the datasource, closing and/or releasing any resources acquired.
`IDataSourceDefinition` `getDefinition()` Returns the definition for the datasource.
`boolean` `isClosed()` Indicates if the datasource has been closed.
`IDataSourceTable` `openTable(ITableDefinition tableDefinition)` Creates an `IDataSourceTable` given the specified `ITableDefinition`.

### Methods inherited from interface java.lang.Iterable

`forEach, iterator, spliterator`

### Method Detail

#### getDefinition

    IDataSourceDefinition getDefinition()

Returns the definition for the datasource.

Identifying a datasource typically involves technology-specific or vendor-specific knowledge. For example, a WFS datasource would require the identification of the web service URL whereas an Oracle datasource would require a JDBC connection string. These differences are encapsulated in the data provider-specific implementations of the `IDataSourceDefinition` interface. Datasource definition objects are used by the data provider to instantiate a datasource instance.

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

Returns:
  the definition for the datasource.

#### close

    void close()

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

When close is invoked on a datasource, there are a series of events that are involved with the closing process. The first event raised is a datasourceClosingRequest event. This event is cancellable and if a listener cancels the event, then the datasource will not be closed or altered in any way. While a user may wish to close a datasource, he/she may not realize that it is in use or shouldn't be closed. For example, there may be an ITable that is referencing the datasource that cannot be closed for some reason.

If the close request is not cancelled, then a second event would be raised indicating that the datasource will be closing. During that event, the datasource 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 datasource is closed and should no longer be used.

Any tables, metadata browsers, cursors, command processors, or transient features obtained from the datasource or any table dependent on the datasource should be assumed to be invalid and should not be accessed after the datasource is closed. Tables, cursors, command processors, etc should be closed before the datasource is closed so that they can properly clean up and release resources.

After closing a datasource, 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 datasource. Closing a datasource 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.

#### isClosed

    boolean isClosed()

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

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

#### openTable

    IDataSourceTable openTable(ITableDefinition tableDefinition)

Creates an `IDataSourceTable` given the specified `ITableDefinition`.

Parameters:
  `tableDefinition` - the information that defines the `IDataSourceTable` to instantiate.
Returns:
  the new `IDataSourceTable` object that was opened.