org.objectweb.cjdbc.controller.loadbalancer
Class AbstractLoadBalancer

java.lang.Object
  javax.management.StandardMBean
      org.objectweb.cjdbc.controller.jmx.AbstractStandardMBean
          org.objectweb.cjdbc.controller.loadbalancer.AbstractLoadBalancer

All Implemented Interfaces:

AbstractLoadBalancerMBean, javax.management.DynamicMBean, javax.management.NotificationBroadcaster, javax.management.NotificationEmitter, XmlComponent

Direct Known Subclasses:

ParallelDB, RAIDb0, RAIDb1, RAIDb2, SingleDB

public abstract class AbstractLoadBalancer

extends AbstractStandardMBean

implements XmlComponent, AbstractLoadBalancerMBean

The Request Load Balancer should implement the load balancing of the requests among the backend nodes.

The requests comes from the Request Controller and are sent to the Connection Managers.

Version:

1.0

Author:

Emmanuel Cecchet , Vadim Kassin , Jaco Swart , Jean-Bernard van Zuylen

Nested Class Summary

Nested classes inherited from class javax.management.StandardMBean

Field Summary

protected static Trace	logger
protected MacrosHandler	macroHandler
protected int	parsingGranularity
protected int	raidbLevel
protected java.util.LinkedList	totalOrderQueue Reference to distributed virtual database total order queue
protected VirtualDatabase	vdb

Fields inherited from class org.objectweb.cjdbc.controller.jmx.AbstractStandardMBean

Fields inherited from class javax.management.StandardMBean

Fields inherited from interface org.objectweb.cjdbc.common.xml.XmlComponent

DOCTYPE_CONTROLLER, DOCTYPE_DB, XML_VERSION

Constructor Summary

protected

AbstractLoadBalancer(VirtualDatabase vdb, int raidbLevel, int parsingGranularity) Generic constructor that sets some member variables and checks that backends are in the disabled state

Method Summary

abstract void	begin(TransactionMarkerMetaData tm) Begin a new transaction.
abstract void	commit(TransactionMarkerMetaData tm) Commit a transaction.
abstract void	disableBackend(DatabaseBackend db) Disable a backend without further check.
abstract void	enableBackend(DatabaseBackend db, boolean writeEnabled) Enable a backend without further check.
abstract ControllerResultSet	execReadOnlyReadStoredProcedure(StoredProcedure proc, MetadataCache metadataCache) Call a read-only stored procedure that returns a ResultSet.
abstract ControllerResultSet	execReadRequest(SelectRequest request, MetadataCache metadataCache) Perform a read request.
abstract ControllerResultSet	execReadStoredProcedure(StoredProcedure proc, MetadataCache metadataCache) Call a stored procedure that returns a ResultSet.
static ControllerResultSet	executeReadStoredProcedureOnBackend(StoredProcedure proc, DatabaseBackend backend, java.sql.Connection c, MetadataCache metadataCache) Execute a read stored procedure on the given backend.
static ControllerResultSet	executeSelectRequestOnBackend(SelectRequest request, DatabaseBackend backend, java.sql.Connection c, MetadataCache metadataCache) Execute a statement on a backend.
static int	executeUpdateRequestOnBackend(AbstractWriteRequest request, DatabaseBackend backend, java.sql.Connection c) Execute an update prepared statement on a backend.
static ControllerResultSet	executeUpdateRequestOnBackendWithKeys(AbstractWriteRequest request, DatabaseBackend backend, java.sql.Connection c, MetadataCache metadataCache) Execute an update prepared statement on a backend.
static int	executeWriteStoredProcedureOnBackend(StoredProcedure proc, DatabaseBackend backend, java.sql.Connection c) Execute a write stored procedure on the given backend.
abstract int	execWriteRequest(AbstractWriteRequest request) Perform a write request.
abstract ControllerResultSet	execWriteRequestWithKeys(AbstractWriteRequest request, MetadataCache metadataCache) Perform a write request and return a ResultSet containing the auto generated keys.
abstract int	execWriteStoredProcedure(StoredProcedure proc) Call a stored procedure that performs an update.
java.lang.String	getAssociatedString() Allow to retrieve internationalization description on mbeans as well
static java.sql.Connection	getConnectionAndBeginTransaction(DatabaseBackend backend, AbstractConnectionManager cm, long tid, int transactionIsolationLevel) Factorized code to start a transaction on a backend and to retrieve a connection on this backend
abstract java.lang.String	getInformation() Get information about the Request Load Balancer
abstract int	getNumberOfEnabledBackends() Get the number of currently enabled backends. 0 means that no backend is available.
int	getParsingGranularity() Get the needed query parsing granularity.
int	getRAIDbLevel() Returns the RAIDbLevel.
java.lang.String	getXml() Get xml formatted representation of this cjdbc component
abstract java.lang.String	getXmlImpl() Get information about the Request Load Balancer in xml
void	handleMacros(AbstractRequest request) Interprets the macros in the request (depending on the MacroHandler set for this class) and modify either the skeleton or the query itself.
abstract void	releaseSavepoint(TransactionMarkerMetaData tm, java.lang.String name) Release a savepoint from a transaction
void	removeHeadFromAndNotifyTotalOrderQueue() Remove the first entry of the total order queue and notify the queue so that the next queries can be scheduled.
abstract void	rollback(TransactionMarkerMetaData tm) Rollback a transaction.
abstract void	rollback(TransactionMarkerMetaData tm, java.lang.String savepointName) Rollback a transaction to a savepoint
void	setMacroHandler(MacrosHandler handler) This sets the macro handler for this load balancer.
void	setParsingGranularity(int parsingGranularity) Set the needed query parsing granularity.
void	setRAIDbLevel(int raidbLevel) Sets the RAIDbLevel.
abstract void	setSavepoint(TransactionMarkerMetaData tm, java.lang.String name) Set a savepoint to a transaction.
void	setWeight(java.lang.String name, int w) Associate a weight to a backend identified by its logical name.
boolean	waitForTotalOrder(java.lang.Object request, boolean errorIfNotFound) If we are executing in a distributed virtual database, we have to make sure that we post the query in the queue following the total order.

