org.apache.avalon.excalibur.datasource.cluster.DefaultIndexedDataSourceCluster Maven / Gradle / Ivy

Go to download
/* 
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.apache.avalon.excalibur.datasource.cluster;

import java.sql.Connection;
import java.sql.SQLException;

import org.apache.avalon.excalibur.datasource.NoValidConnectionException;

/**
 * The DefaultIndexedDataSourceCluster requires that the user implement their own method of
 *  selecting which DataSource in the cluster to use for each connection request.  Calls to
 *  getConnection() will throw an exception.  Components which make use of this class must call
 *  the getConnectionForIndex(int index) method instead.
 * 
 * The Configuration for a 2 database cluster is like this:
 *
 * 
 *   <datasources>
 *     <indexed-cluster name="mydb-cluster" size="2">
 *       <dbpool index="0">mydb-0</dbpool>
 *       <dbpool index="1">mydb-1</dbpool>
 *     </indexed-cluster>
 *   </datasources>
 *   <cluster-datasources>
 *     <jdbc name="mydb-0">
 *       <pool-controller min="1" max="10"/>
 *       <auto-commit>true</auto-commit>
 *       <driver>com.database.jdbc.JdbcDriver</driver>
 *       <dburl>jdbc:driver://host0/mydb</dburl>
 *       <user>username</user>
 *       <password>password</password>
 *     </jdbc>
 *     <jdbc name="mydb-1">
 *       <pool-controller min="1" max="10"/>
 *       <auto-commit>true</auto-commit>
 *       <driver>com.database.jdbc.JdbcDriver</driver>
 *       <dburl>jdbc:driver://host1/mydb</dburl>
 *       <user>username</user>
 *       <password>password</password>
 *     </jdbc>
 *   </cluster-datasources>
 * 
 *
 * With the following roles declaration:
 *
 *  *   <role name="org.apache.avalon.excalibur.datasource.DataSourceComponentSelector"
 *     shorthand="datasources"
 *     default-class="org.apache.avalon.excalibur.component.ExcaliburComponentSelector">
 *     <hint shorthand="jdbc" class="org.apache.avalon.excalibur.datasource.JdbcDataSource"/>
 *     <hint shorthand="j2ee" class="org.apache.avalon.excalibur.datasource.J2eeDataSource"/>
 *     <hint shorthand="indexed-cluster"
 *       class="org.apache.avalon.excalibur.datasource.cluster.DefaultIndexedDataSourceCluster"/>
 *   </role>
 *   <role name="org.apache.avalon.excalibur.datasource.DataSourceComponentClusterSelector"
 *       shorthand="cluster-datasources"
 *       default-class="org.apache.avalon.excalibur.component.ExcaliburComponentSelector">
 *     <hint shorthand="jdbc" class="org.apache.avalon.excalibur.datasource.JdbcDataSource"/>
 *     <hint shorthand="j2ee" class="org.apache.avalon.excalibur.datasource.J2eeDataSource"/>
 *   </role>
 * 
 *
 * An indexed-cluster definition enforces that the configuration specify a size.  This size must
 *  equal the number of datasources referenced as being members of the cluster.  Any datasource can
 *  be a member of the cluster.
 * 
 * The indexed-cluster can be obtained in the same manner as a non-clustered datasource.  The only
 *  difference is in how it is used.  The IndexedDataSourceCluster requires that the caller specify
 *  the index of the cluster member to use when requesting a connection.
 * 

 * The following code demonstrates a change that can be made to database enabled components so that
 *  they will be able to work with both IndexedDataSourceCluster DataSources and regular
 *  DataSources.
 * 

 * old:
 * 
 *   Connection connection = m_dataSource.getConnection();
 * 
 *
 * new:
 *  *   Connection connection;
 *   if ( m_dataSource instanceof IndexedDataSourceCluster )
 *   {
 *     connection = ((IndexedDataSourceCluster)m_dataSource).getConnectionForIndex( index );
 *   }
 *   else
 *   {
 *     connection = m_dataSource.getConnection();
 *   }
 * 
 * 
 * @avalon.component
 * @avalon.service type=org.apache.avalon.excalibur.datasource.DataSourceComponent
 * @avalon.service type=IndexedDataSourceCluster
 * @x-avalon.info name=index-db-cluster
 * @x-avalon.lifestyle type=singleton
 *
 * @author Avalon Development Team
 * @version CVS $Revision: 1.4 $ $Date: 2004/02/28 11:47:20 $
 * @since 4.1
 */
public class DefaultIndexedDataSourceCluster
    extends AbstractDataSourceCluster
    implements IndexedDataSourceCluster
{

    /*---------------------------------------------------------------
     * Constructors
     *-------------------------------------------------------------*/
    public DefaultIndexedDataSourceCluster()
    {
    }

    /*---------------------------------------------------------------
     * DataSourceComponent Methods
     *-------------------------------------------------------------*/
    /**
     * Not supported in this component.  Will throw a NoValidConnectionException.
     */
    public Connection getConnection() throws SQLException
    {
        throw new NoValidConnectionException(
            "getConnection() should not be called for a " + getClass().getName() + ".  " +
            "Please verify your configuration." );
    }

    /*---------------------------------------------------------------
     * IndexedDataSourceCluster Methods
     *-------------------------------------------------------------*/
    // public int getClusterSize()
    //   declared in AbstractDataSourceCluster

    // public Connection getConnectionForIndex( int index ) throws SQLException
    //   declared in AbstractDataSourceCluster
}