org.exist.storage
Class BrokerPool

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

All Implemented Interfaces:

Database

public class BrokerPool
extends java.util.Observable
implements Database

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.

Field Summary

static java.lang.String	COLLECTION_CACHE_SIZE_ATTRIBUTE
protected CollectionCache	collectionCache The cache in which the database instance's collections are stored.
protected Configuration	conf The configuration object for the database instance
static java.lang.String	CONFIGURATION_CONNECTION_ELEMENT_NAME
static java.lang.String	CONFIGURATION_POOL_ELEMENT_NAME
static java.lang.String	CONFIGURATION_RECOVERY_ELEMENT_NAME
static java.lang.String	CONFIGURATION_SECURITY_ELEMENT_NAME
static java.lang.String	DATA_DIR_ATTRIBUTE
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
static int	DEFAULT_PAGE_SIZE
static java.lang.String	DEFAULT_SECURITY_CLASS
long	DEFAULT_SYNCH_PERIOD
static java.lang.String	DOC_ID_MODE_ATTRIBUTE
static java.lang.String	DOC_ID_MODE_PROPERTY
static boolean	FORCE_CORRUPTION For testing only: triggers a database corruption by disabling the page caches.
static java.lang.String	MAX_CONNECTIONS_ATTRIBUTE
static java.lang.String	MIN_CONNECTIONS_ATTRIBUTE
static java.lang.String	NODES_BUFFER_ATTRIBUTE
static java.lang.String	PROPERTY_COLLECTION_CACHE_SIZE
static java.lang.String	PROPERTY_DATA_DIR
static java.lang.String	PROPERTY_MAX_CONNECTIONS
static java.lang.String	PROPERTY_MIN_CONNECTIONS
static java.lang.String	PROPERTY_NODES_BUFFER
static java.lang.String	PROPERTY_PAGE_SIZE
static java.lang.String	PROPERTY_RECOVERY_CHECK
static java.lang.String	PROPERTY_RECOVERY_ENABLED
static java.lang.String	PROPERTY_SECURITY_CLASS
static java.lang.String	PROPERTY_SHUTDOWN_DELAY
static java.lang.String	PROPERTY_SYNC_PERIOD
static java.lang.String	PROPERTY_SYSTEM_TASK_CONFIG
static java.lang.String	RECOVERY_ENABLED_ATTRIBUTE
static java.lang.String	RECOVERY_POST_RECOVERY_CHECK
static java.lang.String	SHUTDOWN_DELAY_ATTRIBUTE
static java.lang.String	SIGNAL_READINESS ready for recovery & read-only operations
static java.lang.String	SIGNAL_RIDEABLE ready for writable operations
static java.lang.String	SIGNAL_SHUTDOWN running shutdown sequence
static java.lang.String	SIGNAL_STARTUP initializing subcomponents
static java.lang.String	SYNC_PERIOD_ATTRIBUTE
protected XMLReaderPool	xmlReaderPool The pool in which the database instance's readers are stored.

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	enterServiceMode(Subject user)
void	exitServiceMode(Subject user)
DBBroker	get(Subject user) Returns an active broker for the database instance.
DBBroker	getActiveBroker()
java.util.Map<java.lang.Thread,DBBroker>	getActiveBrokers()
DBBroker	getBroker()
DefaultCacheManager	getCacheManager() Returns a cache in which the database instance's may store items.
CollectionCacheManager	getCollectionCacheMgr()
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.
Debuggee	getDebuggee()
Lock	getGlobalUpdateLock() Returns the global update lock for the database instance.
java.lang.String	getId() Returns the database instance's name.
IndexManager	getIndexManager() Returns the index manager which handles all additional indexes not being part of the database core.
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<BrokerPool>	getInstances() Returns an iterator over the database instances.
long	getLastMajorSync()
long	getMajorSyncPeriod()
int	getMax() Returns the maximal number of brokers for the database instance.
NodeIdFactory	getNodeFactory()
NotificationService	getNotificationService()
int	getPageSize()
XMLReaderPool	getParserPool() Returns a pool in which the database instance's readers are stored.
PerformanceStats	getPerformanceStats() Returns the global profiler used to gather execution statistics from all XQueries running on this db instance.
ProcessMonitor	getProcessMonitor() Returns a monitor in which the database instance's running XQueries are managed.
long	getReservedMem()
Scheduler	getScheduler() Returns the Scheduler
SecurityManager	getSecurityManager() Returns the database instance's security manager
java.util.Calendar	getStartupTime()
Subject	getSubject()
SymbolTable	getSymbols()
TransactionManager	getTransactionManager()
BrokerWatchdog	getWatchdog()
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	isInServiceMode()
boolean	isInstanceConfigured() Returns whether the database instance has been configured.
static boolean	isInstancesEmpty()
boolean	isReadOnly()
boolean	isShuttingDown()
boolean	isTransactional() Returns whether transactions can be handled by the database instance.
void	printSystemInfo()
void	registerShutdownListener(ShutdownListener listener)
static void	registerStatusObserver(java.util.Observer observer)
void	release(DBBroker broker) Releases a broker for the database instance.
void	reloadSecurityManager(DBBroker broker) Reloads the security manager of the database instance.
void	setReadOnly()
static void	setRegisterShutdownHook(boolean register) Whether of not the JVM should run the shutdown thread.
boolean	setSubject(Subject subject)
void	shutdown() Shuts downs the database instance
void	shutdown(boolean killed) Shuts downs the database instance
void	signalSystemStatus(java.lang.String signal)
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	sync(DBBroker broker, int syncEvent) Executes a waiting cache synchronization for the database instance.
static void	systemInfo()
int	total()
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.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.exist.Database