Methods inherited from class org.objectweb.cjdbc.controller.jmx.AbstractStandardMBean

addNotificationListener, getDescription, getDescription, getDescription, getDescription, getDescription, getDescription, getNotificationInfo, getParameterName, getParameterName, removeNotificationListener, removeNotificationListener, sendNotification

Methods inherited from class javax.management.StandardMBean

cacheMBeanInfo, getAttribute, getAttributes, getCachedMBeanInfo, getClassName, getConstructors, getDescription, getImpact, getImplementation, getImplementationClass, getMBeanInfo, getMBeanInterface, invoke, setAttribute, setAttributes, setImplementation

Methods inherited from class java.lang.Object

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

Field Detail

vdb

protected VirtualDatabase vdb

raidbLevel

protected int raidbLevel

parsingGranularity

protected int parsingGranularity

totalOrderQueue

protected java.util.LinkedList totalOrderQueue

Reference to distributed virtual database total order queue

logger

protected static Trace logger

macroHandler

protected MacrosHandler macroHandler

Constructor Detail

AbstractLoadBalancer

protected AbstractLoadBalancer(VirtualDatabase vdb,
                               int raidbLevel,
                               int parsingGranularity)
                        throws java.sql.SQLException,
                               javax.management.NotCompliantMBeanException

Generic constructor that sets some member variables and checks that backends are in the disabled state

Parameters:

vdb - The virtual database this load balancer belongs to

raidbLevel - The RAIDb level of this load balancer

parsingGranularity - The parsing granularity needed by this load balancer

Method Detail

getRAIDbLevel

public int getRAIDbLevel()

Returns the RAIDbLevel.

Specified by:

getRAIDbLevel in interface AbstractLoadBalancerMBean

Returns:

int the RAIDb level

setRAIDbLevel

public void setRAIDbLevel(int raidbLevel)

Sets the RAIDbLevel.

Specified by:

setRAIDbLevel in interface AbstractLoadBalancerMBean

Parameters:

raidbLevel - The RAIDb level to set

getParsingGranularity

public int getParsingGranularity()

Get the needed query parsing granularity.

Specified by:

getParsingGranularity in interface AbstractLoadBalancerMBean

Returns:

needed query parsing granularity

setParsingGranularity

public void setParsingGranularity(int parsingGranularity)

Set the needed query parsing granularity.

Specified by:

setParsingGranularity in interface AbstractLoadBalancerMBean

Parameters:

parsingGranularity - the granularity to set

handleMacros

public void handleMacros(AbstractRequest request)

