1/*
2   Copyright (c) 2013, 2021, Oracle and/or its affiliates.
3
4   This program is free software; you can redistribute it and/or modify
5   it under the terms of the GNU General Public License, version 2.0,
6   as published by the Free Software Foundation.
7
8   This program is also distributed with certain software (including
9   but not limited to OpenSSL) that is licensed under separate terms,
10   as designated in a particular file or component or in included license
11   documentation.  The authors of MySQL hereby grant you an additional
12   permission to link the program and your derivative works with the
13   separately licensed software that they have included with MySQL.
14
15   This program is distributed in the hope that it will be useful,
16   but WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18   GNU General Public License, version 2.0, for more details.
19
20   You should have received a copy of the GNU General Public License
21   along with this program; if not, write to the Free Software
22   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
23*/
24
25The goal of the API is to provide a productive environment for creating
26database applications; the goal of the SPI is to make it easy to provide
27those applications with some backend database adapter.  We mean to
28describe a simple set of abstractions and then to state that if you implement
29them as described, your adapter will work without surprises.
30
31Concepts
32--------
33
341. DBServiceProvider
35
36   DBServiceProvider is able to do a few crucial things.
37    * Supply the list of prerequisite modules required for the adapter to function
38    * Supply a set of default connection properties
39    * Given a set of connection properties, return a DBConnectionPool
40    * Given a set of properties, return a string factoryKey.
41      If two sets of properties result in the same factoryKey, then they can
42      use the same DBConnectionPool.
43
44
452. DBConnectionPool
46
47   DBConnectionPool is able to open and close a "master" connection (or pool
48   of connections) to the database.
49
50   Most importantly, DBConnectionPool implements getDBSession().  While the
51   DBConnectionPool itself represents a master connection for, say, a whole
52   web application, the DBSession represents an individual session for an
53   individual user's request.
54
55   DBConnectionPool is also responsible for some data dictionary operations.
56   It implements the two fundamental data dictionary lookups, listTables()
57   and getTableMetadata().  And, finally, it implements
58   registerTypeConverter(), which can establish a default conversion between
59   a SQL type anywhere in the database (such as BIGINT) and some JavaScript
60   class (such as a BigInteger utility class).
61
62
633. DBSession
64
65   A DBSession encapsulates a user's session and one single active database
66   transaction in that session.  DBSession implements a Builder pattern,
67   allowing various operations to be built and then executed.
68
69
704. DBOperation
71
72   DBOperation encapsulates a particular database operation, including the
73   details that define it (such as search keys and lock mode), its indexed
74   access path, its result, and any errors encountered during its execution.
75
76
775. DBTableHandler
78
79   DBTableHandler encapsulates the relationship between a DBTable -- which is a
80   metadata object obtained from the data dictionary -- and a class of domain
81   objects mapped to that table.
82
83