addObserver

Field Detail

SIGNAL_STARTUP

public static final java.lang.String SIGNAL_STARTUP

initializing subcomponents

See Also:

Constant Field Values

SIGNAL_READINESS

public static final java.lang.String SIGNAL_READINESS

ready for recovery & read-only operations

See Also:

Constant Field Values

SIGNAL_RIDEABLE

public static final java.lang.String SIGNAL_RIDEABLE

ready for writable operations

See Also:

Constant Field Values

SIGNAL_SHUTDOWN

public static final java.lang.String SIGNAL_SHUTDOWN

running shutdown sequence

See Also:

Constant Field Values

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

CONFIGURATION_CONNECTION_ELEMENT_NAME

public static final java.lang.String CONFIGURATION_CONNECTION_ELEMENT_NAME

See Also:

Constant Field Values

CONFIGURATION_POOL_ELEMENT_NAME

public static final java.lang.String CONFIGURATION_POOL_ELEMENT_NAME

See Also:

Constant Field Values

CONFIGURATION_SECURITY_ELEMENT_NAME

public static final java.lang.String CONFIGURATION_SECURITY_ELEMENT_NAME

See Also:

Constant Field Values

CONFIGURATION_RECOVERY_ELEMENT_NAME

public static final java.lang.String CONFIGURATION_RECOVERY_ELEMENT_NAME

See Also:

Constant Field Values

DATA_DIR_ATTRIBUTE

public static final java.lang.String DATA_DIR_ATTRIBUTE

See Also:

Constant Field Values

RECOVERY_ENABLED_ATTRIBUTE

public static final java.lang.String RECOVERY_ENABLED_ATTRIBUTE

See Also:

Constant Field Values

RECOVERY_POST_RECOVERY_CHECK

public static final java.lang.String RECOVERY_POST_RECOVERY_CHECK

See Also:

Constant Field Values

COLLECTION_CACHE_SIZE_ATTRIBUTE

public static final java.lang.String COLLECTION_CACHE_SIZE_ATTRIBUTE

See Also:

Constant Field Values

MIN_CONNECTIONS_ATTRIBUTE

public static final java.lang.String MIN_CONNECTIONS_ATTRIBUTE

See Also:

Constant Field Values

MAX_CONNECTIONS_ATTRIBUTE