Interprets the macros in the request (depending on the MacroHandler set for this class) and modify either the skeleton or the query itself. Note that the given object is directly modified.

Parameters:

request - the request to process

waitForTotalOrder

public boolean waitForTotalOrder(java.lang.Object request,
                                 boolean errorIfNotFound)

If we are executing in a distributed virtual database, we have to make sure that we post the query in the queue following the total order. This method does not remove the request from the total order queue. You have to call removeHeadFromAndNotifyTotalOrderQueue() to do so.

Parameters:

request - the request to wait for (can be any object but usually a DistributedRequest, Commit or Rollback)

errorIfNotFound - true if an error message should be logged if the request is not found in the total order queue

Returns:

true if the element was found and wait has succeeded, false otherwise

See Also:

removeHeadFromAndNotifyTotalOrderQueue()

removeHeadFromAndNotifyTotalOrderQueue

public void removeHeadFromAndNotifyTotalOrderQueue()

Remove the first entry of the total order queue and notify the queue so that the next queries can be scheduled.

execReadRequest

public abstract ControllerResultSet execReadRequest(SelectRequest request,
                                                    MetadataCache metadataCache)
                                             throws java.sql.SQLException

Perform a read request. It is up to the implementation to choose to which backend node(s) this request should be sent.

Parameters:

request - an SelectRequest

metadataCache - MetadataCache (null if none)

Returns:

the corresponding ControllerResultSet

Throws:

java.sql.SQLException - if an error occurs

execWriteRequest

public abstract int execWriteRequest(AbstractWriteRequest request)
                              throws AllBackendsFailedException,
                                     java.sql.SQLException

Perform a write request. This request should usually be broadcasted to all nodes.

Parameters:

request - an AbstractWriteRequest

Returns:

number of rows affected by the request

Throws:

AllBackendsFailedException - if all backends failed to execute the request

java.sql.SQLException - if an error occurs

execWriteRequestWithKeys

public abstract ControllerResultSet execWriteRequestWithKeys(AbstractWriteRequest request,
                                                             MetadataCache metadataCache)
                                                      throws AllBackendsFailedException,
                                                             java.sql.SQLException

Perform a write request and return a ResultSet containing the auto generated keys.

Parameters:

request - an AbstractWriteRequest

metadataCache - MetadataCache (null if none)

Returns:

auto generated keys

Throws:

AllBackendsFailedException - if all backends failed to execute the request

java.sql.SQLException - if an error occurs

execReadOnlyReadStoredProcedure

public abstract ControllerResultSet execReadOnlyReadStoredProcedure(StoredProcedure proc,
                                                                    MetadataCache metadataCache)
                                                             throws java.sql.SQLException

Call a read-only stored procedure that returns a ResultSet. The stored procedure will be executed by one node only.

Parameters:

proc - the stored procedure call

metadataCache - MetadataCache (null if none)

Returns:

a ControllerResultSet value

Throws:

java.sql.SQLException - if an error occurs

execReadStoredProcedure

public abstract ControllerResultSet execReadStoredProcedure(StoredProcedure proc,
                                                            MetadataCache metadataCache)
                                                     throws AllBackendsFailedException,
                                                            java.sql.SQLException

Call a stored procedure that returns a ResultSet. This stored procedure can possibly perform writes and will therefore be executed by all nodes.

Parameters:

proc - the stored procedure call

metadataCache - MetadataCache (null if none)

Returns:

a ControllerResultSet value

Throws:

AllBackendsFailedException - if all backends failed to execute the request

java.sql.SQLException - if an error occurs

execWriteStoredProcedure

public abstract int execWriteStoredProcedure(StoredProcedure proc)
                                      throws AllBackendsFailedException,
                                             java.sql.SQLException

Call a stored procedure that performs an update.

Parameters:

proc - the stored procedure call

Returns:

number of rows affected

Throws:

AllBackendsFailedException - if all backends failed to execute the request

java.sql.SQLException - if an error occurs

executeSelectRequestOnBackend

public static final ControllerResultSet executeSelectRequestOnBackend(SelectRequest request,
                                                                      DatabaseBackend backend,
                                                                      java.sql.Connection c,
                                                                      MetadataCache metadataCache)
                                                               throws java.sql.SQLException,
                                                                      BadConnectionException

Execute a statement on a backend. If the execution fails, the connection is checked for validity. If the connection was not valid, the query is automatically retried on a new connection.

Parameters:

request - the request to execute

