org.exist.storage
Class BrokerPool

java.lang.Object
  org.exist.storage.BrokerPool

public class BrokerPool

extends java.lang.Object

This class controls all available instances of the database. Use it to configure, start and stop database instances. You may have multiple instances defined, each using its own configuration. To define multiple instances, pass an identification string to configure(String, int, int, Configuration) and use getInstance(String) to retrieve an instance.

Author:

Wolfgang Meier , Pierrick Brihaye

Field Summary

protected CollectionCache	collectionCache The cache in which the database instance's collections are stored.
protected Configuration	conf The configuration object for the database instance
int	DEFAULT_COLLECTION_BUFFER_SIZE
static java.lang.String	DEFAULT_INSTANCE_NAME The name of a default database instance for those who are too lazy to provide parameters ;-).
long	DEFAULT_MAX_SHUTDOWN_WAIT
long	DEFAULT_SYNCH_PERIOD
static boolean	FORCE_CORRUPTION For testing only: triggers a database corruption by disabling the page caches.
protected XMLReaderPool	xmlReaderPool The pool in which the database instance's readers are stored.

Constructor Summary

BrokerPool(java.lang.String instanceName, int minBrokers, int maxBrokers, Configuration conf)
Creates and configures the database instance.

Method Summary

int	active() Returns the number of brokers currently serving requests for the database instance.
int	available() Returns the number of inactive brokers for the database instance.
protected boolean	canReadDataDir(Configuration conf)
static void	configure(int minBrokers, int maxBrokers, Configuration config) Creates and configures a default database instance and adds it to the pool.
static void	configure(java.lang.String instanceName, int minBrokers, int maxBrokers, Configuration config) Creates and configures a database instance and adds it to the pool.
protected DBBroker	createBroker() Creates an inactive broker for the database instance.
DBBroker	get() Returns an active broker for the database instance.
DBBroker	get(User user) Returns an active broker for the database instance and sets its current user.
CacheManager	getCacheManager() Returns a cache in which the database instance's may store items.
CollectionCache	getCollectionsCache() Returns a cache in which the database instance's collections are stored.
Configuration	getConfiguration() Returns the configuration object for the database instance.
CollectionConfigurationManager	getConfigurationManager() Returns a manager for accessing the database instance's collection configuration files.
Lock	getGlobalUpdateLock() Returns the global update lock for the database instance.
java.lang.String	getId() Returns the database instance's name.
static BrokerPool	getInstance() Returns a broker pool for the default database instance.
static BrokerPool	getInstance(java.lang.String instanceName) Returns a broker pool for a database instance.
static java.util.Iterator	getInstances() Returns an iterator over the database instances.
int	getMax() Returns the maximal number of brokers for the database instance.
NotificationService	getNotificationService()
XMLReaderPool	getParserPool() Returns a pool in which the database instance's readers are stored.
SecurityManager	getSecurityManager() Returns the database instance's security manager
SyncDaemon	getSyncDaemon() Returns the daemon which periodically executes system tasks, including cache synchronization, on the database instance.
TransactionManager	getTransactionManager()
XQueryMonitor	getXQueryMonitor() Returns a monitor in which the database instance's running XQueries are managed.
XQueryPool	getXQueryPool() Returns a pool in which the database instance's compiled XQueries are stored.
protected void	initialize() Initializes the database instance.
static boolean	isConfigured() Returns whether or not the default database instance is configured.
static boolean	isConfigured(java.lang.String id) Returns whether or not a database instance is configured.
boolean	isInitializing() Whether or not the database instance is being initialized.
boolean	isInstanceConfigured() Returns whether the database instance has been configured.
boolean	isTransactional() Returns whether transactions can be handled by the database instance.
protected SecurityManager	newSecurityManager()
void	registerShutdownListener(ShutdownListener listener)
void	release(DBBroker broker) Releases a broker for the database instance.
void	reloadSecurityManager(DBBroker broker) Reloads the security manager of the database instance.
static void	setRegisterShutdownHook(boolean register) Whether of not the JVM should run the shutdown thread.
void	shutdown() Shuts downs the database instance
void	shutdown(boolean killed) Shuts downs the database instance
static void	stop() Stops the default database instance.
static void	stop(java.lang.String id) Stops the given database instance.
static void	stopAll(boolean killed) Stops all the database instances.
void	triggerCheckpoint()
void	triggerSync(int syncEvent) Schedules a cache synchronization for the database instance.
void	triggerSystemTask(SystemTask task) Schedules a system maintenance task for the database instance.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_INSTANCE_NAME

