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.balancer;
019
020import java.util.Set;
021
022import net.sf.hajdbc.Database;
023import net.sf.hajdbc.invocation.Invoker;
024
025/**
026 * The set of active databases and a strategy for determining the next balancing target.
027 * 
028 * @author Paul Ferraro
029 *
030 * @param <Z> the database connection source
031 * @param <D> the database descriptor
032 */
033public interface Balancer<Z, D extends Database<Z>> extends Set<D>
034{
035        /**
036         * Returns the primary database.
037         * The database returned by this method should be consistent across nodes.
038         * @return the primary database
039         */
040        D primary();
041        
042        /**
043         * The non-primary databases.
044         * @return an iterable collection of databases.
045         */
046        Iterable<D> backups();
047        
048        /**
049         * Returns the next database from this balancer
050         * @return the next database from this balancer
051         */
052        D next();
053
054        /**
055         * Invoke the specified invoker on the specified object against the specified database, potentially informing the balancer.
056         * @param <T> invoker target object type
057         * @param <R> invoker return type
058         * @param <E> invoker exception type
059         * @param invoker
060         * @param database
061         * @param object
062         * @return the result of the invocation
063         * @throws E
064         */
065        <T, R, E extends Exception> R invoke(Invoker<Z, D, T, R, E> invoker, D database, T object) throws E;
066}