org.exist.storage
Class BrokerPool

java.lang.Object
  extended byorg.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
 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.
static java.lang.String PROPERTY_COLLECTION_CACHE_SIZE
           
static java.lang.String PROPERTY_MAX_CONNECTIONS
           
static java.lang.String PROPERTY_MIN_CONNECTIONS
           
static java.lang.String PROPERTY_SHUTDOWN_DELAY
           
static java.lang.String PROPERTY_SYNC_PERIOD
           
 
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.
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.
 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.
 NodeIdFactory getNodeFactory()
           
 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.
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 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(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
equals, 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

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

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

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)

getNodeFactory

public NodeIdFactory getNodeFactory()

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

isReadOnly

public boolean isReadOnly()

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

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.

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.

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


Copyright (C) Wolfgang Meier. All rights reserved.