activemq Lease Database Locker

http://activemq.apache.org/pluggable-storage-lockers.html

 

The Lease Database Locker was created to solve the shortcomings of the Database Locker. The Lease Database Locker does not open a long running JDBC transaction. Instead it lets the master broker acquire a lock that’s valid for a fixed (usually short) duration after which it expires. To retain the lock the master broker must periodically extend the lock’s lease before it expires. Simultaneously the slave broker checks periodically to see if the lease has expired. If, for whatever reason, the master broker fails to update its lease on the lock the slave will take ownership of the lock becoming the new master in the process. The leased lock can survive a DB replica failover.

Example:

<persistenceAdapter>
	<jdbcPersistenceAdapter dataDirectory="${activemq.data}" dataSource="#mysql-ds" lockKeepAlivePeriod="5000">
		<locker>
			<lease-database-locker lockAcquireSleepInterval="10000"/>
		</locker>
	</jdbcPersistenceAdapter>
</persistenceAdapter>

In order for this mechanism to work correctly, each broker in a master/slave(s) cluster must have a unique value for the brokerName attribute as defined on the <broker/> tag. Alternatively, use unique values for the leaseHolderId attribute on the <lease-database-locker/> tag as this value is used to create a lease lock definition.

The lease based lock is acquired by blocking at startup. It is then retained for a period whose duration (in ms) is given by the lockKeepAlivePeriod attribute. To retain the lock the master broker periodically extends its lease by lockAcquireSleepInterval milliseconds each time. In theory, therefore, the master broker is always (lockAcquireSleepInterval - lockKeepAlivePeriod) ahead of the slave broker with regard to the lease. It is imperative that lockAcquireSleepInterval > lockKeepAlivePeriod, to ensure the lease is always current. As of ActiveMQ 5.9.0 a warning message is logged if this condition is not met.

In the simplest case, the clocks between master and slave must be in sync for this solution to work properly. If the clocks cannot be in sync, the locker can use the system time from the database CURRENT TIME and adjust the timeouts in accordance with their local variance from the DB system time. If maxAllowableDiffFromDBTime is greater than zero the local periods will be adjusted by any delta that exceeds maxAllowableDiffFromDBTime.

It is important to know if the default rules your JDBC driver uses for converting TIME values are JDBC compliant. If you’re using MySQL, for example, the driver’s JDBC URL should contain useJDBCCompliantTimezoneShift=true to ensure that TIME value conversion is JDBC compliant. If not the locker could report a large time difference when it compares the retrieved lease expiration time against the current system time. Consult your JDBC driver’s documentation for more details.

As of ActiveMQ 5.9.0 the lease database locker can be used in conjunction with the KahaDB persistence adapter. However, this particular combination requires that the lease database locker element contains a <statements/> child element. In the example below the lockTableName is also configured, although doing so is not mandatory.