include/GaudiKernel/INTupleSvc.h

0001 /***********************************************************************************\
0002 * (c) Copyright 1998-2019 CERN for the benefit of the LHCb and ATLAS collaborations *
0003 *                                                                                   *
0004 * This software is distributed under the terms of the Apache version 2 licence,     *
0005 * copied verbatim in the file "LICENSE".                                            *
0006 *                                                                                   *
0007 * In applying this licence, CERN does not waive the privileges and immunities       *
0008 * granted to it by virtue of its status as an Intergovernmental Organization        *
0009 * or submit itself to any jurisdiction.                                             *
0010 \***********************************************************************************/
0011 #ifndef GAUDIKERNEL_INTUPLESVC_H
0012 #define GAUDIKERNEL_INTUPLESVC_H
0013
0014 // Framework include files
0015 #include "GaudiKernel/ClassID.h"
0016 #include "GaudiKernel/IDataProviderSvc.h"
0017
0018 // Forward declarations
0019 namespace NTuple {
0020   class Tuple;
0021   struct Directory;
0022 } // namespace NTuple
0023
0024 /** @class INTupleSvc INTupleSvc.h GaudiKernel/INTupleSvc.h
0025
0026     <P>The ntuple service interface allows to:
0027     <UL>
0028     <LI> Export the data provider's functionality.
0029     <LI> Extend the functionality in order
0030          to book abstract N tuples:
0031          <UL>
0032          <LI> Book COLUMN WISE N tuples.
0033          <LI> Book ROW WISE N tuples.
0034          <LI> Access a persistent N tuple within a file
0035          <LI> Save the N tuple after filling.
0036          <LI> Write individual records from to a N tuple.
0037          <LI> Read individual records from an existing N tuple.
0038          </UL>
0039          created N tuples are automatically put onto the
0040          N tuple data store.
0041     </UL>
0042
0043    @author Markus Frank
0044    @version 1.0
0045 */
0046 class GAUDI_API INTupleSvc : virtual public IDataProviderSvc {
0047 public:
0048   /// InterfaceID
0049   DeclareInterfaceID( INTupleSvc, 2, 0 );
0050   /// Create requested N tuple (Hide constructor)
0051   virtual StatusCode create( const CLID& typ, const std::string& title, NTuple::Tuple*& refpTuple ) = 0;
0052   /** Book Ntuple and register it with the data store.
0053       Connects the object identified by its full path to the parent object
0054       identified by the base name of the full path.
0055       @param      fullPath    Full path to the node of the object.
0056       @param      type        Class ID of the N tuple: Column or row wise.
0057       @param      title       Title property of the N tuple.
0058       @param      refpTuple   Reference to pointer to the N tuple to be booled and registered.
0059       @return                 Status code indicating success or failure.
0060   */
0061   virtual NTuple::Tuple* book( const std::string& fullPath, const CLID& type, const std::string& title ) = 0;
0062   /** Book Ntuple and register it with the data store.
0063       Connects the object identified by its relative path to the parent object
0064       identified by the base name.
0065       @param      dirPath     Path to parent node of the object.
0066       @param      relPath     Relative path to the object with respect to the parent node.
0067                               The relative path is the identifier of the tuple.
0068       @param      title       Title property of the N tuple.
0069       @param      type        Class ID of the N tuple: Column or row wise.
0070       @param      refpTuple   Reference to pointer to the N tuple to be booled and registered.
0071       @return                 Status code indicating success or failure.
0072   */
0073   virtual NTuple::Tuple* book( const std::string& dirPath, const std::string& relPath, const CLID& type,
0074                                const std::string& title ) = 0;
0075   /** Book Ntuple and register it with the data store.
0076       Connects the object identified by an identifier to the parent object
0077       identified by the base name.
0078       @param      dirPath     Path to parent node of the object.
0079       @param      id          Identifier of the tuple within the parent's directory.
0080       @param      type        Class ID of the N tuple: Column or row wise.
0081       @param      title       Title property of the N tuple.
0082       @param      refpTuple   Reference to pointer to the N tuple to be booled and registered.
0083       @return                 Status code indicating success or failure.
0084   */
0085   virtual NTuple::Tuple* book( const std::string& dirPath, long id, const CLID& type, const std::string& title ) = 0;
0086   /** Book Ntuple and register it with the data store.
0087       Connects the object identified by an identifier (id) to the parent object
0088       identified by the parent's pointer.
0089       @param      pParent     Pointer to parent object.
0090       @param      relPath     Relative path to the object with respect to the parent node.
0091                               The relative path is the identifier of the tuple.
0092       @param      type        Class ID of the N tuple: Column or row wise.
0093       @param      title       Title property of the N tuple.
0094       @param      refpTuple   Reference to pointer to the N tuple to be booled and registered.
0095       @return                 Status code indicating success or failure.
0096   */
0097   virtual NTuple::Tuple* book( DataObject* pParent, const std::string& relPath, const CLID& type,
0098                                const std::string& title ) = 0;
0099   /** Book Ntuple and register it with the data store.
0100       Connects the object identified by its relative path to the parent object
0101       identified by the parent's pointer.
0102       @param      pParent     Pointer to parent object.
0103       @param      id          Identifier of the tuple within the parent's directory.
0104       @param      type        Class ID of the N tuple: Column or row wise.
0105       @param      title       Title property of the N tuple.
0106       @return                 Status code indicating success or failure.
0107   */
0108   virtual NTuple::Tuple* book( DataObject* pParent, long id, const CLID& type, const std::string& title ) = 0;
0109   /** Create Ntuple directory and register it with the data store.
0110       Connects the object identified by its relative path to the parent object
0111       identified by the parent's pointer.
0112       @param      pParent     Pointer to parent object.
0113       @param      title       Directory identifier.
0114       @return                 Status code indicating success or failure.
0115   */
0116   virtual NTuple::Directory* createDirectory( DataObject* pParent, const std::string& title ) = 0;
0117   /** Create Ntuple directory and register it with the data store.
0118       Connects the object identified by its relative path to the parent object
0119       identified by the parent's pointer.
0120       @param      pParent     Pointer to parent object.
0121       @param      id          Identifier of the tuple within the parent's directory.
0122       @return                 Status code indicating success or failure.
0123   */
0124   virtual NTuple::Directory* createDirectory( DataObject* pParent, long id ) = 0;
0125   /** Create Ntuple directory and register it with the data store.
0126       Connects the object identified by its relative path to the parent object
0127       identified by the parent's pointer.
0128       @param      dirPath     Full directory path to parent
0129       @param      id          Identifier of the tuple within the parent's directory.
0130       @return                 Status code indicating success or failure.
0131   */
0132   virtual NTuple::Directory* createDirectory( const std::string& dirPath, long id ) = 0;
0133   /** Create Ntuple directory and register it with the data store.
0134       Connects the object identified by its path to the parent object
0135       identified by the parent's path.
0136       @param      dirPath     Full directory path to parent
0137       @param      title       Directory identifier.
0138       @return                 Status code indicating success or failure.
0139   */
0140   virtual NTuple::Directory* createDirectory( const std::string& dirPath, const std::string& title ) = 0;
0141   /** Create Ntuple directory and register it with the data store.
0142       @param      fullPath    Full directory path
0143       @return                 Status code indicating success or failure.
0144   */
0145   virtual NTuple::Directory* createDirectory( const std::string& fullPath ) = 0;
0146   /** Access N tuple on disk.
0147       @param    fullPath    Full path to the N tuple within the transient store
0148       @param    filename    Name of the file the ntuple resides in.
0149       @return               Status code indicating success or failure.
0150   */
0151   virtual NTuple::Tuple* access( const std::string& fullPath, const std::string& filename ) = 0;
0152
0153   /** Save N tuple to disk. Must be called in order to close the ntuple file properly
0154       @param    fullPath    Full path to the N tuple in memory.
0155       @return               Status code indicating success or failure.
0156   */
0157   virtual StatusCode save( const std::string& fullPath ) = 0;
0158
0159   /** Save N tuple to disk. Must be called in order to close the ntuple file properly
0160       @param    tuple       Pointer to the Ntuple in memory
0161       @return               Status code indicating success or failure.
0162   */
0163   virtual StatusCode save( NTuple::Tuple* tuple ) = 0;
0164
0165   /** Save N tuple to disk. Must be called in order to close the ntuple file properly
0166       @param    pParent     Parent object of the N tuple
0167       @param    relPath     Relative path to the N tuple in memory with respect to the
0168                             parent object.
0169       @return               Status code indicating success or failure.
0170   */
0171   virtual StatusCode save( DataObject* pParent, const std::string& relPath ) = 0;
0172
0173   /** Write single record to N tuple.
0174       @param    tuple       Pointer to the Ntuple in memory
0175       @return               Status code indicating success or failure.
0176   */
0177   virtual StatusCode writeRecord( NTuple::Tuple* tuple ) = 0;
0178
0179   /** Write single record to N tuple.
0180       @param    fullPath    Full path to the N tuple in memory.
0181       @return               Status code indicating success or failure.
0182   */
0183   virtual StatusCode writeRecord( const std::string& fullPath ) = 0;
0184
0185   /** Write single record to N tuple.
0186       @param    pParent     Parent object of the N tuple
0187       @param    relPath     Relative path to the N tuple in memory with respect to the
0188                             parent object.
0189       @return               Status code indicating success or failure.
0190   */
0191   virtual StatusCode writeRecord( DataObject* pParent, const std::string& relPath ) = 0;
0192
0193   /** Read single record from N tuple.
0194       @param    tuple       Pointer to the Ntuple in memory
0195       @return               Status code indicating success or failure.
0196   */
0197   virtual StatusCode readRecord( NTuple::Tuple* tuple ) = 0;
0198
0199   /** Read single record from N tuple.
0200       @param    fullPath    Full path to the N tuple in memory.
0201       @return               Status code indicating success or failure.
0202   */
0203   virtual StatusCode readRecord( const std::string& fullPath ) = 0;
0204
0205   /** Read single record from N tuple.
0206       @param    pParent     Parent object of the N tuple
0207       @param    relPath     Relative path to the N tuple in memory with respect to the
0208                             parent object.
0209       @return               Status code indicating success or failure.
0210   */
0211   virtual StatusCode readRecord( DataObject* pParent, const std::string& relPath ) = 0;
0212 };
0213
0214 #endif // INTERFACES_INTUPLESVC_H