com.jovial.db9010

Package com.jovial.db9010

Package Documentation

In order to fluently write code as described in the introduction, it's helpful to know something about how the API is structured. There are three main parts: The table and type definitions, the Database entry point, and the five statement types. In the following, these areas are illustrated with UML diagrams

Table and Type Definitions

The first step in writing a database system is normally to create table definitions. These classes support building up a representation of tables, which are made up of columns. Each column has a SQL type that gets mapped to and from Kotlin types. There are also query columns that contain expressions, like "SELECT COUNT(*)" and so forth.

The Database Entry Point

Next, we look at Database class, which is the main entry point to the system. It lets us make a JDBC connection, and various statement types. It has a series of methods that return different Builder objects for five types of SQL statement: SelectQuery, DeleteStatement, UpdateStatement, InsertStatement, and GenericStatement.

Statements

Finally, we consider the implementation of the five statement types. When a builder runs the client code, it give a reference to an object representing the statement. This can be used by the client code to set any needed parameters, and set and get row values.

Types

Column	A column in a select statement. This can be either a TableColumn or a QueryColumn. `abstract class Column<T>`
ColumnSetter	Superclass for statements that can set table columns: UpdateStatement and InsertStatement. This class maintains a list of the columns that have been set, and a code block to set each value. `abstract class ColumnSetter`
Database	Represents a database that we connect to using JDBC. This is the main entry point in this library for operations on a database. `class Database : AutoCloseable`
DeleteStatement	An SQL delete statement. See Database.deleteFrom. `class DeleteStatement : ParameterSetter`
GenericStatement	A generic SQL statement. The entire statement body is set by user code. See Database.statement. `class GenericStatement : ParameterSetter`
InsertStatement	An SQL insert statement. See Database.insertInto. `class InsertStatement : ColumnSetter`
Parameter	A parameter to an SQL statement. Parameters are represented as "?" in the text of a SQL statement. Before executing a statement, they can be set, using ParameterSetter.set, which sets one the underlying java.sql.PreparedStatement's parameter values. `class Parameter<T>`
ParameterSetter	Type for statements that can set parameters: DeleteStatement, UpdateStatement, SelectQuery and GenericStatement. This class maintains a map of the parameters that have been set to code blocks that set the parameters on a PreparedStatement, given the value index. `interface ParameterSetter`
QueryColumn	A query column with a SQL expression, like "COUNT(*)". QueryColumn values are read-only, and query columns cannot appear in a SelectQuery marked as for update. `class QueryColumn<T> : Column<T>`
ResultsHolder	Abstract superclass for objects that hold a ResultSet: SelectQuery and InsertStatement.Result. This class maintains a map that is used to look up a desired Column, and find it in a ResultSet. `abstract class ResultsHolder`
ReusableDeleteStatement	A delete statement that can be stored in a variable, and used multipe times. This saves the (small) overhead of a hash table lookup that's incurred when using Database.deleteFrom every time the same statement is run. `class ReusableDeleteStatement`
ReusableGenericStatement	A generic statement that can be stored in a variable, and used multipe times. This saves the (small) overhead of a hash table lookup that's incurred when using Database.statement every time the same statement is run. `class ReusableGenericStatement`
ReusableSelectQuery	A select query that can be stored in a variable, and used multipe times. This saves the (small) overhead of a hash table lookup that's incurred when using Database.select every time the same statement is run. `class ReusableSelectQuery`
SelectQuery	An SQL select query. See Database.select. `class SelectQuery : ResultsHolder, ParameterSetter`
StatementBuilder	Abstract superclass for the builder of all statement types. See also StatementBuilder.doNotCache `abstract class StatementBuilder<K>`
Table	Base class for Table definitions. A table is defined by making a singleton object that implements this type, with TableColumn members. Columns register themselves with their table, which is the first parameter to their constructor. `abstract class Table`
TableColumn	A column in a Table. The SQL type of the column is determined by sqlType, and the Kotlin type is determined by adapter. See Table `class TableColumn<T> : Column<T>`
TextStatementBuilder	Superclass for the builder of all statements that can have SQL strings added to the statement body. See TextStatementBuilder.plus. `abstract class TextStatementBuilder<K> : StatementBuilder<K>`
Types	`object Types`
UpdateStatement	An SQL update statement. See Database.update. `class UpdateStatement : ColumnSetter, ParameterSetter`
ValueAdapter	Interface describing an object that is used to adapt a PreparedStatement or a ResultSet by getting/setting a value of the appropriate type. `interface ValueAdapter<T>`
ValueAdapterNotNull	Abstract superclass for all value adapters of non-nullable types. This provides an implementation of a method that creates a value adapter of the corresponding nullable type. `abstract class ValueAdapterNotNull<T> : ValueAdapter<T>`

Functions

doNotCache

Method to set this builder so that it creates a statement that is not cached by the Database object. By default, statements are cached.

fun <T : StatementBuilder<*>> T.doNotCache(): T

plus

Add a SQL string to the statement being built.

operator fun <T : TextStatementBuilder<*>> T.plus(s: String): T

Add a parameter to the statement being built. The text "?" is added, and the parameter is recorded so that the parameter's index can be determined when the statement is run.

operator fun <T : TextStatementBuilder<*>> T.plus(p: Parameter<*>): T

Add a column to the statement being built. The column's string representation in SQL is added. See TextStatementBuilder.qualifyColumnNames

operator fun <T : TextStatementBuilder<*>> T.plus(c: Column<*>): T

Add a table to the statement being built. The table's name is appended.

operator fun <T : TextStatementBuilder<*>> T.plus(t: Table): T

qualifyColumnNames

Determine whether or not subsequent calls to TextStatementBuilder.plus with a TableColumn argument will use the qualified name (table_name.column_name), or just the column name. If this method is not called, the default behavior is to qualify names.

fun <T : TextStatementBuilder<*>> T.qualifyColumnNames(v: Boolean = true): T