Logo ROOT   6.12/07
Reference Guide
TVirtualRefProxy.h
Go to the documentation of this file.
1 // @(#)root/meta: $Id$
2 // Author: Markus Frank 20/05/2005
3 
4 /*************************************************************************
5  * Copyright (C) 1995-2006, Rene Brun and Fons Rademakers. *
6  * All rights reserved. *
7  * *
8  * For the licensing terms see $ROOTSYS/LICENSE. *
9  * For the list of contributors see $ROOTSYS/README/CREDITS. *
10  *************************************************************************/
11 #ifndef ROOT_TVirtualRefProxy
12 #define ROOT_TVirtualRefProxy
13 
14 // Framework include files
15 #include "Rtypes.h" // ROOT_Rtypes
16 
17 // Forward declarations
18 class TClass;
20 
21 //______________________________________________________________________________
22 //
23 // Abstract proxy definition to follow reference objects.
24 //
25 //
26 // Generic Mechanism for Object References
27 // =======================================
28 //
29 // References are a well known mechanism to support persistency
30 // of entities, which in C++ typically are represented as
31 // pointers. The generic mechanism allows clients to supply
32 // hooks to the ROOT framework in interactive mode in order to
33 // dereference these objects and access the objects pointed to by
34 // the reference objects.
35 //
36 // Implementations are supplied for ROOT own reference mechanism
37 // based on instances of the TRef and the TRefArray classes.
38 //
39 // To support generality this mechanism was implemented using a
40 // proxy mechanism, which shields the concrete implementation of the
41 // reference classes from ROOT. Hence, this mechanism also works for
42 // references as they are supported by the POOL persistency framework
43 // and by frameworks like Gaudi.
44 //
45 // To enable reference support a concrete sub-class instance of
46 // the TVirtualRefProxy base class must be attached to the TClass
47 // instance representing the reference itself. Please see the
48 // header- and implementation file TRefProxy.h/cxx for details.
49 // For ROOT's own references this is done simply by a call like:
50 //
51 // #include "TROOT.h"
52 // #include "TClass.h"
53 // #include "TRefProxy.h"
54 //
55 // ...
56 // gROOT->GetClass("TRef")->AdoptReferenceProxy(new TRefProxy());
57 //
58 // - GetObject() must return the pointer to the referenced
59 // object. TTreeFormula then figures out how to access the
60 // value to be plotted.
61 // Hence, the actual work is done inside a call to:
62 //
63 // void* TRefProxy::GetObject(TFormLeafInfoReference* info, void* data, int)
64 // {
65 // if ( data ) {
66 // TRef* ref = (TRef*)((char*)data + info->GetOffset());
67 // // Dereference TRef and return pointer to object
68 // void* obj = ref->GetObject();
69 // if ( obj ) { return obj; }
70 //
71 // ... else handle error or implement failover ....
72 //
73 //
74 // The type of the referenced object must either be known at compilation
75 // time or it must be possible to guess it reading the first TTree entry.
76 // In this case the following conditions must be met:
77 // - GetValueClass() must return the TClass to the referenced
78 // objects (or a base class)
79 //
80 //______________________________________________________________________________
82 public:
83  // Virtual Destructor
84  virtual ~TVirtualRefProxy() {};
85 
86  // Release the reference proxy (virtual destructor)
87  virtual void Release() = 0;
88 
89  // Clone the reference proxy (virtual constructor)
90  virtual TVirtualRefProxy* Clone() const = 0;
91 
92  // Setter of reference class (executed when the proxy is adopted)
93  // Setup the reference when it is adopted by the TClass structure
94  //
95  // classptr [IN] Pointer to the reference class.
96  virtual void SetClass(TClass *classptr) = 0;
97 
98  // Getter of reference class.
99  // The function returns the class description of the reference class
100  // ie. in the case of TRef TRef::Class
101  virtual TClass * GetClass() const = 0;
102 
103  // Access to the target class.
104  // In the event the value class cannot be specified from the reference
105  // itself, because the object behind the reference requires a cast,
106  // the return value must be NULL.
107  //
108  // data [IN] Resolved pointer to the referenced object
109  virtual TClass* GetValueClass(void* data) const = 0;
110 
111  // Update (and propagate) cached information
112  virtual Bool_t Update() = 0;
113 
114  // Flag to indicate if this is a container reference
115  virtual Bool_t HasCounter() const = 0;
116 
117  // Access to container size (if container reference (ie TRefArray) etc)
118  //
119  // info [IN] Pointer to the structure called by TTree::Draw
120  // to extract the required object information.
121  // data [IN] Pointer to the reference object
122  //
123  // return value: The prepared pointer to the reference.
124  virtual Int_t GetCounterValue(TFormLeafInfoReference* info, void *data) = 0;
125 
126  // Prepare reused reference object (e.g. ZERO data pointers)
127  // Because TTree::Draw reuses objects some reference implementations
128  // require setup. For example the pointer to the object the reference points to
129  // needs to be ZEROed.
130  //
131  // data [IN] Pointer to the reference object
132  //
133  // return value: The prepared pointer to the reference.
134  virtual void* GetPreparedReference(void* data) = 0;
135 
136  // Access referenced object(-data)
137  //
138  // info [IN] Pointer to the structure called by TTree::Draw
139  // to extract the required object information.
140  // data [IN] Pointer to the referenced object
141  // instance [IN] Item number if ref collection
142  //
143  // return value: Pointer to the requested information
144  virtual void* GetObject(TFormLeafInfoReference* info, void* data, int instance) = 0;
145 };
146 #endif // ROOT_TVirtualRefProxy
A small helper class to implement the following of reference objects stored in a TTree.
virtual ~TVirtualRefProxy()
int Int_t
Definition: RtypesCore.h:41
bool Bool_t
Definition: RtypesCore.h:59
virtual Int_t GetCounterValue(TFormLeafInfoReference *info, void *data)=0
virtual void * GetObject(TFormLeafInfoReference *info, void *data, int instance)=0
virtual Bool_t HasCounter() const =0
virtual void * GetPreparedReference(void *data)=0
virtual void Release()=0
The ROOT global object gROOT contains a list of all defined classes.
Definition: TClass.h:75
virtual void SetClass(TClass *classptr)=0
virtual TClass * GetClass() const =0
virtual TClass * GetValueClass(void *data) const =0
virtual Bool_t Update()=0
virtual TVirtualRefProxy * Clone() const =0