# Package PIRL.Database

The PIRL Database package provides a simple interface for access to, and basic management of, databases.

See: Description

Interface Summary
Interface | Description
--- | ---
Data_Port | A Data_Port is the interface for accessing the content of a Database.
SQL_Listener | The SQL_Listener interface is used by a Data_Port to provide notifications of SQL statements being sent to the database server.

Class Summary
Class | Description
--- | ---
Connect_View | Connect_View provides a dialog used to interactively obtain the information needed to make a connection to a Database.
Data_Table | Data_Table manages a JTable for Database_View.
Data_View | Data_View manages access to Database_Views as mediated by its Configuration.
Database | A Database provides an implementation of a Data_Port to manage access to any database for which a driver is available.
Database_View | Database_View provides a View of a Database.
Fields_Map | A Fields_Map maps a list of field names in user specified order to the actual order of field names as returned from a database table query.
JDBC_Data_Port | A JDBC_Data_Port manages access to any JDBC database.
MySQL_Data_Port | Provides access to a MySQL database via a JDBC Data_Port.
PostgreSQL_Data_Port | Provides access to a PostgreSQL database via a JDBC_Data_Port.
Query_DB | Query_DB sends a SQL query to a Database and lists the results.
SQL | A modal dialog containing a text editor pane in which to specify an SQL command.
Update_DB | Update_DB updates an existing database table record or inserts a new record in a table.

Exception Summary
Exception | Description
--- | ---
Database_Exception | The excpetion thrown from the PIRL.Database package.

## Package PIRL.Database Description

The PIRL Database package provides a simple interface for access to, and basic management of, databases.

A database is considered to be composed of named data tables grouped into named catalogs. Each table is composed of records containing the same number of named data fields. A table might be thought of as a rectangular array of data where each column has a name and data type, and each row provides a set of specific data values for all the columns.

A database may be implemented as a simple text file or a complex Relational Database System managed by a server on a remote system. The Database user need not be concerned with how the database is implemented. The Database class provides a consistent Data_Port interface for all databases, so the user can focus on the data rather than the mechanics of the database implementation. Each Database object is backed by a specific type of Data_Port implementation that takes care of the requirements of its type of database. For example, a Data_Port class for accessing MySQL database servers is provided. This class is supported by a class that can be used with any database accessible via a JDBC driver; the MySQL_Data_Port class just provides the knowledge of how to Open access to a MySQL database using its specific driver. Support for other types of databases is very easy to provide.

A Configuration class is provided to manage parameters that are needed for access to specific databases. The parameters may be maintained in a text file ("Database.conf" by default) using the Parameter-Value Language syntax. In this way applications using the Database package do not need to know anything at all about particular databases; everything can be specified in the configuration file and grouped by database type as well as any other groupings that may be appropriate. This includes the names of JDBC drivers and their specific access parameters, catalog and table names, data field names mapped to generic application names, and default values for parameters that may or may not have specific parameters in some grouping. Of course the application may directly manage configurations as it sees fit. When a connection to a particular type of database is made, the Database class collects all the parameters relevant to it together in a separate Configuration associated with the Data_Port object, so the Data_Port automatically gets the correct parameters, and the application may know exactly which parameters are being used.

The Data_Port interface provides a complement of methods for the typical operations on a database: catalog (a.k.a. "database") creation and deletion; table creation, deletion and modification including adding, removing and renaming/retyping fields; field insertion, deletion and modification; and, of course, selection of data including simple joins. The methods provided are NOT meant to provide all the capabilities available with a database. They are meant to make it very easy to accomplish the vast majority of operations typically needed using a very simple interface. Methods to submit arbitrary SQL query statements (anything that returns table data from the database) and SQL update statements (anything that modifies the database) are provided for the advanced user. Also, a method to obtain direct access to a Connection object for the database is provided for the expert JDBC programmer.

See Also:
  `PIRL.PVL`