BABARConditions Database
Application Programmer Interface
BABAR Computing
Version Information
Draft: 4th April 1997
This document is still under development. If you have any questions or comments, please address them to the author.
This document describes the mechanism whereby data may be stored and retrieved from the BABARConditions Database. Such data describes the state of some aspect of the detector for a time interval over which it was stable. Each event is tagged with a time-stamp and this is used to access the
conditions information relevant for events within the time interval. Conditions information includes electronic calibration and alignment as well as other detector conditions such as the trigger and HV settings etc.
In order to isolate the application programmer as much as possible from the underlying database technology, they interact with a transient environment object from which objects can be accessed in a type-safe fashion.
Furthermore, it is often the case that the object-level information necessary for reconstruction is derived from several different calibrations etc. For example, the gain for the EMC for a single channel is derived from several different calibrations,
some involving feedback from physics data. Each of these calibrations might have a different time validity interval so that the information for each channel has to be checked against multiple intervals. The access with the environment object performs this
checking and any recalculation transparently to the application programmer.
This document describes the mechanism whereby data may be associated with the BABAR environment. The reconstruction or analysis programmer
(referred to as the client for the remainder of this document) is presented with the appearance of a transient environment from which transient objects can be accessed or stored in a type-safe fashion. This transient event acts as a conduit to an
underlying conditions database containing persistent objects. This decouples the client from the database and its persistent objects. This has the following advantages:
- The client has access to a conventional C++ API, whereas the persistent class programmer must cope with persistent class restrictions and language extensions.
- The client is presented with a flat environment structure, whereas the persistent information may be organized in a very hierarchical manner in order to optimize placement of data within the database. The placement
strategies and implementations can be modified with no change in the client code.
- The mapping between a transient object and its persistent equivalent may be complex, allowing compression of the data or merging of separate transient objects into single persistent ones in order to optimize the storage
within the database.
- Transient objects may be used to cache information in order to improve performance without incurring a space penalty in the persistent store.
For each object type (class) within the environment, several C++ classes and functions are necessary in order to maintain this decoupling:
- A transient class (T). This is the class that is used by the reconstruction or analysis code itself. Single instances of these classes may be associated with the environment, in which case they are required to
inherit from a base class that is detailed below (AbsEnvObj), or a list of instances may be associated with the environment, in which case the collection class detailed below (IfdHepAList<T>) must be used.
- A persistent class (TP). Objects of this class can be retained in the persistent conditions database. They generally have a one-to-one relationship with the equivalent transient class but have to obey more
stringent rules and are generally simpler, consisting of only data members and accessors. These persistent classes must inherit from a base class (BdbObject).
- A proxy class. An instance of this proxy must be created and used when associating the transient class with the event. It must be of type IfdDataProxy<T> or a descendant class thereof. In the former case
fault and store handlers may be associated with the transient object by specifying handler functions in the proxy constructor, while in the latter case these handlers are specified by redefining the default fault and store member functions associated with
the class. The fault handler is used to locate the persistent object within the database (or indicate that it doesn't exist), and create the equivalent transient object, setting its data members according to the persistent information. This transient
object is associated with the transient environment so that it can subsequently be retrieved as needed without invoking this handler. The store handler creates the persistent object if it doesn't already exist, sets its persistent information from the
data members of the transient object.
Thus there is a conceptual separation between the client for an object within the environment, who is only aware of the transient event and object, and the interface developer who is responsible for developing the classes
and proxies described above. This document describes the programming conventions that must be obeyed by doth developers, but focusses upon the interface developer. It should be read in the context of the AbsEnv User Guide document [does this
exist?] that describes in more detail the interfaces to the underlying dictionaries.
Return to Table of Contents.
The BABAR application framework (the Framework
package) makes the transient event available to modules as a global object:
AbsEnv* gblEnv;
The transient environment is an example of a Proxy or Interface Dictionary (i.e. it inherits from IfdProxyDict). The only access to entities within the environment is via the templated class Ifd<T> which provides access (both to fetch and store information) in a type-safe manner.
Return to Table of Contents.
Keys (IfdKey, IfdIntKey & IfdStrKey)
If multiple instances of objects from the same class are to be separately associated with the event, rather than being contained within a list, they must be identified by a unique key. The underlying ProxyDict classes
support several types of key (based on an abstract parent, IfdKey), but two are of interest for the client programmer, integer keys (IfdIntKey) and string keys (IfdStrKey).
IfdKey
Description
This class provides an abstract interface for keys. It is the parent of the key class hierarchy.
Inheritance Tree
IfdKey
Interface
#include "ProxyDict/IfdKey.hh"
Constructors
This class presents a pure interface and cannot be directly instantiated.
IfdIntKey
Description
This class provides an implementation of the IfdKey interface for integer keys.
Inheritance Tree
IfdIntKey > IfdKey
Interface
#include "ProxyDict/IfdIntKey.hh"
Constructors
IfdIntKey( const int i )
IfdStrKey
Description
This class provides an implementation of the IfdKey interface for string keys.
Inheritance Tree
IfdStrKey > IfdKey
Interface
#include "ProxyDict/IfdStrKey.hh"
Constructors
IfdStrKey( const HepString& s )
Return to Table of Contents.
Description
This class provides type-safe (templated) access to the objects within the transient environment.
Inheritance Tree
Ifd<T>
Interface
#include "ProxyDict/Ifd.hh"
Constructors
This class contains static member functions only. It cannot be instantiated.
Selectors
T* Ifd<T>::get( AbsEnv* env )
T* Ifd<T>::get( AbsEnv* env, const IfdKey &k )
This templated function accesses objects within the environment. Such objects may optionally be identified by a key to differentiate them from other instances of the same class. The function value will be set to NULL if the
desired object does not exist within the environment.
Arguments
AbsEnv* env The transient environment.IfdKey& k The optional key (see section on keys).
Modifiers
bool Ifd<T>::put( AbsEnv* env, IfdDataProxy<T>* p )
bool Ifd<T>::put( AbsEnv* env, IfdDataProxy<T>* p, const IfdKey& k )
This templated function adds objects to the environment. Such objects may optionally be identified by a secondary key if multiple instances of objects of the same class are to be directly associated with the event (rather
than residing in a list). The function value will be set to true if the object is successfully added to the event.
Arguments
AbsEnv* env The transient environment.IfdDataProxy<T>* p The proxy corresponding to the data to be added to the environment.IfdKey& k The optional key (see section on keys).
Return to Table of Contents.
Description
Single instances of classes associated with the environment (as opposed to lists of such instances) must inherit from the AbsEnvObj class.
Inheritance Tree
AbsEnvObj > IfdData
Interface
#include "AbsEnv/AbsEnvObj.hh"
Constructors
AbsEnvObj( ) The constructor is protected and is only accessible from descendant classes.
Selectors
Refer to header file.
Modifiers
Refer to header file.
Operations
Refer to header file.
Return to Table of Contents.
This section will be extended to include the Rogue Wave collection classes (or IfdData-compatible descendants thereof). Currently only the IfdHepAList<T> CLHEP-compatible class is implemented.
Description
Collections associated with the transient environment must be instances of this templated class.
Inheritance Tree
IfdHepAList<T> > HepAList<T>, IfdData
Interface
#include "ProxyDict/IfdHepAList.hh"
Constructors
IfdHepAList( ) Construct an empty list (a list with no objects)
Selectors
These are detailed in the interface description for HepAList<T>.
Modifiers
These are detailed in the interface description for HepAList<T>.
Operations
These are detailed in the interface description for HepAList<T>.
Return to Table of Contents.
Description
For each transient object of type T (inheriting from AbsEnvObj), a proxy object of type IfdDataProxy<T> (or a descendant thereof) must be instantiated. This proxy object must define fault and store
handlers for the transient/persistent object pair. If of type IfdDataProxy<T>, fault and store handlers may be associated with the transient object by specifying handler functions in the constructor of this class. If of a descendant class of
IfdDataProxy<T>, these handlers are specified by redefining the default fault and store member functions associated with the IfdDataProxy<T> class.
Inheritance Tree
IfdDataProxy<T>
Interface
#include "ProxyDict/IfdDataProxy.hh"
Constructors
IfdDataProxy( T* myT )
Construct a proxy that holds an already existing T*.
IfdDataProxy( T* (*f)( IfdProxyDict* d, const IfdKey& k), bool (*f)( IfdProxyDict*d, T* theT ) )
Construct a proxy using the specified fault (first argument) and store (second argument) handler functions.
Selectors
IfdData* get( const IfdKey& k )
Modifiers
None.
Operations
T* fault( IfdProxyDict* d, const IfdKey& k )
Default fault handler. The first argument (IfdProxyDict* d) is the current proxy dictionary (transient environment in this case), and the second argument (const IfdKey& k) is the secondary key as specified
in the Ifd<T>::get() request. This default handler just returns a NULL object and should be redefined in descendant classes or specified in the constructor of this class.
bool store( IfdProxyDict* d, T* theT )
Default store handler. The first argument (IfdProxyDict* d) is the current proxy dictionary (transient environment in this case), and the second argument (T* theT) is transient object as specified in the
Ifd<T>::put() request. This default handler is empty and should be redefined in descendant classes or specified in the constructor of this class.
void invalidateCache( )
Return to Table of Contents.
In the situation where a data member in one class is a pointer to another class, special care must be taken to ensure that the destination transient object exists by the time the pointer is traversed. A smart pointer
(IfdPtr<T>) performs this operation. [section incomplete]
Inheritance Tree
IfdPtr<T>[the name will probably change]
Interface
#include "ProxyDict/IfdPtr.hh"
Constructors
[this section is missing.]
Selectors
[this section is missing.]
Modifiers
[this section is missing.]
Operations
[this section is missing.]
Return to Table of Contents.
There is a problem when elements in a list belong not to a single class, but to different classes that all inherit from the same parent. First, the type of each element cannot intrinsically be determined by the fault
handler, and second, the persistent collection classes can only store such polymorphic elements in a HepRefVector(P) list. If the elements are
small objects there is potentially a large space overhead in the database.
We do not currently have a solution to this. Possibilities are:
- Implement ad hoc run-time typing for the list elements. This could be an enum defining a type-id for each subclass, or a set of dynamic_cast classes & functions that attempt to replicate the C++ standard
dynamic_cast<T> operation. Both of these have the disadvantage that they need to be explicitly extended each time a new sub-class is implemented.
- Store the persistent objects in different HepVector(P) lists, each corresponding to a different subclass. This would avoid the database space overhead.
Return to Table of Contents.
Description
All persistent conditions objects must inherit from BdbObject. The coding rules for them are discussed in the draft BABAR DDL Coding Guidelines and
Hints.
Inheritance Tree
BdbObject
Interface
#include "BdbCond/BdbObject.hh"
Constructors
[This section incomplete.]
Selectors
[This section incomplete.]
Modifiers
[This section incomplete.]
Operations
[This section incomplete.]
Return to Table of Contents.
Description
Classes for persistent environment collections. The HepVector(P) class implements an extensible vector of objects of persistent capable objects of type P. The HepRefVector(P) class implements an extensible
vector of references to persistent capable objects of type P. In both cases the objects to be associated with the persistent collections must themselves inherit from the d_Object class. The HepRefVector class has the advantage that the
elements exist as separate objects within the database and can be located elsewhere within the database so as to optimize access to them.
Inheritance Tree
HepVector(P)
HepRefVector(P)
Interface
#include "RD45/Hep.h"
Constructors
[This section incomplete.]
Selectors
[This section incomplete.]
Modifiers
[This section incomplete.]
Operations
[This section incomplete.]
Return to Table of Contents.
Description
[This section incomplete.]
Return to Table of Contents
Description
This example demonstrates use of the API.
[Example missing]
DB Home | BaBar Home | Computing | Reconstruction | Simulation |
Search
DRQuarrie@LBL.Gov
|
