com.mapinfo.midev.xml.mws

## Interface IMWSDataProviderHandler

    public interface IMWSDataProviderHandler

Interface for reading and writing a data source from and to a Named Table definition in the Named Resource Repository. A Named Table definition in the in-process model is composed of an `ITableDefinition` and an `IDataSourceDefinition`. These are represented in the MWS schema by the `<mxp:XDPDataSourceDefinition>` and `<mxp:XDPConnection>` elements, respectively.

Reading a Named Table Definition from the Repository

Spatial Server reads the contents of the `<mxp:ConnectionSet>` first. Each implementor of this interface is 'asked' to read a connection (i.e. `IDataSourceDefinition`) from the `<mxp:ConnectionSet>`. If the XML can be read then a `IDataSourceDefinition` (via a `Connection` instance) is returned; or `null` if it does not understand the XML construct it was given.

Next, the contents of the `<mxp:DataSourceDefinitionSet>` is read. Each implementor of this interface is 'asked' (via `IMWSDataProviderHandler.readDataSourceDefinition(com.mapinfo.midev.xml.read.IXmlReader, java.io.File, java.util.Map, com.mapinfo.midev.tabledepot.TableDepot)` to read a data source definition from the `<mxp:DataSourceDefinitionSet>`. If an implementation understands the constructs therein they are read and a `ITableDefinition` (via a `DataSourceDefinition`) is returned. If not `null` should be returned. A `java.util.Map` of connection name to `Connection` is also provided in case it is needed by the `ITableDefinition`.

Writing a Named Table Definition from the Repository

Writing follows the same pattern as reading. First the `IDataSourceDefinition`s are written to the `<mxp:ConnectionSet>`. Each implementor of this interface is 'asked' via `IMWSDataProviderHandler.writeConnection(com.mapinfo.midev.xml.write.IXmlWriter, Connection)` to write a specified `IDataSourceDefinition`. If an implementation understands the `IDataSourceDefinition` it is given it writes it to the `<mxp:ConnectionSet>` else `false` should be returned.

After writing all the `IDataSourceDefinition`s to the `<mxp:ConnectionSet>` the `ITableDefinition`s are written to the `<mxp:DataSourceDefinitionSet>`. Each implementation of this interface is 'asked' via `IMWSDataProviderHandler.writeDataSourceDefinition(com.mapinfo.midev.xml.write.IXmlWriter, DataSourceDefinition, java.io.File)` to write the specified `ITableDefinition`. If the implementation understands the specified `ITableDefinition` it writes it as an `<mxp:XDPDataSourceDefinition>` and `true` is returned; else `false` is returned.

Using the Specified IXmlReader and IXmlWriter

The specified `IXmlReader` and `IXmlWriter` may be used in any way. Implementations of this interface are given a copy of the XML 'stream' so changes to the reader or writer does not affect the rest of the system.

### Method Summary

All Methods Instance Methods Abstract Methods
`Connection` `readConnection(IXmlReader r)` Returns a `Connection` if the implementation read the contents of the `<mxp:XDPConnection>` element; or `null` if not.
`DataSourceDefinition` `readDataSourceDefinition(IXmlReader xml, File workingDir, Map connections, TableDepot tableDepot)` Returns a `DataSourceDefinition` or `null` if the implementation did not understand the contents of the <mxp:XDPDataSourceDefinition> element pointed to by the specified `IXmlReader`.
`boolean` `writeConnection(IXmlWriter w, Connection connection)` Returns `true` if the implementation wrote the specified `Connection` as an `<mxp:XDPConnection>` to the specified `IXmlWriter`; `false` if not.
`boolean` `writeDataSourceDefinition(IXmlWriter w, DataSourceDefinition mwsDataSourceDefinition, File workingDir)` Returns `true` if the implementation of this method understood how to write the specified `DataSourceDefinition`; `false` if not.

### Method Detail

#### readDataSourceDefinition

    DataSourceDefinition readDataSourceDefinition(IXmlReader xml,
                                                  File workingDir,
                                                  Map connections,
                                                  TableDepot tableDepot)

Returns a `DataSourceDefinition` or `null` if the implementation did not understand the contents of the <mxp:XDPDataSourceDefinition> element pointed to by the specified `IXmlReader`.

Parameters:
  `xml` - The IXmlReader that is pointing to the <mxp:XDPDataSourceDefinition>
  `workingDir` - the current working directory. Usually used for data sources that support relative paths.
  `connections` - a Map of <mxp:ConnectionName>s to Connections that were read from the <mxp:ConnectionSet>.
  `tableDepot` - a collection of ITables that have already be read from the .
Returns:
  a `DataSourceDefinition` or `null` if the implementation did not understand the contents of the <mxp:XDPDataSourceDefinition> element.

#### writeDataSourceDefinition

    boolean writeDataSourceDefinition(IXmlWriter w,
                                      DataSourceDefinition mwsDataSourceDefinition,
                                      File workingDir)

Returns `true` if the implementation of this method understood how to write the specified `DataSourceDefinition`; `false` if not.

Parameters:
  `w` - the `IXmlWriter` to use to write the desired XML elements to the Named Table definition.
  `mwsDataSourceDefinition` - the `DataSourceDefinition` to write to the Named Table definition.
  `workingDir` - the working directory. May be used to store relative paths but not recommended.
Returns:
  `true` if the implementation of this method understood how to write the specified `DataSourceDefinition`; `false` if not.

#### readConnection

    Connection readConnection(IXmlReader r)

Returns a `Connection` if the implementation read the contents of the `<mxp:XDPConnection>` element; or `null` if not.

Parameters:
  `r` - The `IXmlReader` that is pointing to the `<mxp:XDPConnection>`.
Returns:
  a `Connection` if the implementation understand and read the contents of the `<mxp:XDPConnection>` element; or `null` if not.

#### writeConnection

    boolean writeConnection(IXmlWriter w,
                            Connection connection)

Returns `true` if the implementation wrote the specified `Connection` as an `<mxp:XDPConnection>` to the specified `IXmlWriter`; `false` if not.

Parameters:
  `w` - the `IXmlWriter` to use to write the desired XML elements.
  `connection` - The `Connection` to write.
Returns:
  `true` if the implementation wrote the specified `Connection` as an `<mxp:XDPConnection>` to the specified `IXmlWriter`; `false` if not.