Module conddbui :: Class CondDB
[show private | hide private]
[frames | no frames]

Class CondDB


Object allowing to manipulate a COOL database object in an LHCb way. This object contains a functions to open or create a database. It can then be manipulated either directly through the attribute 'db', or via a set of functions simplifying some operations, like creation and deletion of nodes, storage and retrieval of XML strings, etc.
Method Summary
  __init__(self, connectionString, create_new_db, defaultTag, readOnly)
Establishes the connection to the COOL database and store the object.
  closeDatabase(self)
Close the connection to the opened database...
  createDatabase(self, connectionString)
Create a new database and connect to it.
  createNode(self, path, description, storageType, versionMode, storageKeys)
Creates a new node (folder or folderset) in the database.
  createTagRelation(self, path, parentTag, tag)
Create a relation between the tag of the given node and a tag of its parent node.
  deleteNode(self, path, delete_subnodes)
Delete a node from the database permanently.
  deleteTag(self, path, tagName, delete_relations)
Delete a tag from the database, and its relations if asked for.
  deleteTagRelation(self, path, parentTag)
Delete a relation between the tag of the given node and a tag of its parent node.
  dropDatabase(cls, connectionString)
drop the database identified by the connection string. (Class method)
  generateUniqueTagName(self, baseName, reservedNames)
Generate a random tag name based on a given one.
  getAllChildNodes(self, path)
Return all the nodes of the tree lying under "path" inputs: path: string; path of the parent node.
  getAllNodes(self)
Convenience function: returns all the nodes of the database.
  getChildNodes(self, path)
Return a list of the children of the given node.
  getFolderStorageKeys(self, path)
Retrieve the keys of the Record Specification for the given folder.
  getPayload(self, path, when, channelID, tag)
Retrieve the payload of the condition object valid at a given time.
  getPayloadList(self, path, fromTime, toTime, channelID, tag)
Retrieve the payload of the condition objects valid during a given time interval.
  getTagList(self, path)
Return all the tag objects defined for the given node.
  getXMLString(self, path, when, channelID, tag, payloadKey)
Retrieve the XML string of the condition object valid at a given time.
  getXMLStringList(self, path, fromTime, toTime, channelID, tag, payloadKey)
Retrieve the payload of the condition objects valid during a given time interval.
  isSingleVersionFolder(self, path)
