|
Version 4.10.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface ConnectionSource
Return a Connection
to a database, using a policy defined by the application.
See BuildImpl
for important information on how this item is configured.
BuildImpl.forConnectionSource()
returns the configured implementation of this interface.
Here is an example implementation, taken from the WEB4J example application.
There are many alternatives for creating or accessing database connections. The application programmer can use any technique whatsoever to implement this interface. For example, an implementation may :
Connection
directly, using the database driver. (Some modern
drivers have connection pooling built directly into the driver.)
The design of this interface is slightly skewed towards applications that use more than one database. If only one database is used in an application, then this interface is simply implemented 'as if' there were more than one. In practice, this should be only a minor nuisance. In addition, if a single-database application is extended to use more than one database, the changes will be absorbed naturally by the existing implementation.
If no database is used at all, then getDatabaseNames()
returns an emtpy Set.
See SqlId
for related information.
Method Summary | |
---|---|
Connection |
getConnection()
Return a Connection to the default database. |
Connection |
getConnection(String aDatabaseName)
Return a Connection for a specified database (default or non-default). |
Set<String> |
getDatabaseNames()
Return the database names accepted by getConnection(String) . |
void |
init(Map<String,String> aConfig)
Read in any necessary configuration parameters. |
Method Detail |
---|
void init(Map<String,String> aConfig)
This method is called by the framework early during startup processing. If your implementation of this interface does not use any sort of config information, then it can simply ignore the given Map parameter.
In the context of a web application, the given Map is populated with the servlet's init-param settings in web.xml.
Set<String> getDatabaseNames()
getConnection(String)
.
Return a Set with one or more entries. Each entry must have content. If your application does not use a database at all, then you must return an empty Set.
Connection getConnection() throws DAOException
Connection
to the default database.
The default database is selected by the application programmer as representing the principal or main database in the application, against which the majority of SQL statements are executed. (For most applications, this choice will be obvious.) In .sql files, SQL statements against the default database do not need an extra qualifier in their identifiers, while those against a non-default database do need an extra qualifier.
Implementations must translate any exceptions into a DAOException
.
Examples of exceptions that may need translation are SQLException
and javax.naming.NamingException.
DAOException
Connection getConnection(String aDatabaseName) throws DAOException
Connection
for a specified database (default or non-default).
The getConnection()
method is intended for the "default" or
principal database used in the application, while this method is
intended for all other databases (but may be used for the default as well).
See SqlId
for related information.
Here, aDatabaseName is a prefix used
in .sql files as a qualifer to a SQL statement identifier.
For example, in an .sql file, the SQL statement identifier:
The values taken by aDatabaseName are those returned by getDatabaseNames()
.
They may be chosen by the application programmer in any desired way, to clarify the SQL
statement identifiers appearing in the .sql file(s).
Typically, an implementation of this interface will internally map these database
identifiers into specific connection strings, such as
'java:comp/env/jdbc/blah' (or whatever is required).
Implementations must translate any exceptions into a DAOException
.
Examples of exceptions that may need translation are SQLException
and javax.naming.NamingException.
DAOException
|
Version 4.10.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |