org.exist.storage
Class BrokerPool

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

public class BrokerPool
extends 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

int	DEFAULT_COLLECTION_BUFFER_SIZE
static 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.
static String	PROPERTY_COLLECTION_CACHE_SIZE
static String	PROPERTY_MAX_CONNECTIONS
static String	PROPERTY_MIN_CONNECTIONS
static String	PROPERTY_SHUTDOWN_DELAY
static String	PROPERTY_SYNC_PERIOD

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.
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(String instanceName, int minBrokers, int maxBrokers, Configuration config) Creates and configures a database instance and adds it to the pool.
void	enterServiceMode(User user)
void	exitServiceMode(User user)
DBBroker	get(User user) Returns an active broker for the database instance.
DefaultCacheManager	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.
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(String instanceName) Returns a broker pool for a database instance.
static Iterator	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()
XMLReaderPool	getParserPool() Returns a pool in which the database instance's readers are stored.
Scheduler	getScheduler() Returns the Scheduler
SecurityManager	getSecurityManager() Returns the database instance's security manager
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.
static boolean	isConfigured() Returns whether or not the default database instance is configured.
static boolean	isConfigured(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.
boolean	isReadOnly()
boolean	isTransactional() Returns whether transactions can be handled by the database instance.
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(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

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

Field Detail

DEFAULT_INSTANCE_NAME

public static final 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

PROPERTY_MIN_CONNECTIONS

public static final String PROPERTY_MIN_CONNECTIONS

See Also:

Constant Field Values

PROPERTY_MAX_CONNECTIONS

public static final String PROPERTY_MAX_CONNECTIONS

See Also:

Constant Field Values

PROPERTY_SYNC_PERIOD

public static final String PROPERTY_SYNC_PERIOD

See Also:

Constant Field Values

PROPERTY_SHUTDOWN_DELAY

public static final String PROPERTY_SHUTDOWN_DELAY

See Also:

Constant Field Values

PROPERTY_COLLECTION_CACHE_SIZE

public static final String PROPERTY_COLLECTION_CACHE_SIZE

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

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(String instanceName,
                                   int minBrokers,
                                   int maxBrokers,
                                   Configuration config)
                            throws EXistException,
                                   DatabaseConfigurationException

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.

DatabaseConfigurationException

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(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(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 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(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

isInitializing

public boolean isInitializing()

Whether or not the database instance is being initialized.

Returns:

true is the database instance is being initialized

getId

public 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)

getNodeFactory

public NodeIdFactory getNodeFactory()

getSecurityManager

public SecurityManager getSecurityManager()

Returns the database instance's security manager

Returns:

The security manager

getScheduler

public Scheduler getScheduler()

Returns the Scheduler

Returns:

The scheduler

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

isInServiceMode

public boolean isInServiceMode()

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

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

Returns:

The cache

getIndexManager

public IndexManager getIndexManager()

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

Returns:

The IndexManager

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

get

public DBBroker get(User user)
             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)

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

enterServiceMode

public void enterServiceMode(User user)
                      throws PermissionDeniedException

Throws:

PermissionDeniedException

exitServiceMode

public void exitServiceMode(User 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()

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

shutdown

public void shutdown(boolean killed)

Shuts downs the database instance

Parameters:

killed - true when the JVM is (cleanly) exiting

triggerCheckpoint

public void triggerCheckpoint()