DatabaseConditionsManager (HPS Java 4.3-SNAPSHOT API)

java.lang.Object
- org.lcsim.conditions.ConditionsManager
- - org.lcsim.conditions.ConditionsManagerImplementation
  - - org.hps.conditions.database.DatabaseConditionsManager

```
public final class DatabaseConditionsManager
extends org.lcsim.conditions.ConditionsManagerImplementation
```
This class provides the top-level API for accessing database conditions, as well as configuring the database connection, initializing all required components, and loading required converters and table meta data. It is registered as the global ConditionsManager in the constructor.
Differences between Test Run and Engineering Run configurations are handled automatically.
The connection URL, username and password can be set via Java properties from the command line, e.g. for the default connection:
java -Dorg.hps.conditions.url=jdbc:mysql://hpsdb.jlab.org:3306/hps_conditions -Dorg.hps.conditions.user=hpsuser -Dorg.hps.conditions.password=darkphoton [...]
To use a local SQLite database, provide a URL that looks something like this:
jdbc:sqlite:hps_conditions.db
The last part should be the relative or absolute path to the SQLite db file.
When using a SQLite database, no username or password needs to be provided.
SQLite is not supported in write mode. The local database should be a clone of a particular version of the master MySQL database at JLab.

Author:

Jeremy McCormick, SLAC

See Also:

ConditionsManager

Nested Class Summary
- Nested classes/interfaces inherited from class org.lcsim.conditions.ConditionsManager
  org.lcsim.conditions.ConditionsManager.ConditionsNotFoundException, org.lcsim.conditions.ConditionsManager.ConditionsSetNotFoundException

Field Summary

Fields
Modifier and Type	Field and Description
`private ConditionsRecord.ConditionsRecordCollection`	`conditionsRecordCollection` The current set of conditions records for the run.
`private ConditionsTag.ConditionsTagCollection`	`conditionsTagCollection` The currently active conditions tag; an empty collection means that no tag is active.
`private Connection`	`connection` The current database connection.
`private ConverterRegistry`	`converters` Create the global registry of conditions object converters.
`private static String`	`DEFAULT_PASSWORD` Password for default account 'hpsuser'.
`private static String`	`DEFAULT_URL` Default database URL.
`private static String`	`DEFAULT_USER` Default database user for read access.
`private org.lcsim.conditions.ConditionsConverter`	`ecalConverter` The converter for creating the combined ECAL conditions object.
`private boolean`	`isFrozen` True if the conditions system has been frozen and will ignore updates after it is initialized.
`private boolean`	`isInitialized` True if the manager has been initialized, e.g.
`private boolean`	`isTestRun` True if current run number is from Test Run.
`private static Logger`	`LOG` Initialize the logger.
`private static int`	`MAX_ATTEMPTS` Number of connection retries allowed.
`private static int`	`RETRY_WAIT` Wait time (in millis) for the first retry.
`private org.lcsim.conditions.ConditionsConverter`	`svtConverter` The converter for creating the combined SVT conditions object.
`private TableRegistry`	`tableRegistry` Create the global registry of table meta data.
`private Set<String>`	`tags` The currently applied conditions tags.
`private static int`	`TEST_RUN_MAX_RUN` The max value for a run to be considered Test Run.

Fields inherited from class org.lcsim.conditions.ConditionsManagerImplementation
cache, detectorName, listenerList, logger, reader, run

Constructor Summary

Constructors
Constructor and Description

DatabaseConditionsManager()
Class constructor.