public static final java.lang.String MAX_CONNECTIONS_ATTRIBUTE

See Also:

Constant Field Values

SYNC_PERIOD_ATTRIBUTE

public static final java.lang.String SYNC_PERIOD_ATTRIBUTE

See Also:

Constant Field Values

SHUTDOWN_DELAY_ATTRIBUTE

public static final java.lang.String SHUTDOWN_DELAY_ATTRIBUTE

See Also:

Constant Field Values

NODES_BUFFER_ATTRIBUTE

public static final java.lang.String NODES_BUFFER_ATTRIBUTE

See Also:

Constant Field Values

PROPERTY_DATA_DIR

public static final java.lang.String PROPERTY_DATA_DIR

See Also:

Constant Field Values

PROPERTY_MIN_CONNECTIONS

public static final java.lang.String PROPERTY_MIN_CONNECTIONS

See Also:

Constant Field Values

PROPERTY_MAX_CONNECTIONS

public static final java.lang.String PROPERTY_MAX_CONNECTIONS

See Also:

Constant Field Values

PROPERTY_SYNC_PERIOD

public static final java.lang.String PROPERTY_SYNC_PERIOD

See Also:

Constant Field Values

PROPERTY_SHUTDOWN_DELAY

public static final java.lang.String PROPERTY_SHUTDOWN_DELAY

See Also:

Constant Field Values

PROPERTY_COLLECTION_CACHE_SIZE

public static final java.lang.String PROPERTY_COLLECTION_CACHE_SIZE

See Also:

Constant Field Values

DEFAULT_SECURITY_CLASS

public static final java.lang.String DEFAULT_SECURITY_CLASS

See Also:

Constant Field Values

PROPERTY_SECURITY_CLASS

public static final java.lang.String PROPERTY_SECURITY_CLASS

See Also:

Constant Field Values

PROPERTY_RECOVERY_ENABLED

public static final java.lang.String PROPERTY_RECOVERY_ENABLED

See Also:

Constant Field Values

PROPERTY_RECOVERY_CHECK

public static final java.lang.String PROPERTY_RECOVERY_CHECK

See Also:

Constant Field Values

PROPERTY_SYSTEM_TASK_CONFIG

public static final java.lang.String PROPERTY_SYSTEM_TASK_CONFIG

See Also:

Constant Field Values

PROPERTY_NODES_BUFFER

public static final java.lang.String PROPERTY_NODES_BUFFER

See Also:

Constant Field Values

DOC_ID_MODE_ATTRIBUTE

public static final java.lang.String DOC_ID_MODE_ATTRIBUTE

See Also:

Constant Field Values

DOC_ID_MODE_PROPERTY

public static final java.lang.String DOC_ID_MODE_PROPERTY

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

PROPERTY_PAGE_SIZE

public static final java.lang.String PROPERTY_PAGE_SIZE

See Also:

Constant Field Values

DEFAULT_PAGE_SIZE

public static final int DEFAULT_PAGE_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.

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,
                                   DatabaseConfigurationException

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.

DatabaseConfigurationException

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<BrokerPool> getInstances()

Returns an iterator over the database instances.

Returns:

The iterator

isInstancesEmpty

public static final boolean isInstancesEmpty()

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

systemInfo

public static final void systemInfo()

registerStatusObserver

public static void registerStatusObserver(java.util.Observer observer)

canReadDataDir

protected boolean canReadDataDir(Configuration conf)
                          throws EXistException

Throws:

EXistException

initialize

protected void initialize()
                   throws EXistException,
                          DatabaseConfigurationException

Initializes the database instance.

Throws:

EXistException

DatabaseConfigurationException

getReservedMem

public long getReservedMem()

getPageSize

public int getPageSize()

signalSystemStatus

public void signalSystemStatus(java.lang.String signal)

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.

Specified by:

getId in interface Database

Returns:

The id

active

public int active()

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

Returns:

The brokers count

getActiveBrokers

public java.util.Map<java.lang.Thread,DBBroker> getActiveBrokers()

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

