## 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 <meier@ifs.tu-darmstadt.de>, Pierrick Brihaye <pierrick.brihaye@free.fr>

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.