001/*
002 * HA-JDBC: High-Availability JDBC
003 * Copyright (C) 2012  Paul Ferraro
004 *
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Lesser General Public License as published by
007 * the Free Software Foundation, either version 3 of the License, or
008 * (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013 * GNU Lesser General Public License for more details.
014 *
015 * You should have received a copy of the GNU Lesser General Public License
016 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
017 */
018package net.sf.hajdbc;
019
020import java.sql.Connection;
021import java.sql.SQLException;
022
023import net.sf.hajdbc.codec.Decoder;
024
025/**
026 * @author  Paul Ferraro
027 * @version $Revision: 1536 $
028 * @param <Z> connection source (e.g. Driver, DataSource, etc.)
029 * @since   1.0
030 */
031public interface Database<Z> extends Comparable<Database<Z>>
032{
033        static final int ID_MAX_SIZE = 64;
034        
035        /**
036         * Returns the unique idenfier for this database
037         * @return a unique identifier
038         */
039        String getId();
040        
041        /**
042         * Returns the location of this database
043         * @return a location
044         */
045        String getLocation();
046        
047        /**
048         * Returns the relative "weight" of this cluster node.
049         * In general, when choosing a node to service read requests, a cluster will favor the node with the highest weight.
050         * A weight of 0 is somewhat special, depending on the type of balancer used by the cluster.
051         * In most cases, a weight of 0 means that this node will never service read requests unless it is the only node in the cluster.
052         * @return a positive integer
053         */
054        int getWeight();
055        
056        /**
057         * Indicates whether or not this database is local to the machine on which the JVM resides.
058         * @return true if local, false if remote
059         */
060        boolean isLocal();
061
062        String decodePassword(Decoder decoder) throws SQLException;
063        
064        /**
065         * Connects to the database using the specified connection factory.
066         * @param connectionSource a factory object for creating connections
067         * @param password a decoded password
068         * @return a database connection
069         * @throws SQLException if connection fails
070         */
071        Connection connect(Z connectionSource, String password) throws SQLException;
072        
073        /**
074         * Returns a connection source for this database.
075         * @return a connection source
076         * @throws IllegalArgumentException if connection source could not be created
077         */
078        Z getConnectionSource();
079        
080        boolean isDirty();
081        
082        void clean();
083        
084        boolean isActive();
085        
086        void setActive(boolean active);
087}