org.javalite.activeweb

Class AbstractDBConfig

java.lang.Object

org.javalite.activeweb.AppConfig

org.javalite.activeweb.AbstractDBConfig

public abstract class AbstractDBConfig
extends AppConfig

This class is designed to be sub-classed by an application level class called app.config.DbConfig. It is used to configure database connections for various environments and modes.

What is an environment?

An ActiveWeb environment is a computer where a project executes. In the process of software development there can be a number of environments where a project gets executed, such as development, continuous integration, QA, staging, production and more. The number of environments for ActiveWeb is custom for every project.

How to specify an environment

An environment is specified by an environment variable ACTIVE_ENV. Every computer where an ActiveWeb project gets executed, needs to have this variable specified. This value is used to determine which DB connections need to be initialized.

Default environment

In case an environment variable ACTIVE_ENV is not provided, the framework defaults to "development".

What is a mode?

ActiveWeb defines two modes of operation: "standard", which is also implicit, and "testing". Standard mode is used during regular run of the program, and testing used during the build when tests are executed. ActiveWeb promotes a style of development where one database used for testing, but a different one used under normal execution. When tests are executed, a "test" database is used, and when a project is run in a normal mode, a "development" database is used. Having a separate database for testing ensures safety of data in the development database.

Example of configuration

 1. public class DbConfig extends AbstractDBConfig {
 2.  public void init() {
 3.      environment("development").jndi("jdbc/kitchensink_development");
 4.      environment("development").testing().jdbc("com.mysql.jdbc.Driver", "jdbc:mysql://localhost/kitchensink_test", "root", "****");
 5.      environment("hudson").testing().jdbc("com.mysql.jdbc.Driver", "jdbc:mysql://172.30.64.31/kitchensink_test", "root", "****");
 6.      environment("production").jndi("jdbc/kitchensink_production");
 7.  }
 8.}
 

The code above is an example from Kitchensink project. Lets examine it line by line.

• Line 3: here we provide configuration for a "standard" mode in "development" environment. This DB connection will be used when the application is running under normal conditions in development environment.
• Line 4: This is a configuration of DB connection for "development" environment, but for "testing" mode. This connection will be used by unit and integration tests during the build.
• Line 5: This is a configuration of DB connection for "hudson" environment, but for "testing" mode. The "hudson" environment is a computer where this project is built by Hudson - the continuous integration server. Since Hudson computer is fully automated, and this project is not running there in "standard" mode, there is no standard configuration for Jenkins environment, just one for testing.
• Line 6: This is configuration similar to one on line 3, but for "production" environment.

Author:

Igor Polevoy

Constructor Summary

Constructors

Constructor and Description
AbstractDBConfig()

Method Summary

Methods

Modifier and Type	Method and Description
void	configFile(String file) Configures multiple database connections from a single property file.
ConnectionBuilder	environment(String environment)
ConnectionBuilder	environment(String environment, boolean override)

Methods inherited from class org.javalite.activeweb.AppConfig

completeInit, init

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractDBConfig

public AbstractDBConfig()

Method Detail

environment

public ConnectionBuilder environment(String environment)

Parameters:

environment - name of environment (corresponds to env var ACTIVE_ENV)

Returns:

builder instance

environment

public ConnectionBuilder environment(String environment,
                            boolean override)

Parameters:

environment - name of environment (corresponds to env var ACTIVE_ENV)

override - true to override any previous configuration for the same environment.

Returns:

builder instance

configFile

public void configFile(String file)

Configures multiple database connections from a single property file. Example content for such file:

     development.driver=com.mysql.jdbc.Driver
     development.username=john
     development.password=pwd
     development.url=jdbc:mysql://localhost/proj_dev

     test.driver=com.mysql.jdbc.Driver
     test.username=mary
     test.password=pwd1
     test.url=jdbc:mysql://localhost/test

     production.jndi=java:comp/env/jdbc/prod
 

Rules and limitations of using a file-based configuration:

• Only one database connection can be configured per environment (with the exception of development and test connections only in development environment)
• Currently additional database parameters need to be specified as a part of a database URL
• Database connection named "test" in the database configuration file is for "development" environment and is automatically marked for testing (will be used during tests)
• If this method of configuration is too limiting, it is possible to mix and match both configuration methods - file-based, as well as DSL: environment(String)
• All connections specified in a property file automatically assigned DB name "default". For more on database names see Database configuration

Parameters:

file - path to a file. Can be located on classpath, or on a file system. First searched on classpath, then on file system.