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