Constructors
Constructor and Description
`DatabaseConditionsManager()` Class constructor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addTag(String tag)` Add a tag used to filter the accessible conditions records.
`void`	`addTags(Set<String> tags)` Add one or more tags for filtering records.
`void`	`clearTags()` Clear the tags used to filter the `ConditionsRecord`s.
`void`	`closeConnection()` Close the database connection.
`boolean`	`collectionExists(String tableName, int collectionID)` This method will return `true` if the given collection ID already exists in the table.
`private Connection`	`createConnection()` Get a connection to the conditions database, possibly using properties from the command line for the database URL, username, and password (otherwise the defaults are used to provide a read only connection).
`ConditionsRecord.ConditionsRecordCollection`	`findConditionsRecords(String name)` Find a collection of conditions validity records by key name.
`TableMetaData`	`findTableMetaData(String name)` Find table information from the name.
`void`	`freeze()` This method can be called to "freeze" the conditions system so that any subsequent updates to run number or detector name will be ignored.
`Collection<String>`	`getActiveTags()` Get the currently active conditions tags.
`Set<String>`	`getAvailableTags()` Get the set of available conditions tags from the conditions table
`int`	`getCollectionId(ConditionsObjectCollection<?> collection, String description)` Add a row for a new collection and return the new collection ID assigned to it.
`ConditionsRecord.ConditionsRecordCollection`	`getConditionsRecords()` Get the list of conditions records for the run, filtered by the current set of active tags.
`<ObjectType extends ConditionsObject,CollectionType extends ConditionsObjectCollection<ObjectType>> ConditionsSeries<ObjectType,CollectionType>`	`getConditionsSeries(Class<CollectionType> collectionType, String tableName)` Get a conditions series with one or more collections.
`Connection`	`getConnection()` Get the JDBC connection.
`org.lcsim.geometry.Detector`	`getDetectorObject()` Get the current LCSim compact `Detector` object with the geometry and detector model.
`EcalConditions`	`getEcalConditions()` Get the combined ECAL conditions for this run.
`static DatabaseConditionsManager`	`getInstance()` Get the static instance of this class.
`SvtConditions`	`getSvtConditions()` Get the combined SVT conditions for this run.
`boolean`	`hasConditionsRecord(String name)` True if there is a conditions record with the given name.
`boolean`	`isFrozen()` True if conditions system is frozen
`boolean`	`isInitialized()` True if conditions manager is properly initialized.
`boolean`	`isTestRun()` Return `true` if Test Run configuration is active
`static boolean`	`isTestRun(int runNumber)` Utility method to determine if a run number is from the 2012 Test Run.
`<CollectionType extends ConditionsObjectCollection<?>> CollectionType`	`newCollection(Class<CollectionType> collectionType)` Create a new collection with the given type.
`<CollectionType extends ConditionsObjectCollection<?>> CollectionType`	`newCollection(Class<CollectionType> collectionType, String tableName)` Create a new collection with the given type and table name.
`void`	`openConnection()` Open the database connection.
`private void`	`registerConverters()` Register the conditions converters with the manager.
`ResultSet`	`selectQuery(String query)` This method can be used to perform a database SELECT query.
`void`	`setDetector(String detectorName, int runNumber)` This method handles changes to the detector name and run number.
`void`	`unfreeze()` Un-freeze the conditions system so that updates will be received again.

Methods inherited from class org.lcsim.conditions.ConditionsManagerImplementation
addConditionsListener, clearCache, fireConditionsChanged, getCachedConditions, getConditions, getConditionsReader, getDetector, getRawConditions, getRun, open, registerConditionsConverter, removeConditionsConverter, removeConditionsListener, setConditionsReader, setRun

Methods inherited from class org.lcsim.conditions.ConditionsManager
defaultInstance, isSetup, setDefaultConditionsManager

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - LOG
```
private static Logger LOG
```
    Initialize the logger.
  - TEST_RUN_MAX_RUN
```
private static final int TEST_RUN_MAX_RUN
```
    The max value for a run to be considered Test Run.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_URL
```
private static String DEFAULT_URL
```
    Default database URL.
  - DEFAULT_USER
```
private static String DEFAULT_USER
```
    Default database user for read access.
  - DEFAULT_PASSWORD
```
private static String DEFAULT_PASSWORD
```
    Password for default account 'hpsuser'.
  - MAX_ATTEMPTS
```
private static final int MAX_ATTEMPTS
```
    Number of connection retries allowed.
    
    See Also:
    
    Constant Field Values
  - RETRY_WAIT
```
private static final int RETRY_WAIT
```
    Wait time (in millis) for the first retry. The nth retry waits for n*RETRY_WAIT millis.
    
    See Also:
    
    Constant Field Values
  - conditionsRecordCollection
```
private ConditionsRecord.ConditionsRecordCollection conditionsRecordCollection
```
    The current set of conditions records for the run.
  - conditionsTagCollection
```
private final ConditionsTag.ConditionsTagCollection conditionsTagCollection
```
    The currently active conditions tag; an empty collection means that no tag is active.
  - connection
```
private Connection connection
```
    The current database connection.
  - converters
```
private final ConverterRegistry converters
```
    Create the global registry of conditions object converters.
  - ecalConverter
```
private org.lcsim.conditions.ConditionsConverter ecalConverter
```
    The converter for creating the combined ECAL conditions object.
  - isFrozen
```
private boolean isFrozen
```
    True if the conditions system has been frozen and will ignore updates after it is initialized.
  - isInitialized
```
private boolean isInitialized
```
    True if the manager has been initialized, e.g. the setDetector(String, int) method was called.
  - isTestRun
```
private boolean isTestRun
```
    True if current run number is from Test Run.
  - svtConverter
```
private org.lcsim.conditions.ConditionsConverter svtConverter
```
    The converter for creating the combined SVT conditions object.
  - tableRegistry
```
private final TableRegistry tableRegistry
```
    Create the global registry of table meta data.
  - tags
```
private final Set<String> tags
```
    The currently applied conditions tags.
- Constructor Detail
  - DatabaseConditionsManager
```
public DatabaseConditionsManager()
```
    Class constructor. Calling this will automatically register this manager as the global default.
- Method Detail
  - createConnection
```
private Connection createConnection()
```
    Get a connection to the conditions database, possibly using properties from the command line for the database URL, username, and password (otherwise the defaults are used to provide a read only connection).
    
    Returns:
    
    A connection to the conditions database
  - getInstance
```
public static DatabaseConditionsManager getInstance()
```
    Get the static instance of this class.
    
    Returns:
    
    the static instance of the manager
  - isTestRun
```
public static boolean isTestRun(int runNumber)
```
    Utility method to determine if a run number is from the 2012 Test Run.
    
    Parameters:
    
    runNumber - the run number
    
    Returns:
    
    true if run number is from the Test Run
  - addTag
```
public void addTag(String tag)
```
    Add a tag used to filter the accessible conditions records.
    Multiple tags are OR'd together.
    
    Parameters:
    
    tag - the tag value used to filter returned conditions records
  - addTags
```
public void addTags(Set<String> tags)
```
    Add one or more tags for filtering records.
    
    Parameters:
    
    tags - the Set of tags to add
  - clearTags
```
public void clearTags()
```
    Clear the tags used to filter the ConditionsRecords.
  - closeConnection
```
public void closeConnection()
```
    Close the database connection.
  - collectionExists
```
public boolean collectionExists(String tableName,
                                int collectionID)
