include/GaudiKernel/IDataManagerSvc.h

0001 /***********************************************************************************\
0002 * (c) Copyright 1998-2025 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_IDATAMANAGERSVC_H
0012 #define GAUDIKERNEL_IDATAMANAGERSVC_H
0013
0014 // Include files
0015 #include <GaudiKernel/ClassID.h>
0016 #include <GaudiKernel/IDataStoreAgent.h>
0017 #include <GaudiKernel/IInterface.h>
0018 #include <string>
0019 #include <string_view>
0020 #include <vector>
0021
0022 // Forward declarations
0023 // Generic interface to data object class
0024 #include <GaudiKernel/DataObject.h>
0025 // Interface to persistency service
0026 class IConversionSvc;
0027 // Opaque addresses
0028 class IOpaqueAddress;
0029 // Registry entry definition
0030 class IRegistry;
0031 // Data provider svc
0032 class IDataProviderSvc;
0033
0034 /** @class IDataManagerSvc IDataManagerSvc.h GaudiKernel/IDataManagerSvc.h
0035
0036     <P>The data manager interface of the service allows to:
0037     <UL>
0038     <LI> Discard sub-trees or the entire data stored.
0039     <LI> Initialize the top level root used for navigation.
0040     <LI> Access the tree information of the data store:
0041          Given a reference to a store object, which can be identified by
0042          path, pointer or reference to the registry entry, it is possible
0043          to retrieve the parent object and to access iterators over the
0044          leaf entries.
0045     <LI> Register addresses to the data store.
0046          Registered addresses contain the retrieve information for the
0047          underlying object.
0048     <LI> Unregister addresses from the data store. The object will no longer be
0049          accessible and loadable.
0050     </UL>
0051
0052    @author Markus Frank
0053    @version 1.0
0054 */
0055 struct GAUDI_API IDataManagerSvc : extend_interfaces<IInterface> {
0056   /// InterfaceID
0057   DeclareInterfaceID( IDataManagerSvc, 4, 0 );
0058
0059   /// Get class ID of root Event
0060   virtual CLID rootCLID() const = 0;
0061
0062   /// Get Name of root Event
0063   virtual const std::string& rootName() const = 0;
0064
0065   /** Pass a default data loader to the service. This service will be
0066       asked to load non existant data items.
0067       @param      svc        [IN] Pointer to persistency service instance
0068       @param      dpsvc      [IN] Pointer to data provider instance (optional)
0069       @return                     Status code indicating success or failure
0070   */
0071   virtual StatusCode setDataLoader( IConversionSvc* svc, IDataProviderSvc* dpsvc = nullptr ) = 0;
0072
0073   /** IDataManagerSvc: Explore the object store: retrieve the object's parent.
0074       The object is identified by its pointer.
0075       @param      pObject     [IN] Pointer to the object.
0076       @param      refpParent [OUT] Reference to store the parent's registry entry.
0077       @return                      Status code indicating success or failure.
0078   */
0079   virtual StatusCode objectParent( const DataObject* pObject, IRegistry*& refpParent ) = 0;
0080
0081   /** IDataManagerSvc: Explore the object store: retrieve the object's parent.
0082       The object is identified by the pointer to the registry entry.
0083       @param      pRegistry   [IN] Pointer to the object.
0084       @param      refpParent [OUT] Reference to store the parent's registry entry.
0085       @return                      Status code indicating success or failure.
0086   */
0087   virtual StatusCode objectParent( const IRegistry* pRegistry, IRegistry*& refpParent ) = 0;
0088
0089   /** Explore the object store: retrieve all leaves attached to the object
0090       The object is identified by its pointer.
0091       Allow to access and browse the leaf objects of the identified object.
0092       @param      pObject    [IN] Pointer to the object.
0093       @param      refLeaves  [OUT] Reference to storage location, where
0094                                   the objects leaves should be stored.
0095       @return                     Status code indicating success or failure.
0096   */
0097   virtual StatusCode objectLeaves( const DataObject* pObject, std::vector<IRegistry*>& refLeaves ) = 0;
0098
0099   /** Explore the object store: retrieve all leaves attached to the object
0100       The object is identified by the pointer to the registry entry.
0101       Allow to access and browse the leaf objects of the identified object.
0102       @param      pRegistry  [IN] Pointer to the registry of the obejct.
0103       @param      refLeaves  [OUT] Reference to storage location, where
0104                                   the objects leaves should be stored.
0105       @return                     Status code indicating success or failure.
0106   */
0107   virtual StatusCode objectLeaves( const IRegistry* pRegistry, std::vector<IRegistry*>& refLeaves ) = 0;
0108
0109   /** Remove all data objects below the sub tree identified by its full path name.
0110       @param      sub_path   [IN] Path to sub-tree node.
0111       @return                     Status code indicating success or failure.
0112   */
0113   virtual StatusCode clearSubTree( std::string_view sub_path ) = 0;
0114
0115   /** Remove all data objects below the sub tree
0116       identified by the object. The object itself is removed as well.
0117       @param      pObject    [IN] Pointer to object
0118       @return                     Status code indicating success or failure
0119   */
0120   virtual StatusCode clearSubTree( DataObject* pObject ) = 0;
0121
0122   /** Remove all data objects in the data store.
0123       @return                     Status code indicating success or failure
0124   */
0125   virtual StatusCode clearStore() = 0;
0126
0127   /** Analyse by traversing all data objects below the sub tree identified by its full path name.
0128       @param      sub_path   [IN] Path to sub-tree node.
0129       @return                     Status code indicating success or failure.
0130   */
0131   virtual StatusCode traverseSubTree( std::string_view sub_tree_path, IDataStoreAgent* pAgent ) = 0;
0132
0133   /** Analyse by traversing all data objects below the sub tree identified by its full path name.
0134       @param      sub_path   [IN] Path to sub-tree node.
0135       @param      f          [IN] callable which will be called for each data object
0136                                   it should have the signature bool(IRegistry*,int level)
0137       @return                     Status code indicating success or failure.
0138   */
0139   template <typename F>
0140     requires( !std::is_convertible_v<F, IDataStoreAgent*> )
0141   StatusCode traverseSubTree( std::string_view sub_path, F&& f ) {
0142     auto agent = makeDataStoreAgent( std::forward<F>( f ) );
0143     return traverseSubTree( sub_path, &agent );
0144   }
0145
0146   /** Analyse by traversing all data objects below the sub tree
0147       identified by the object. The object itself is removed as well.
0148       @param      pObject    [IN] Pointer to object
0149       @param      pAgent     [IN] Pointer to the datastore agent traversing the store
0150       @return                     Status code indicating success or failure
0151   */
0152   virtual StatusCode traverseSubTree( DataObject* pObject, IDataStoreAgent* pAgent ) = 0;
0153
0154   /** Analyse by traversing all data objects below the sub tree
0155       identified by the object. The object itself is removed as well.
0156       @param      pObject    [IN] Pointer to object
0157       @param      f          [IN] Callable which will be called on each data object
0158                                   it should have the signature bool(IRegistry*,int level)
0159       @return                     Status code indicating success or failure
0160   */
0161   template <typename F>
0162     requires( !std::is_convertible_v<F, IDataStoreAgent*> )
0163   StatusCode traverseSubTree( DataObject* pObject, F&& f ) {
0164     auto agent = makeDataStoreAgent( std::forward<F>( f ) );
0165     return traverseSubTree( pObject, &agent );
0166   }
0167
0168   /** Analyse by traversing all data objects in the data store.
0169       @return     Status code indicating success or failure
0170   */
0171   virtual StatusCode traverseTree( IDataStoreAgent* pAgent ) = 0;
0172
0173   /** Analyse by traversing all data objects in the data store.
0174       @param      f          [IN] callable which will be called for each data object
0175                                   it should have the signature bool(IRegistry*,int level)
0176       @return     Status code indicating success or failure
0177   */
0178   template <typename F>
0179     requires( !std::is_convertible_v<F, IDataStoreAgent*> )
0180   StatusCode traverseTree( F&& f ) {
0181     auto agent = makeDataStoreAgent( std::forward<F>( f ) );
0182     return traverseTree( &agent );
0183   }
0184
0185   /** Initialize data store for new event by giving new event path.
0186       Implicitly this clears the entire data store.
0187       @param      root_name  [IN] String containing root path name
0188       @param      pObject    [IN] Pointer to root node object
0189       @return                     Status code indicating success or failure
0190   */
0191   virtual StatusCode setRoot( std::string root_name, DataObject* pObject ) = 0;
0192
0193   /** Initialize data store for new event by giving new event path.
0194       Implicitly this clears the entire data store.
0195       @param      root_name  [IN] String containing root path name
0196       @param      pRootAddr  [IN] Pointer to opaque root node address
0197       @return                     Status code indicating success or failure
0198   */
0199   virtual StatusCode setRoot( std::string root_path, IOpaqueAddress* pRootAddr ) = 0;
0200
0201   /** Register object address with the data store.
0202      Connect the object identified by its pointer to the node object
0203      identified by its path.
0204      @param      fullPath    [IN] Path to parent node of the object.
0205      @param      pAddress    [IN] Pointer to the object to be registered.
0206       @return                     Status code indicating success or failure.
0207   */
0208   virtual StatusCode registerAddress( std::string_view fullPath, IOpaqueAddress* pAddress ) = 0;
0209
0210   /** Register object address with the data store.
0211       Connect the object identified by its pointer to the parent object
0212       and the relative path of the object with respect to the parent.
0213       @param      parentObj  [IN] Pointer to parent object.
0214       @param      objectPath [IN] Path of the object relative to the parent node
0215       @param      pAddress   [IN] Pointer to the object to be connected.
0216       @return                     Status code indicating success or failure.
0217   */
0218   StatusCode registerAddress( DataObject* parentObj, std::string_view objectPath, IOpaqueAddress* pAddress ) {
0219     return registerAddress( parentObj ? parentObj->registry() : nullptr, objectPath, pAddress );
0220   }
0221
0222   /** Register object address with the data store.
0223       Connect the object identified by its pointer to the parent object
0224       and the relative path of the object with respect to the parent.
0225       @param      parentObj  [IN] Pointer to parent object.
0226       @param      objectPath [IN] Path of the object relative to the parent node
0227       @param      pAddress   [IN] Pointer to the object to be connected.
0228       @return                     Status code indicating success or failure.
0229   */
0230   virtual StatusCode registerAddress( IRegistry* parentObj, std::string_view objectPath, IOpaqueAddress* pAddress ) = 0;
0231
0232   /** Unregister object address from the data store.
0233       The object is identified by full path name.
0234       @param      fullPath [IN] Path name of the object.
0235       @return                   Status code indicating success or failure.
0236   */
0237   virtual StatusCode unregisterAddress( std::string_view fullPath ) = 0;
0238
0239   /** Unregister object address from the data store.
0240       The object is identified by parent object and the path of the
0241       object relative to the parent.
0242       @param      pParent  [IN] Pointer to parent object.
0243       @param      objPath  [IN] Path name of the object relative to the parent.
0244       @return                   Status code indicating success or failure.
0245   */
0246   StatusCode unregisterAddress( DataObject* pParent, std::string_view objPath ) {
0247     return unregisterAddress( pParent ? pParent->registry() : nullptr, objPath );
0248   }
0249
0250   /** Unregister object address from the data store.
0251       The object is identified by parent object and the path of the
0252       object relative to the parent.
0253       @param      pParent  [IN] Pointer to parent object.
0254       @param      objPath  [IN] Path name of the object relative to the parent.
0255       @return                   Status code indicating success or failure.
0256   */
0257   virtual StatusCode unregisterAddress( IRegistry* pParent, std::string_view objPath ) = 0;
0258 };
0259
0260 #endif // GAUDIKERNEL_IDATAMANAGERSVC_H