Logo ROOT   6.18/05
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
18class 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//______________________________________________________________________________
82public:
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
int Int_t
Definition: RtypesCore.h:41
bool Bool_t
Definition: RtypesCore.h:59
TClass instances represent classes, structs and namespaces in the ROOT type system.
Definition: TClass.h:75
A small helper class to implement the following of reference objects stored in a TTree.
virtual TClass * GetValueClass(void *data) const =0
virtual void Release()=0
virtual void SetClass(TClass *classptr)=0
virtual Int_t GetCounterValue(TFormLeafInfoReference *info, void *data)=0
virtual TClass * GetClass() const =0
virtual TVirtualRefProxy * Clone() const =0
virtual Bool_t HasCounter() const =0
virtual ~TVirtualRefProxy()
virtual void * GetObject(TFormLeafInfoReference *info, void *data, int instance)=0
virtual void * GetPreparedReference(void *data)=0
virtual Bool_t Update()=0