TerraLib and TerraView Wiki Page

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Last revision Both sides next revision
wiki:documentation:devguide:data_access_module [2016/01/14 07:17]
gribeiro [DataSource]
wiki:documentation:devguide:data_access_module [2016/01/19 16:23]
gribeiro [Design]
Line 16: Line 16:
 As one can see in the class diagram below, the Data Access module provides a basic framework for accessing data. As one can see in the class diagram below, the Data Access module provides a basic framework for accessing data.
  
-{{:wiki:devguide:dataaccess:​dataaccess_class_diagram.png|Data Access Class Diagram}}+{{:wiki:documentation:devguide:​dataaccess_class_diagram.png?640|Data Access Class Diagram}}
  
 It is designed towards extensibility and data interoperability,​ so you can easily extend it with your own data access implementation. It is designed towards extensibility and data interoperability,​ so you can easily extend it with your own data access implementation.
Line 30: Line 30:
  
 The yellow classes with the names in italic are abstract and must be implemented by data access drivers. Following we discuss each class in detail. See the [[http://​www.dpi.inpe.br/​terralib5/​codedocs_5.1.0/​d8/​d18/​group__dataaccess.html|Doxygen documentation for more details]]. The yellow classes with the names in italic are abstract and must be implemented by data access drivers. Following we discuss each class in detail. See the [[http://​www.dpi.inpe.br/​terralib5/​codedocs_5.1.0/​d8/​d18/​group__dataaccess.html|Doxygen documentation for more details]].
- 
 ===== DataSource ===== ===== DataSource =====
  
Line 47: Line 46:
 Each data source driver must have a unique identifier. This identifier is a string (//in capital letters//) with the data source type name and it is available through the method ''​getType''​. Examples of identifiers are: POSTGIS, OGR, GDAL, SQLITE, WFS, WCS, SHP, ACCESS. Each data source driver must have a unique identifier. This identifier is a string (//in capital letters//) with the data source type name and it is available through the method ''​getType''​. Examples of identifiers are: POSTGIS, OGR, GDAL, SQLITE, WFS, WCS, SHP, ACCESS.
  
-**REVER DAQUI PRA BAIXO** +A data source is also characterized by a set of parameters that can be used to set up an access channel to its underlying repository. This information is referred as the **//data source connection information//**. This information may be provided as an associative container (a set of key-value pairs) through the method ''​setConnectionInfo''​((TODO: we should use a plain connection string through the method ''​setConnectionStr''​)). The key-value pairs (kvp) may contain information about maximum number of accepted connections,​ user name and password required for establishing a connection, the url of a service or any other information needed by the data source to operate. The parameters are dependent on the data source driver. So, please, check the driver documentation for any additional information on the supported parameters.((When using a plain string, the information is encoded by a set of key-value pairs separated by an equal sign and each pair is separated by the ampersand (''&''​) and they must be URL encoded.)) For instance, in a PostGIS data source it is usual to use the following syntax:
-A data source is also characterized by a set of parameters that can be used to set up an access channel to its underlying repository. This information is referred as the data source connection information. This information may be provided as an associative container (a set of key-value pairs) through the method ''​setConnectionInfo'' ​or using a plain connection string through the method ''​setConnectionStr''​. The key-value pairs (kvp) may contain information about maximum number of accepted connections,​ user name and password required for establishing a connection, the url of a service or any other information needed by the data source to operate. The parameters are dependent on the data source driver. So, please, check the driver documentation for any additional information on the supported parameters. When using a plain string, the information is encoded by a set of key-value pairs separated by an equal sign and each pair is separated by the ampersand (''&''​) and they must be URL encoded. For instance, in a PostGIS data source it is usual to use the following syntax: +
- +
-<code cpp> +
-std::string connInfo = "​host=atlas.dpi.inpe.br&​port=5432&​dbname=mydb&​user=postgres&​password=mypasswd&​connect_timeout=20";​ +
-</​code>​ +
- +
-For a WFS data source available at ''​http://​www.dpi.inpe.br/​wfs''​ the connection string could be: +
-<code cpp> +
-std::string connInfo = "​service=http%3A%2F%2Fwww.dpi.inpe.br%2Fwfs";​ +
-</​code>​ +
- +
-The method ''​getConnectionInfo''​ returns an associative container (set of key-value pairs) with the connection information. The same information is also available in an URL encoded string through the method ''​getConnectionStr''​. +
- +
-Another useful information available in a data source is its known [[:​wiki:​designimplementation:​dataaccess#​common_data_source_capabilities|capabilities]]. The method ''​getCapabilities''​ returns an associative container with all information about what the data source can perform. Here you will find if the data source implementation supports primary keys, foreign keys, if it can be used in a thread environment and much more information. There is a list of common key-value pairs that every data access driver must supply although each implementation can provide additional information. +
- +
-A data source can be in one of the following states: //opened// or //closed//. In order to open a data source and makes it ready for use, one needs to provide the set of parameters required to set up the underlying access channel to the repository and then call one of the ''​open''​ methods. These methods will prepare the data source to work. If the implementation needs to open a connection to a database server, or to open a file or to get information from a Web Service, these methods can do this kind of job in order to prepare the data source to be in an operational mode. As one can see, you can use an associative container with the connection information or a string in a kvp notation. +
- +
-Once opened, the data source can be closed, releasing all the resources used by its internal communication channel. The close method closes any database connection, opened files or resources used by the data source. +
- +
-You can inquire the data source in order to know if it is opened or if it still valid (available for use) using the methods isOpened and isValid accordingly. +
- +
-The data stored in a data source may be discovered using the [[:​wiki:​designimplementation:​dataaccess#​datasourcetransactor|DataSourceTransactor]] and [[:​wiki:​designimplementation:​dataaccess#​datasourcecatalogloader|DataSourceCatalogLoader]]. The developer may also cache the description of datasets available in the data source in its catalog ([[:​wiki:​designimplementation:​dataaccess#​datasourcecatalog|DataSourceCatalog]]). The method ''​getCatalog''​ gives you the access to the cached data description in the data source. All drivers must assure a non-NULL data source catalog when the ''​getCatalog''​ method is called, although it can be empty. +
- +
-In order to interact with the data source you need a transactor. The ''​getTransactor''​ method returns an object that can execute transactions in the context of a data source. You can use this method to get an object that allows to retrieve a dataset, to insert data or to modify the schema of a dataset. You don't need to cache this kind of object because each driver in TerraLib already keeps a pool. So as soon as you finish using the transactor, destroy it. For more information see the [[:​wiki:​designimplementation:​dataaccess#​datasourcetransactor|DataSourceTransactor]] class. +
- +
-A data source repository can be created using the ''​create''​ class method. All you need is to inform the type of data source (providing its type name, for example: POSTGIS, ORACLE, WFS) and the creational information (a set of key-value pairs). Note that after creation the data source is in a "​closed state"​. The caller will have to decide when to open it. Not all drivers may perform this operation and it must be checked in the capabilities. +
- +
-As you can create a new data source, you can also drop an existing one, through the ''​drop''​ class method. This command will also remove the data source from the data source manager (if it is stored there). Not all drivers may perform this operation and it must be checked in the capabilities. +
- +
-For an in depth explanation,​ see [[http://​www.dpi.inpe.br/​terralib5/​codedocs_5.1.0/​de/​de5/​classte_1_1da_1_1DataSource.html|Doxygen documentation of this class]].+
  
 +For an in depth explanation,​ see the [[http://​www.dpi.inpe.br/​terralib5/​codedocs_5.1.0/​de/​de5/​classte_1_1da_1_1DataSource.html|Doxygen documentation of this class]].
 ===== DataSet ===== ===== DataSet =====
  
-For an in depth explanation,​ see [[http://​www.dpi.inpe.br/​terralib5/​codedocs_5.1.0/​dc/​d2c/​classte_1_1da_1_1DataSet.html|Doxygen documentation of this class]]. +For an in depth explanation,​ see the [[http://​www.dpi.inpe.br/​terralib5/​codedocs_5.1.0/​dc/​d2c/​classte_1_1da_1_1DataSet.html|Doxygen documentation of this class]].