backend - the backend on which the request is executed

c - connection used to create the statement

metadataCache - MetadataCache (null if none)

Returns:

the ControllerResultSet

Throws:

java.sql.SQLException - if an error occurs

BadConnectionException - if the connection was bad

executeUpdateRequestOnBackend

public static final int executeUpdateRequestOnBackend(AbstractWriteRequest request,
                                                      DatabaseBackend backend,
                                                      java.sql.Connection c)
                                               throws java.sql.SQLException,
                                                      BadConnectionException

Execute an update prepared statement on a backend. If the execution fails, the connection is checked for validity. If the connection was not valid, the query is automatically retried on a new connection.

Parameters:

request - the request to execute

backend - the backend on which the request is executed

c - connection used to create the statement

Returns:

int Number of rows effected

Throws:

java.sql.SQLException - if an error occurs

BadConnectionException - if the connection was bad

executeUpdateRequestOnBackendWithKeys

public static final ControllerResultSet executeUpdateRequestOnBackendWithKeys(AbstractWriteRequest request,
                                                                              DatabaseBackend backend,
                                                                              java.sql.Connection c,
                                                                              MetadataCache metadataCache)
                                                                       throws java.sql.SQLException,
                                                                              BadConnectionException

Execute an update prepared statement on a backend. If the execution fails, the connection is checked for validity. If the connection was not valid, the query is automatically retried on a new connection.

Parameters:

request - the request to execute

backend - the backend on which the request is executed

c - connection used to create the statement

metadataCache - MetadataCache (null if none)

Returns:

ControllerResultSet containing the auto-generated keys

Throws:

java.sql.SQLException - if an error occurs

BadConnectionException - if the connection was bad

executeReadStoredProcedureOnBackend

public static final ControllerResultSet executeReadStoredProcedureOnBackend(StoredProcedure proc,
                                                                            DatabaseBackend backend,
                                                                            java.sql.Connection c,
                                                                            MetadataCache metadataCache)
                                                                     throws java.sql.SQLException,
                                                                            BadConnectionException

Execute a read stored procedure on the given backend. The callable statement is setXXX if the driver has not processed the statement.

Parameters:

proc - the stored procedure to execute

backend - the backend on which to execute the stored procedure

c - the connection on which to execute the stored procedure

metadataCache - the matedatacache to build the ControllerResultSet

Returns:

the controllerResultSet

Throws:

java.sql.SQLException - if an error occurs

BadConnectionException - if the connection was bad

executeWriteStoredProcedureOnBackend

public static final int executeWriteStoredProcedureOnBackend(StoredProcedure proc,
                                                             DatabaseBackend backend,
                                                             java.sql.Connection c)
                                                      throws java.sql.SQLException,
                                                             BadConnectionException

Execute a write stored procedure on the given backend. The callable statement is setXXX if the driver has not processed the statement.

Parameters:

proc - the stored procedure to execute

backend - the backend on which to execute the stored procedure

c - the connection on which to execute the stored procedure

Returns:

the number of updated rows

Throws:

java.sql.SQLException - if an error occurs

BadConnectionException - if the connection was bad

begin

public abstract void begin(TransactionMarkerMetaData tm)
                    throws java.sql.SQLException

Begin a new transaction.

Parameters:

tm - The transaction marker metadata

Throws:

java.sql.SQLException - if an error occurs

commit

public abstract void commit(TransactionMarkerMetaData tm)
                     throws AllBackendsFailedException,
                            java.sql.SQLException

Commit a transaction.

Parameters:

tm - The transaction marker metadata

Throws:

AllBackendsFailedException - if all backends failed to execute the request

java.sql.SQLException - if an error occurs

rollback

public abstract void rollback(TransactionMarkerMetaData tm)
                       throws AllBackendsFailedException,
                              java.sql.SQLException

Rollback a transaction.

Parameters:

tm - The transaction marker metadata

Throws:

AllBackendsFailedException - if all backends failed to execute the request

java.sql.SQLException - if an error occurs

rollback

public abstract void rollback(TransactionMarkerMetaData tm,
                              java.lang.String savepointName)
                       throws AllBackendsFailedException,
                              java.sql.SQLException

Rollback a transaction to a savepoint

Parameters:

tm - The transaction marker metadata

savepointName - The name of the savepoint

Throws:

AllBackendsFailedException - if all backends failed to execute the request