```
    This method will return true if the given collection ID already exists in the table.
    
    Parameters:
    
    tableName - the name of the table
    
    collectionID - the collection ID value
    
    Returns:
    
    true if collection exists
  - findConditionsRecords
```
public ConditionsRecord.ConditionsRecordCollection findConditionsRecords(String name)
```
    Find a collection of conditions validity records by key name. The key name is distinct from the table name, but they are usually set to the same value.
    
    Parameters:
    
    name - the conditions key name
    
    Returns:
    
    the set of matching conditions records
  - findTableMetaData
```
public TableMetaData findTableMetaData(String name)
```
    Find table information from the name.
    
    Parameters:
    
    name - the name of the table
    
    Returns:
    
    the table information or null if does not exist
  - freeze
```
public void freeze()
```
    This method can be called to "freeze" the conditions system so that any subsequent updates to run number or detector name will be ignored.
  - getActiveTags
```
public Collection<String> getActiveTags()
```
    Get the currently active conditions tags.
    
    Returns:
    
    the currently active conditions tags
  - getAvailableTags
```
public Set<String> getAvailableTags()
```
    Get the set of available conditions tags from the conditions table
    
    Returns:
    
    the set of available conditions tags
  - getCollectionId
```
public int getCollectionId(ConditionsObjectCollection<?> collection,
                           String description)
                    throws SQLException
```
    Add a row for a new collection and return the new collection ID assigned to it.
    
    Parameters:
    
    collection - the conditions object collection
    
    description - text description for the new collection ID record in the database
    
    Returns:
    
    the collection's ID
    
    Throws:
    
    SQLException
  - getConditionsRecords
```
public ConditionsRecord.ConditionsRecordCollection getConditionsRecords()
```
    Get the list of conditions records for the run, filtered by the current set of active tags.
    
    Returns:
    
    the list of conditions records for the run
  - getConditionsSeries
```
public <ObjectType extends ConditionsObject,CollectionType extends ConditionsObjectCollection<ObjectType>> ConditionsSeries<ObjectType,CollectionType> getConditionsSeries(Class<CollectionType> collectionType,
                                                                                                                                                                           String tableName)