Check if path corresponds to a single version folder inputs: path: string; path to the node to check outputs: boolean; True if the node is a single version folder, False in all other cases (i.e.
  isTagReady(self, tagName, path)
Check if the given tag name is usable at the level of the specified path.
  openDatabase(self, connectionString, create_new_db, readOnly)
Closes the current database and connects to a new one.
  payloadToMd5(self, path, tag, initialMd5Sum)
Computes the md5 sum for the payload stored under the given node.
  recursiveTag(self, path, tagName, description, reserved)
Tag the given node and recursively tag the child nodes and their HEAD revisions with randomly generated tags.
  setDefaultTag(self, tagName)
Set the value of the default tag.
  storeXMLString(self, path, data, since, until, channelID)
Adds a new condition object to the database.
  storeXMLStringList(self, path, XMLList)
Allows to store a list of XML string into a given folder.
  tagLeafNode(self, path, tagName, description)
Apply a new tag to the head of the given folder.
  tagWithAncestorTag(self, path, ancestorTag, description)
Recursively tag (with automatically generated tag names) the given node and associate the tags with the ancestor tag given.

Instance Method Details

__init__(self, connectionString='', create_new_db=False, defaultTag='HEAD', readOnly=True)
(Constructor)

Establishes the connection to the COOL database and store the object.
inputs:
    connectionString: string; standard COOL connection string. An empty string
                      does not initialise the database handle.
                      -> Default = ''
    create_new_db:    boolean; tells the constructor what to do if the connectionString
                      doesn't open an existing database.
                      -> Default = False
    defaultTag:       string; tag which will be used by default if no other is precised.
                      -> Default = 'HEAD'
    readOnly:         boolean; open the conddb in read only mode if True, or read/write
                      mode if False.
                      -> Default = True (or False if the database is created)
outputs:
    none

closeDatabase(self)

Close the connection to the opened database
inputs:
    none
outputs:
    none

createDatabase(self, connectionString)

Create a new database and connect to it.
inputs:
    connectionString: string; standard COOL connection string.
outputs:
    none

createNode(self, path, description='', storageType='XML', versionMode='MULTI', storageKeys=['data'])

Creates a new node (folder or folderset) in the database.
inputs:
    path:        string; full path of the new node. Parents will be created if necessary.
    description: string; short description of the node.
                 -> Default = ''
    storageType: string; data type to be stored in this node, implying the type of node
                 to create. If the node is a folder, it will contain 'XML'. If it is a
                 folderset, it will contain 'NODE'.
                 -> Default = 'XML'
    versionMode: string; applies to folders only: is it multi version ('MULTI') or single
                 version ('SINGLE') ?
                 -> Default = 'MULTI'
    storageKeys: list of strings; the keys of the attribute list that will be stored in the folder.
                 -> Default = ['data']
outputs:
    none

createTagRelation(self, path, parentTag, tag)

Create a relation between the tag of the given node and a tag
of its parent node.
inputs:
    path:      string; path of the node
    parentTag: string; a tag associated to the parent node.
    tag:       string; the tag which we want to relate to the parent tag.
outputs:
    none

deleteNode(self, path, delete_subnodes=False)

Delete a node from the database permanently.
inputs:
    path:            string; node's path in the database
    delete_subnodes: boolean; only useful for fodlersets. If True, all the subnodes
                     will be destroyed as well. If False, a node can be deleted only
                     if it has no children.
                     -> Default = False

outputs:
    none

deleteTag(self, path, tagName, delete_relations=True)

Delete a tag from the database, and its relations if asked for.
inputs:
    path:             string; path to the node
    tagName:          string; name of the tag to delete
    delete_relations: boolean; this has a meaning only for folders. If True,
                      delete also the relations with the parent tag.
                      -> Default = True
outputs:
    none

deleteTagRelation(self, path, parentTag)

Delete a relation between the tag of the given node and a tag
of its parent node.
inputs:
    path:      string; path of the node
    parentTag: string; the tag we no longer want to be related to.
outputs:
    none

generateUniqueTagName(self, baseName, reservedNames=[])

Generate a random tag name based on a given one.
inputs:
    baseName:       string; idealy, this is the "parent tag" name. If this name
                    is an automatically generated one (i.e. starting with '_auto_'
                    and finishing with '-' and 6 alphanumeric characters), the
                    function will automatically strip the name from its random
                    parts.
    reservedNames:  list of strings; list of name that can't be chosen.
                    -> Default = []
outputs:
    string; the generated tag name. Its format is:
    '_auto_' + baseName + '-' + 6 random alphanumeric characters.

getAllChildNodes(self, path)

Return all the nodes of the tree lying under "path"
inputs:
    path: string; path of the parent node. Must be a folderset.
outpus:
    list of strings; the paths of all the elements of the tree under the
    given node.

getAllNodes(self)

Convenience function: returns all the nodes of the database.
inputs:
    none
outputs:
    list of strings; the paths of all the nodes of the database

getChildNodes(self, path)

Return a list of the children of the given node.
inputs:
    path: string; path of the parent node. Must be a folderset.
outputs:
    list of strings; the paths of the child nodes.

getFolderStorageKeys(self, path)

Retrieve the keys of the Record Specification for the given folder.
inputs:
    path: string; path to the folder.
outputs:
    list of strings; the list of storage keys.

getPayload(self, path, when, channelID=0, tag='')

Retrieve the payload of the condition object valid at a given time.
inputs:
    path:      string; path to the condition data in the database.
    when:      integer; time stamp (most likely an event time) at which the
               value of the condition is requested.
    channelID: integer; ID of the channel in which the condition data are
               stored.
               -> Default = 0
    tag:       string; name of the version. If empty, defaultTag is used.
               -> Default = ''
outputs:
    dictionary; the contents of the attribute list

getPayloadList(self, path, fromTime, toTime, channelID=0, tag='')

Retrieve the payload of the condition objects valid during a given time interval.
inputs:
    path:       string; path to the condition data in the database.
    fromTime:   integer; lower bound of the studied time interval.
    toTime:     integer; upper bound of the studied time interval. Note that an object
                with start of validity equal to this upper bound value will be returned
                as well.
    channelIDs: integer; IDs of the channel in which the condition data are
                stored. If None is given instead, all channels will be browsed.
                -> Default = 0
    tag:        string; name of the version. If empty, defaultTag is used.
                -> Default = ''
outputs:
    list of [dictionary, integer, integer, integer, integer]; the dictionary is the payload.
    The first two integers are the since and until values of the interval of validity. The
    third integer is the channel ID, and the last integer is the insertion time.

getTagList(self, path)

Return all the tag objects defined for the given node.
inputs:
    path: string; path to the leaf node
outputs:
    tagList: list of Tag; the list of Tag objects defined for this node.
             They contains links to their parent Tag objects.

getXMLString(self, path, when, channelID=0, tag='', payloadKey='data')

Retrieve the XML string of the condition object valid at a given time.
inputs:
    path:      string; path to the condition data in the database.
    when:      integer; time stamp (most likely an event time) at which the
               value of the condition is requested.
    channelID: integer; ID of the channel in which the condition data are
               stored.
               -> Default = 0
    tag:       string; name of the version. If empty, defaultTag is used.
               -> Default = ''
    payloadKey: string; key of the Record element we want to retrieve.
                -> Default = 'data'
outputs:
    string; the contents of the condition data.

getXMLStringList(self, path, fromTime, toTime, channelID=0, tag='', payloadKey='data')

Retrieve the payload of the condition objects valid during a given time interval.
inputs:
    path:       string; path to the condition data in the database.
    fromTime:   integer; lower bound of the studied time interval.
    toTime:     integer; upper bound of the studied time interval. Note that an object
                with start of validity equal to this upper bound value will be returned
                as well.
    channelIDs: integer; IDs of the channel in which the condition data are
                stored. If None is given instead, all channels will be browsed.
                -> Default = 0
    tag:        string; name of the version. If empty, defaultTag is used.
                -> Default = ''
    payloadKey: string; key of the record element we want to retrieve.
                -> Default = 'data'
outputs:
    list of [string, integer, integer, integer, integer]; the string is the payload.
    The first two integers are the since and until values of the interval of validity.
    The third integer is the channel ID, and the last integer is the insertion time.

isSingleVersionFolder(self, path)

Check if path corresponds to a single version folder
inputs:
    path: string; path to the node to check
outputs:
    boolean; True if the node is a single version folder, False in all other cases
   (i.e. if the node is a multi version folder OR if it is a folderset or does not
   exist).

isTagReady(self, tagName, path='/')

Check if the given tag name is usable at the level of the specified path.
inputs:
    tagName:          string; name of the tag to delete
    path:             string; path to the node
                      -> Default = '/'
outputs:
    none

openDatabase(self, connectionString, create_new_db=False, readOnly=True)

Closes the current database and connects to a new one. Creates it if asked to.
inputs:
    connectionString: string; standard COOL connection string.
    create_new_db:    boolean; if True, creates a new database on failure to
                      connect.
                      -> Default = False
    readOnly:         boolean; open the conddb in read only mode if True, or read/write
                      mode if False.
                      -> Default = True
outputs:
    none

payloadToMd5(self, path='/', tag='', initialMd5Sum=None)

Computes the md5 sum for the payload stored under the given node.
inputs:
    path:   string; path to the top of the database subtree to check.
            -> Default = '/'
    tag:    string; version of the data to check. If set to '', defaultTag
            is used. If set to 'ALL', will check all the tags associated
            to this node (NOT YET IMPLEMENTED !!)
            -> Default = ''
    md5Sum: md5 object; starting point for the check. If none is given, a
            new one is created.
            -> Default = None
outputs:
    md5 object; result from the md5 check sum.

recursiveTag(self, path, tagName, description='', reserved=None)

Tag the given node and recursively tag the child nodes and their HEAD revisions
with randomly generated tags.
inputs:
    path:         string; full path to the node
    tagName:      string; name of the tag to apply. It must be unique in the database.
    description:  string; details about the tagging operation.
                  -> Default = ''
    reserved:     list of strings; list of reserved tags.
                  -> Default = None
outputs:
    none

setDefaultTag(self, tagName)

Set the value of the default tag.
inputs:
    tagName: string; the name of the default tag.
outputs:
    none

storeXMLString(self, path, data, since, until, channelID=0)

Adds a new condition object to the database.
inputs:
    path:      string; path of the folder where the condition will be stored.
    data:      dictionary; a dictionary version of the attribute list to store in the database.
    since:     integer; lower bound of the interval of validity.
    until:     integer; upper bound of the interval of validity. It is excluded from
               the interval.
    channelID: integer; ID of the channel where to store the condition.
               -> Default: 0

outputs:
    none

storeXMLStringList(self, path, XMLList)

Allows to store a list of XML string into a given folder.
inputs:
    path:    string; the path to the folder
    XMLList: list of dictionary of 'payload': dictionary: a dictionary version of the attribute
                                                          list to store in the database.
                                   'since': integer:      the lower bound of the IOV.
                                   'until': integer:      the upper bound of the IOV.
                                   'channel': integer:    the channel ID.
outputs:
    none

tagLeafNode(self, path, tagName, description='')

Apply a new tag to the head of the given folder.
inputs:
    path:        string; full path to the folder
    tagName:     string; name of the tag to apply. It must be unique in the database.
    description: string; details about the tagging operation.
                 -> Default = ''
outputs:
    none

tagWithAncestorTag(self, path, ancestorTag, description='')

Recursively tag (with automatically generated tag names) the given node and
associate the tags with the ancestor tag given.
inputs:
    path:        string; path of the node to tag
    ancestorTag: string; tag to associate the node with. It must be an existing
                 tag and a relation must exist with the parent of the given node.
                 Otherwise, an exception is raised.
    description: string; description to associate with the tagged elements. If empty,
                 the description of the closest ancestor tag will be used.
                 -> Default = ''
outputs:
    none

Class Method Details

dropDatabase(cls, connectionString)

drop the database identified by the connection string.
inputs:
    connectionString: string; standard COOL connection string.
outputs:
    none

Generated by Epydoc 2.1 on Tue Mar 6 18:29:23 2007 http://epydoc.sf.net