public static final java.lang.String DEFAULT_INSTANCE_NAME

The name of a default database instance for those who are too lazy to provide parameters ;-).

See Also:

Constant Field Values

FORCE_CORRUPTION

public static boolean FORCE_CORRUPTION

For testing only: triggers a database corruption by disabling the page caches. The effect is similar to a sudden power loss or the jvm being killed. The flag is used by some junit tests to test the recovery process.

DEFAULT_SYNCH_PERIOD

public final long DEFAULT_SYNCH_PERIOD

See Also:

Constant Field Values

DEFAULT_MAX_SHUTDOWN_WAIT

public final long DEFAULT_MAX_SHUTDOWN_WAIT

See Also:

Constant Field Values

DEFAULT_COLLECTION_BUFFER_SIZE

public final int DEFAULT_COLLECTION_BUFFER_SIZE

See Also:

Constant Field Values

conf

protected Configuration conf

The configuration object for the database instance

collectionCache

protected CollectionCache collectionCache

The cache in which the database instance's collections are stored.

xmlReaderPool

protected XMLReaderPool xmlReaderPool

The pool in which the database instance's readers are stored.

Constructor Detail

BrokerPool

public BrokerPool(java.lang.String instanceName,
                  int minBrokers,
                  int maxBrokers,
                  Configuration conf)
           throws EXistException

Creates and configures the database instance.

Parameters:

instanceName - A name for the database instance.

minBrokers - The minimum number of concurrent brokers for handling requests on the database instance.

maxBrokers - The maximum number of concurrent brokers for handling requests on the database instance.

conf - The configuration object for the database instance

Throws:

EXistException - If the initialization fails.

Method Detail

setRegisterShutdownHook

public static final void setRegisterShutdownHook(boolean register)

Whether of not the JVM should run the shutdown thread.

Parameters:

register - true if the JVM should run the thread

configure

public static final void configure(int minBrokers,
                                   int maxBrokers,
                                   Configuration config)
                            throws EXistException

