org.exist.storage
Class BrokerPool

java.lang.Object
  extended by 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
static String COLLECTION_CACHE_SIZE_ATTRIBUTE
           
static String CONFIGURATION_CONNECTION_ELEMENT_NAME
           
static String CONFIGURATION_POOL_ELEMENT_NAME
           
static String CONFIGURATION_RECOVERY_ELEMENT_NAME
           
static String CONFIGURATION_SECURITY_ELEMENT_NAME
           
static String DATA_DIR_ATTRIBUTE
           
 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
           
static int DEFAULT_PAGE_SIZE
           
static String DEFAULT_SECURITY_CLASS
           
 long DEFAULT_SYNCH_PERIOD
           
static boolean FORCE_CORRUPTION
          For testing only: triggers a database corruption by disabling the page caches.
static String MAX_CONNECTIONS_ATTRIBUTE
           
static String MIN_CONNECTIONS_ATTRIBUTE
           
static String PROPERTY_COLLECTION_CACHE_SIZE
           
static String PROPERTY_DATA_DIR
           
static String PROPERTY_MAX_CONNECTIONS
           
static String PROPERTY_MIN_CONNECTIONS
           
static String PROPERTY_PAGE_SIZE
           
static String PROPERTY_RECOVERY_CHECK
           
static String PROPERTY_RECOVERY_ENABLED
           
static String PROPERTY_SECURITY_CLASS
           
static String PROPERTY_SHUTDOWN_DELAY
           
static String PROPERTY_SYNC_PERIOD
           
static String PROPERTY_SYSTEM_TASK_CONFIG
           
static String RECOVERY_ENABLED_ATTRIBUTE
           
static String RECOVERY_POST_RECOVERY_CHECK
           
static String SHUTDOWN_DELAY_ATTRIBUTE
           
static String SYNC_PERIOD_ATTRIBUTE
           
 
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.
 Map getActiveBrokers()
           
 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.
 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()
           
 int getPageSize()
           
 XMLReaderPool getParserPool()
          Returns a pool in which the database instance's readers are stored.
 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
 SymbolTable getSymbols()
           
 TransactionManager getTransactionManager()
           
 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 isShuttingDown()
           
 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

CONFIGURATION_CONNECTION_ELEMENT_NAME

public static final String CONFIGURATION_CONNECTION_ELEMENT_NAME
See Also:
Constant Field Values

CONFIGURATION_POOL_ELEMENT_NAME

public static final String CONFIGURATION_POOL_ELEMENT_NAME
See Also:
Constant Field Values

CONFIGURATION_SECURITY_ELEMENT_NAME

public static final String CONFIGURATION_SECURITY_ELEMENT_NAME
See Also:
Constant Field Values

CONFIGURATION_RECOVERY_ELEMENT_NAME

public static final String CONFIGURATION_RECOVERY_ELEMENT_NAME
See Also:
Constant Field Values

DATA_DIR_ATTRIBUTE

public static final String DATA_DIR_ATTRIBUTE
See Also:
Constant Field Values

RECOVERY_ENABLED_ATTRIBUTE

public static final String RECOVERY_ENABLED_ATTRIBUTE
See Also:
Constant Field Values

RECOVERY_POST_RECOVERY_CHECK

public static final String RECOVERY_POST_RECOVERY_CHECK
See Also:
Constant Field Values

COLLECTION_CACHE_SIZE_ATTRIBUTE

public static final String COLLECTION_CACHE_SIZE_ATTRIBUTE
See Also:
Constant Field Values

MIN_CONNECTIONS_ATTRIBUTE

public static final String MIN_CONNECTIONS_ATTRIBUTE
See Also:
Constant Field Values

MAX_CONNECTIONS_ATTRIBUTE

public static final String MAX_CONNECTIONS_ATTRIBUTE
See Also:
Constant Field Values

SYNC_PERIOD_ATTRIBUTE

public static final String SYNC_PERIOD_ATTRIBUTE
See Also:
Constant Field Values

SHUTDOWN_DELAY_ATTRIBUTE

public static final String SHUTDOWN_DELAY_ATTRIBUTE
See Also:
Constant Field Values

PROPERTY_DATA_DIR

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

DEFAULT_SECURITY_CLASS

public static final String DEFAULT_SECURITY_CLASS
See Also:
Constant Field Values

PROPERTY_SECURITY_CLASS

public static final String PROPERTY_SECURITY_CLASS
See Also:
Constant Field Values

PROPERTY_RECOVERY_ENABLED

public static final String PROPERTY_RECOVERY_ENABLED
See Also:
Constant Field Values

PROPERTY_RECOVERY_CHECK

public static final String PROPERTY_RECOVERY_CHECK
See Also:
Constant Field Values

PROPERTY_SYSTEM_TASK_CONFIG

public static final String PROPERTY_SYSTEM_TASK_CONFIG
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 String PROPERTY_PAGE_SIZE
See Also:
Constant Field Values

DEFAULT_PAGE_SIZE

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

getReservedMem

public long getReservedMem()

getPageSize

public int getPageSize()

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

getActiveBrokers

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

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

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

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

getCollectionCacheMgr

public CollectionCacheManager getCollectionCacheMgr()

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

getProcessMonitor

public ProcessMonitor getProcessMonitor()
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


isShuttingDown

public boolean isShuttingDown()

shutdown

public void shutdown(boolean killed)
Shuts downs the database instance

Parameters:
killed - true when the JVM is (cleanly) exiting

triggerCheckpoint

public void triggerCheckpoint()


Copyright (C) Wolfgang Meier. All rights reserved.