total

public int total()

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.

Specified by:

getConfiguration in interface Database

Returns:

The configuration

registerShutdownListener

public void registerShutdownListener(ShutdownListener listener)

getNodeFactory

public NodeIdFactory getNodeFactory()

Specified by:

getNodeFactory in interface Database

getSecurityManager

public SecurityManager getSecurityManager()

Returns the database instance's security manager

Specified by:

getSecurityManager in interface Database

Returns:

The security manager

getScheduler

public Scheduler getScheduler()

Returns the Scheduler

Returns:

The scheduler

getSymbols

public SymbolTable getSymbols()

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

isReadOnly

public boolean isReadOnly()

setReadOnly

public void setReadOnly()

isInServiceMode

public boolean isInServiceMode()

getTransactionManager

public TransactionManager getTransactionManager()

Specified by:

getTransactionManager in interface Database

Returns:

TransactionManager

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 DefaultCacheManager getCacheManager()

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

Specified by:

getCacheManager in interface Database

Returns:

The cache

getCollectionCacheMgr

public CollectionCacheManager getCollectionCacheMgr()

getIndexManager

public IndexManager getIndexManager()

Returns the index manager which handles all additional indexes not being part of the database core.

Specified by:

getIndexManager in interface Database

Returns:

The IndexManager

getXQueryPool

public XQueryPool getXQueryPool()

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

Returns:

The pool

getProcessMonitor

public ProcessMonitor getProcessMonitor()

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

Returns:

The monitor

getPerformanceStats

public PerformanceStats getPerformanceStats()

Returns the global profiler used to gather execution statistics from all XQueries running on this db instance.

Specified by:

getPerformanceStats in interface Database

Returns:

the profiler

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

setSubject

public boolean setSubject(Subject subject)

Specified by:

setSubject in interface Database

getSubject

public Subject getSubject()

Specified by:

getSubject in interface Database

Returns:

Subject

getActiveBroker

public DBBroker getActiveBroker()

Specified by:

getActiveBroker in interface Database

getBroker

public DBBroker getBroker()
                   throws EXistException

Specified by:

getBroker in interface Database

Throws:

EXistException

get

public DBBroker get(Subject user)
             throws EXistException

Returns an active broker for the database instance.

Specified by:

get in interface Database

Returns:

The broker

Throws:

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

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.

Specified by:

release in interface Database

Parameters:

broker - The broker to be released

enterServiceMode

public DBBroker enterServiceMode(Subject user)
                          throws PermissionDeniedException

Throws:

PermissionDeniedException

exitServiceMode

public void exitServiceMode(Subject user)
                     throws PermissionDeniedException

Throws:

PermissionDeniedException

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.

Parameters:

broker - A broker responsible for executing the job TOUNDERSTAND (pb) : why do we need a broker here ? Why not get and release one when we're done? WM: this is called from the Collection.store() methods to signal that /db/system/users.xml has changed. A broker is already available in these methods, so we use it here.

getMajorSyncPeriod

public long getMajorSyncPeriod()

getLastMajorSync

public long getLastMajorSync()

sync

public void sync(DBBroker broker,
                 int syncEvent)

Executes a waiting cache synchronization for the database instance.

Parameters:

broker - A broker responsible for executing the job

syncEvent - One of Sync.MINOR_SYNC or Sync.MINOR_SYNC

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 Sync.MINOR_SYNC or 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

Specified by:

shutdown in interface Database

isShuttingDown

public boolean isShuttingDown()

shutdown

public void shutdown(boolean killed)

Shuts downs the database instance

Parameters:

killed - true when the JVM is (cleanly) exiting

getWatchdog

public BrokerWatchdog getWatchdog()

triggerCheckpoint

public void triggerCheckpoint()

getDebuggee

public Debuggee getDebuggee()

Specified by:

getDebuggee in interface Database

Returns:

Debuggee

getStartupTime

public java.util.Calendar getStartupTime()

printSystemInfo

public void printSystemInfo()