Creates and configures a default database instance and adds it to the pool. Call this before calling {link #getInstance()}. If a default database instance already exists, the new configuration is ignored.

Parameters:

minBrokers - The minimum number of concurrent brokers for handling requests on the database instance.

maxBrokers - The maximum number of concurrent brokers for handling requests on the database instance.

config - The configuration object for the database instance

Throws:

EXistException

EXistException - If the initialization fails.

configure

public static final void configure(java.lang.String instanceName,
                                   int minBrokers,
                                   int maxBrokers,
                                   Configuration config)
                            throws EXistException

Creates and configures a database instance and adds it to the pool. Call this before calling {link #getInstance()}. If a database instance with the same name already exists, the new configuration is ignored.

Parameters:

instanceName - A unique name for the database instance. It is possible to have more than one database instance (with different configurations for example).

minBrokers - The minimum number of concurrent brokers for handling requests on the database instance.

maxBrokers - The maximum number of concurrent brokers for handling requests on the database instance.

config - The configuration object for the database instance

Throws:

EXistException - If the initialization fails.

isConfigured

public static final boolean isConfigured()

Returns whether or not the default database instance is configured.

Returns:

true if it is configured

isConfigured

public static final boolean isConfigured(java.lang.String id)

Returns whether or not a database instance is configured.

Parameters:

id - The name of the database instance

Returns:

true if it is configured

getInstance

public static final BrokerPool getInstance()
                                    throws EXistException

Returns a broker pool for the default database instance.

Returns:

The broker pool

Throws:

EXistException - If the database instance is not available (not created, stopped or not configured)

getInstance

public static final BrokerPool getInstance(java.lang.String instanceName)
                                    throws EXistException

Returns a broker pool for a database instance.

Parameters:

instanceName - The name of the database instance

Returns:

The broker pool

Throws:

EXistException - If the instance is not available (not created, stopped or not configured)

getInstances

public static final java.util.Iterator getInstances()

Returns an iterator over the database instances.

Returns:

The iterator

stop

public static final void stop()
                       throws EXistException

Stops the default database instance. After calling this method, it is no longer configured.

Throws:

EXistException - If the default database instance is not available (not created, stopped or not configured)

stop

public static final void stop(java.lang.String id)
                       throws EXistException

Stops the given database instance. After calling this method, it is no longer configured.

Parameters:

id - The name of the database instance

Throws:

EXistException - If the database instance is not available (not created, stopped or not configured)

stopAll

public static final void stopAll(boolean killed)

Stops all the database instances. After calling this method, the database instances are no longer configured.

Parameters:

killed - true when invoked by an exiting JVM

canReadDataDir

protected boolean canReadDataDir(Configuration conf)
                          throws EXistException

Throws:

EXistException

newSecurityManager

protected SecurityManager newSecurityManager()

initialize

protected void initialize()
                   throws EXistException

Initializes the database instance.

Throws:

EXistException

isInitializing

public boolean isInitializing()

Whether or not the database instance is being initialized.

Returns:

true is the database instance is being initialized

getId

public java.lang.String getId()

Returns the database instance's name.

Returns:

The id

active

public int active()

Returns the number of brokers currently serving requests for the database instance.

Returns:

The brokers count

available

public int available()

Returns the number of inactive brokers for the database instance.

Returns:

The brokers count

getMax

public int getMax()

Returns the maximal number of brokers for the database instance.

Returns:

The brokers count

isInstanceConfigured

public final boolean isInstanceConfigured()

Returns whether the database instance has been configured.

Returns:

true if the datbase instance is configured

getConfiguration

public Configuration getConfiguration()

Returns the configuration object for the database instance.

Returns:

The configuration

registerShutdownListener

public void registerShutdownListener(ShutdownListener listener)

getSecurityManager

public SecurityManager getSecurityManager()

Returns the database instance's security manager

Returns:

The security manager

getSyncDaemon

public SyncDaemon getSyncDaemon()

Returns the daemon which periodically executes system tasks, including cache synchronization, on the database instance.

Returns:

The daemon

getNotificationService

public NotificationService getNotificationService()

isTransactional

public boolean isTransactional()

Returns whether transactions can be handled by the database instance.

Returns:

true if transactions can be handled

getTransactionManager

public TransactionManager getTransactionManager()

getConfigurationManager

public CollectionConfigurationManager getConfigurationManager()

Returns a manager for accessing the database instance's collection configuration files.

Returns:

The manager

getCollectionsCache

public CollectionCache getCollectionsCache()

Returns a cache in which the database instance's collections are stored.

Returns:

The cache

getCacheManager

public CacheManager getCacheManager()

Returns a cache in which the database instance's may store items.

Returns:

The cache

getXQueryPool

public XQueryPool getXQueryPool()

Returns a pool in which the database instance's compiled XQueries are stored.

Returns:

The pool

getXQueryMonitor

public XQueryMonitor getXQueryMonitor()

Returns a monitor in which the database instance's running XQueries are managed.

Returns:

The monitor

getParserPool

public XMLReaderPool getParserPool()

Returns a pool in which the database instance's readers are stored.

Returns:

The pool

getGlobalUpdateLock

public Lock getGlobalUpdateLock()

Returns the global update lock for the database instance. This lock is used by XUpdate operations to avoid that concurrent XUpdate requests modify the database until all document locks have been correctly set.

Returns:

The global lock

createBroker

protected DBBroker createBroker()
                         throws EXistException

Creates an inactive broker for the database instance.

Returns:

The broker

Throws:

EXistException

get

public DBBroker get()
             throws EXistException

Returns an active broker for the database instance.

Returns:

The broker

Throws:

EXistException - If the instance is not available (stopped or not configured)

get

public DBBroker get(User user)
             throws EXistException

Returns an active broker for the database instance and sets its current user.

Parameters:

user - The user

Returns:

The broker

Throws:

EXistException

release

public void release(DBBroker broker)

Releases a broker for the database instance. If it is no more used, make if invactive. If there are pending system maintenance tasks, the method will block until these tasks have finished.

Parameters:

broker - The broker to be released

reloadSecurityManager

public void reloadSecurityManager(DBBroker broker)

Reloads the security manager of the database instance. This method is called for example when the users.xml file has been changed.

triggerSync

public void triggerSync(int syncEvent)

Schedules a cache synchronization for the database instance. If the database instance is idle, the cache synchronization will be run immediately. Otherwise, the task will be deffered until all running threads have returned.

Parameters:

syncEvent - One of org.exist.storage.Sync#MINOR_SYNC or org.exist.storage.Sync#MINOR_SYNC

triggerSystemTask

public void triggerSystemTask(SystemTask task)

Schedules a system maintenance task for the database instance. If the database is idle, the task will be run immediately. Otherwise, the task will be deffered until all running threads have returned.

Parameters:

task - The task

shutdown

public void shutdown()

Shuts downs the database instance

shutdown

public void shutdown(boolean killed)

Shuts downs the database instance

Parameters:

killed - true when the JVM is (cleanly) exiting

triggerCheckpoint

public void triggerCheckpoint()