java.sql.SQLException - if an error occurs

setSavepoint

public abstract void setSavepoint(TransactionMarkerMetaData tm,
                                  java.lang.String name)
                           throws AllBackendsFailedException,
                                  java.sql.SQLException

Set a savepoint to a transaction.

Parameters:

tm - The transaction marker metadata

name - The name of the new savepoint

Throws:

AllBackendsFailedException - if all backends failed to execute the request

java.sql.SQLException - if an error occurs

releaseSavepoint

public abstract void releaseSavepoint(TransactionMarkerMetaData tm,
                                      java.lang.String name)
                               throws AllBackendsFailedException,
                                      java.sql.SQLException

Release a savepoint from a transaction

Parameters:

tm - The transaction marker metadata

name - The name of the savepoint ro release

Throws:

AllBackendsFailedException - if all backends failed to execute the request

java.sql.SQLException - if an error occurs

getConnectionAndBeginTransaction

public static final java.sql.Connection getConnectionAndBeginTransaction(DatabaseBackend backend,
                                                                         AbstractConnectionManager cm,
                                                                         long tid,
                                                                         int transactionIsolationLevel)
                                                                  throws java.sql.SQLException,
                                                                         UnreachableBackendException

Factorized code to start a transaction on a backend and to retrieve a connection on this backend

Parameters:

backend - the backend needed to check valid connection against this backend test statement

cm - the connection manager to use to retrieve connections

tid - the id of the transaction to start

transactionIsolationLevel - transaction isolation level to use for a new transaction (does nothing if equals to Connection.DEFAULT_TRANSACTION_ISOLATION_LEVEL)

Returns:

a valid connection with a started transaction

Throws:

java.sql.SQLException - if the backend is valid but set autocommit cannot be set to false

UnreachableBackendException - if the backend is not reachable, ie not valid connection can be retrieved

See Also:

Connection.DEFAULT_TRANSACTION_ISOLATION_LEVEL

enableBackend

public abstract void enableBackend(DatabaseBackend db,
                                   boolean writeEnabled)
                            throws java.sql.SQLException

Enable a backend without further check. The backend is at least read enabled but could also be enabled for writes. Ask the corresponding connection manager to initialize the connections if needed.

Parameters:

db - The database backend to enable

writeEnabled - True if the backend must be enabled for writes

Throws:

java.sql.SQLException - if an error occurs

disableBackend

public abstract void disableBackend(DatabaseBackend db)
                             throws java.sql.SQLException

Disable a backend without further check. Ask the corresponding connection manager to finalize the connections if needed. This method should not be called directly but instead should access the RequestManager.disableBackeknd(...) method.

Parameters:

db - The database backend to disable

Throws:

java.sql.SQLException - if an error occurs

getNumberOfEnabledBackends

public abstract int getNumberOfEnabledBackends()

Get the number of currently enabled backends. 0 means that no backend is available.

Returns:

number of currently enabled backends

setWeight

public void setWeight(java.lang.String name,
                      int w)
               throws java.sql.SQLException

Associate a weight to a backend identified by its logical name.

Specified by:

setWeight in interface AbstractLoadBalancerMBean

Parameters:

name - the backend name

w - the weight

Throws:

java.sql.SQLException - if an error occurs

getInformation

public abstract java.lang.String getInformation()

Get information about the Request Load Balancer

Specified by:

getInformation in interface AbstractLoadBalancerMBean

Returns:

String containing information

getXmlImpl

public abstract java.lang.String getXmlImpl()

Get information about the Request Load Balancer in xml

Returns:

String containing information, xml formatted

setMacroHandler

public void setMacroHandler(MacrosHandler handler)

This sets the macro handler for this load balancer. Handling macros prevents different backends to generate different values when interpreting the macros which could result in data inconsitencies.

Parameters:

handler - MacrosHandler instance

getXml

public java.lang.String getXml()

Description copied from interface: XmlComponent

Get xml formatted representation of this cjdbc component

Specified by:

getXml in interface XmlComponent

Returns:

xml formatted fragment

See Also:

XmlComponent.getXml()

getAssociatedString

public java.lang.String getAssociatedString()

Description copied from class: AbstractStandardMBean

Allow to retrieve internationalization description on mbeans as well

Specified by:

getAssociatedString in class AbstractStandardMBean

Returns:

part of the key to look for in the translation file.

See Also:

AbstractStandardMBean.getAssociatedString()