org.javalite.activeweb.AbstractDBConfig Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of activeweb Show documentation
Core functionality of the framework
The newest version!
/*
Copyright 2009-(CURRENT YEAR) Igor Polevoy

Licensed under the Apache License, Version 2.0 (the "License"); 
you may not use this file except in compliance with the License. 
You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0 

Unless required by applicable law or agreed to in writing, software 
distributed under the License is distributed on an "AS IS" BASIS, 
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
See the License for the specific language governing permissions and 
limitations under the License. 
*/
package org.javalite.activeweb;


import org.javalite.activejdbc.connection_config.DBConfiguration;

/**
 * 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.cj.jdbc.Driver", "jdbc:mysql://localhost/kitchensink_test", "root", "****");
 * 5.      environment("hudson").testing().jdbc("com.mysql.cj.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
 */
public abstract class AbstractDBConfig extends DBConfiguration implements InitConfig {

    /**
     * @param environment name of environment (corresponds to env var ACTIVE_ENV)
     * @return builder instance
     */
    public ConnectionBuilder environment(String environment) {
        return new ConnectionBuilder(environment);
    }

    /**
     * @param environment name of environment (corresponds to env var ACTIVE_ENV)
     * @param override not used. Any consecutive configuration will override a previous configuration if the following parameters are the same: DB name, environment, testing.
     *
     * @return builder instance
     */
    public ConnectionBuilder environment(String environment, boolean override) {
        return new ConnectionBuilder(environment);
    }

    /**
     * Configures multiple database connections from a single property file. Example content for such file:
     *
     *      development.driver=com.mysql.cj.jdbc.Driver
     development.username=john
     development.password=pwd
     development.url=jdbc:mysql://localhost/proj_dev

     test.driver=com.mysql.cj.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: {@link #environment(String)}
     *     All connections specified in a property file automatically assigned DB name "default". For more on
     *     database names see Database configuration
     * 
     *
     * @param file path to a file. Can be located on classpath, or on a file system. First searched on classpath,
     *             then on file system.
     */
    public void configFile(String file) {
      loadConfiguration(file);
    }
}