```
    Get a conditions series with one or more collections.
    
    Type Parameters:
    
    ObjectType - the type of the conditions object
    
    CollectionType - the type of the conditions collection
    
    Parameters:
    
    collectionType - the type of the collection
    
    tableName - the name of the data table
    
    Returns:
    
    the conditions series
  - getConnection
```
public Connection getConnection()
```
    Get the JDBC connection.
    
    Returns:
    
    the JDBC connection
  - getDetectorObject
```
public org.lcsim.geometry.Detector getDetectorObject()
```
    Get the current LCSim compact Detector object with the geometry and detector model.
    
    Returns:
    
    the detector object
  - getEcalConditions
```
public EcalConditions getEcalConditions()
```
    Get the combined ECAL conditions for this run.
    
    Returns:
    
    the combined ECAL conditions
  - getSvtConditions
```
public SvtConditions getSvtConditions()
```
    Get the combined SVT conditions for this run.
    
    Returns:
    
    the combined SVT conditions
  - hasConditionsRecord
```
public boolean hasConditionsRecord(String name)
```
    True if there is a conditions record with the given name.
    
    Parameters:
    
    name - the conditions record name (usually will match to table name)
    
    Returns:
    
    true if a conditions record exists with the given name
  - isFrozen
```
public boolean isFrozen()
```
    True if conditions system is frozen
    
    Returns:
    
    true if conditions system is currently frozen
  - isInitialized
```
public boolean isInitialized()
```
    True if conditions manager is properly initialized.
    
    Returns:
    
    true if the manager is initialized
  - isTestRun
```
public boolean isTestRun()
```
    Return true if Test Run configuration is active
    
    Returns:
    
    true if Test Run configuration is active
  - newCollection
```
public <CollectionType extends ConditionsObjectCollection<?>> CollectionType newCollection(Class<CollectionType> collectionType)
```
    Create a new collection with the given type.
    
    Parameters:
    
    collectionType - the collection type
    
    Returns:
    
    the new collection
  - newCollection
```
public <CollectionType extends ConditionsObjectCollection<?>> CollectionType newCollection(Class<CollectionType> collectionType,
                                                                                           String tableName)
```
    Create a new collection with the given type and table name.
    
    Parameters:
    
    collectionType - the collection type
    
    tableName - the table name
    
    Returns:
    
    the new collection
  - openConnection
```
public void openConnection()
```
    Open the database connection.
  - registerConverters
```
private void registerConverters()
```
    Register the conditions converters with the manager.
  - selectQuery
```
public ResultSet selectQuery(String query)
```
    This method can be used to perform a database SELECT query.
    
    Parameters:
    
    query - the SQL query string
    
    Returns:
    
    the ResultSet from the query
    
    Throws:
    
    RuntimeException - if there is a query error
  - setDetector
```
public void setDetector(String detectorName,
                        int runNumber)
                 throws org.lcsim.conditions.ConditionsManager.ConditionsNotFoundException
```
    This method handles changes to the detector name and run number. It is called every time an LCSim event is created, and so it has internal logic to figure out if the conditions system actually needs to be updated.
    
    Overrides:
    
    setDetector in class org.lcsim.conditions.ConditionsManagerImplementation
    
    Throws:
    
    org.lcsim.conditions.ConditionsManager.ConditionsNotFoundException
  - unfreeze
```
public void unfreeze()
```
    Un-freeze the conditions system so that updates will be received again.

Class DatabaseConditionsManager

Nested Class Summary

Nested classes/interfaces inherited from class org.lcsim.conditions.ConditionsManager

Field Summary

Fields inherited from class org.lcsim.conditions.ConditionsManagerImplementation

Constructor Summary

Method Summary

Methods inherited from class org.lcsim.conditions.ConditionsManagerImplementation

Methods inherited from class org.lcsim.conditions.ConditionsManager

Methods inherited from class java.lang.Object

Field Detail

LOG

TEST_RUN_MAX_RUN

DEFAULT_URL

DEFAULT_USER

DEFAULT_PASSWORD

MAX_ATTEMPTS

RETRY_WAIT

conditionsRecordCollection

conditionsTagCollection

connection

converters

ecalConverter

isFrozen

isInitialized

isTestRun

svtConverter

tableRegistry

tags

Constructor Detail

DatabaseConditionsManager

Method Detail

createConnection

getInstance

isTestRun

addTag

addTags

clearTags

closeConnection

collectionExists

findConditionsRecords

findTableMetaData

freeze

getActiveTags

getAvailableTags

getCollectionId

getConditionsRecords

getConditionsSeries

getConnection

getDetectorObject

getEcalConditions

getSvtConditions

hasConditionsRecord

isFrozen

isInitialized

isTestRun

newCollection

newCollection

openConnection

registerConverters

selectQuery

setDetector

unfreeze