Collections/SmartCollection/SmartCollection.h

/*
 * SmartCollection.h
 *
 *  Created on: 14-mag-2009
 *      Author: Nicola Mori
 */

/*! @file SmartCollection.h The SmartCollection class definition file */

#ifndef SMARTCOLLECTION_H_
#define SMARTCOLLECTION_H_

#include "../../PamCutBase/PamCutBase.h"
#include "../../CollectionActions/CollectionAction/CollectionAction.h"

/*! @brief A collection class designed to use CollectionAction objects.
 *
 * The SmartCollection class is designed to handle CollectionAction objects. It
 * holds a vector of these objects and takes care of calling Setup and Finalize for
 * each of them at the beginning and at the end of the analysis, respectively.
 * Actions can be added to the SmartCollection by means of the AddAction() method.
 * If a bunch of cuts have been already added to the collection, the action will
 * be logically placed after the cuts. The SmartCollection will call
 * CollectionAction::OnGood() if the cuts preceding the actions are satisfied, and
 * CollectionAction::OnBad() if at least one of them fails. An action will not be
 * sensitive to cuts added to the collection after the action itself.
 * The resulting structure is composed by bunches of cuts intertwined by actions,
 * which are "executed" depending on the result of the bunch of cuts that precedes the
 * action. Note that CollectionAction::OnBad() is called only for those actions at
 * the end of the bunch where the first failed cut is: if after these actions there
 * are other bunches of cuts and actions, they will be ignored.
 * For example, in the sequence below:
 *
 * | cut1 | cut2 | action1 | action2 | cut3 | cut4 | action3 | ...
 *
 * action1 and action2 are executed (eg., OnGood is called for them) if cut1 and cut2
 * are both satisfied, then cut3 and cut4 are evaluated and if both of them are satisfied
 * then action3 is executed. If, for example, cut 1 or cut2 fail, then OnBad is called for
 * action1 and action2; however, cut3, cut4, action3 and all that follows are ignored. The
 * analysis goes on with the next event.
 */
class SmartCollection: public PamCutCollection {

public:

  /*! @brief Constructor.
   *
   * @param collectionName The collection's name.
   * @param owns If true, the collection will own the cuts and the actions, ie., it will
   *             destroy them in its destructor.
   */
  SmartCollection(const char* collectionName, bool owns = true) :
      PamCutCollection(collectionName, owns), _actions(0) {
  }

  /*! @brief Destructor. */
  ~SmartCollection();

  /*! @brief Adds an action to the SmartCollection */
  virtual void AddAction(CollectionAction *action);

  /*! @brief Returns the iAction-th action.
   *
   * @param iAction The index of the desired CollectionAction, defined as the insertion order
   *        (from 0 to \#actions-1, see AddAction()).
   * @return pointer to the iAction-th action; NULL if the specified action cannot be found or if no actions are present.
   */
  CollectionAction *GetAction(unsigned int iAction);

  /*! @brief Searches for an action by name.
   *
   * @param actionName The name of the action to search for.
   * @return pointer to the desired action; NULL if the specified action cannot be found or if no actions are present.
   */
  CollectionAction *GetAction(const char *actionName);

  /*! @brief The number of actions in the collection.
   *
   * @return The number of actions currently in the collection.
   */
  unsigned int GetActionsSize() {
    return _actions.size();
  }

  /*! @brief The position of specified action.
   *
   * This method returns the position of the iAction-th action. For every action
   * placed before the first cut this will return -1. Otherwise it will return the index
   * of the cut preceding the action (eg., if action number 3 is after cut number 2,  GetActionPosition(3)
   * will return 2)
   *
   * @param iAction The index of the action (0 = first action)
   * @return The position of the specified action
   */
  int GetActionPosition(unsigned int iAction) {
    return _actionsPositions[iAction];
  }

  /*! @brief The pre-analysis task definition.
   *
   * This override of the Setup() method calls Setup() for the base class PamCutCollection, and subsequently for each
   * action contained in the SmartCollection.
   *
   * @param events The PamLevel2 pointer to the events that will be analyzed. Used only as parameter for
   *          CollectionAction::Setup().
   */
  void Setup(PamLevel2 *events);

  /*! @brief The post-analysis task definition.
   *
   * This override of the Finalize() method calls PamCutCollection::Finalize() and then the Finalize() method of
   * each action contained in the SmartCollection.
   */
  void Finalize();

  /*! Applies the cuts and executes the actions.
   *
   * When cuts are applied, a SmartCollection will also execute the actions at the end of the bunches of cuts.
   *
   * @param event The event to analyze.
   */
  int ApplyCut(PamLevel2 *event);

protected:

  /*! @brief The vector containing the actions */
  std::vector<CollectionAction*> _actions;

  /*! The vector of actions' positions
   *
   * An action is placed after N cuts, so that the SmartCollection, after applying N cuts, has to
   * perform the action. The numbers N for each action are stored here: the element i is N for the
   * i-th action in #_actions.
   */
  std::vector<int> _actionsPositions;

};

#endif /* SMARTCOLLECTION_H_ */
1	pam-fi	1.1	/*
2			* SmartCollection.h
3			*
4			* Created on: 14-mag-2009
5			* Author: Nicola Mori
6			*/
7
8			/! @file SmartCollection.h The SmartCollection class definition file /
9
10			#ifndef SMARTCOLLECTION_H_
11			#define SMARTCOLLECTION_H_
12
13			#include "../../PamCutBase/PamCutBase.h"
14			#include "../../CollectionActions/CollectionAction/CollectionAction.h"
15
16			/*! @brief A collection class designed to use CollectionAction objects.
17			*
18	pam-fi	1.3	* The SmartCollection class is designed to handle CollectionAction objects. It
19			* holds a vector of these objects and takes care of calling Setup and Finalize for
20			* each of them at the beginning and at the end of the analysis, respectively.
21			* Actions can be added to the SmartCollection by means of the AddAction() method.
22			* If a bunch of cuts have been already added to the collection, the action will
23			* be logically placed after the cuts. The SmartCollection will call
24			* CollectionAction::OnGood() if the cuts preceding the actions are satisfied, and
25			* CollectionAction::OnBad() if at least one of them fails. An action will not be
26			* sensitive to cuts added to the collection after the action itself.
27			* The resulting structure is composed by bunches of cuts intertwined by actions,
28			* which are "executed" depending on the result of the bunch of cuts that precedes the
29			* action. Note that CollectionAction::OnBad() is called only for those actions at
30			* the end of the bunch where the first failed cut is: if after these actions there
31			* are other bunches of cuts and actions, they will be ignored.
32			* For example, in the sequence below:
33	pam-fi	1.1	*
34	pam-fi	1.3	* \| cut1 \| cut2 \| action1 \| action2 \| cut3 \| cut4 \| action3 \| ...
35			*
36			* action1 and action2 are executed (eg., OnGood is called for them) if cut1 and cut2
37			* are both satisfied, then cut3 and cut4 are evaluated and if both of them are satisfied
38			* then action3 is executed. If, for example, cut 1 or cut2 fail, then OnBad is called for
39			* action1 and action2; however, cut3, cut4, action3 and all that follows are ignored. The
40			* analysis goes on with the next event.
41	pam-fi	1.1	*/
42			class SmartCollection: public PamCutCollection {
43
44			public:
45
46			/*! @brief Constructor.
47			*
48	pam-fi	1.2	* @param collectionName The collection's name.
49	pam-fi	1.7	* @param owns If true, the collection will own the cuts and the actions, ie., it will
50			* destroy them in its destructor.
51	pam-fi	1.1	*/
52	pam-fi	1.7	SmartCollection(const char* collectionName, bool owns = true) :
53	pam-fi	1.8	PamCutCollection(collectionName, owns), _actions(0) {
54	pam-fi	1.1	}
55
56			/! @brief Destructor. /
57	pam-fi	1.7	~SmartCollection();
58	pam-fi	1.1
59			/! @brief Adds an action to the SmartCollection /
60	pam-fi	1.7	virtual void AddAction(CollectionAction *action);
61	pam-fi	1.1
62			/*! @brief Returns the iAction-th action.
63			*
64			* @param iAction The index of the desired CollectionAction, defined as the insertion order
65			* (from 0 to \#actions-1, see AddAction()).
66			* @return pointer to the iAction-th action; NULL if the specified action cannot be found or if no actions are present.
67			*/
68			CollectionAction *GetAction(unsigned int iAction);
69
70	pam-fi	1.5	/*! @brief Searches for an action by name.
71			*
72			* @param actionName The name of the action to search for.
73			* @return pointer to the desired action; NULL if the specified action cannot be found or if no actions are present.
74			*/
75			CollectionAction GetAction(const char actionName);
76
77			/*! @brief The number of actions in the collection.
78			*
79			* @return The number of actions currently in the collection.
80			*/
81	pam-fi	1.7	unsigned int GetActionsSize() {
82	pam-fi	1.5	return _actions.size();
83			}
84
85	pam-fi	1.8	/*! @brief The position of specified action.
86			*
87			* This method returns the position of the iAction-th action. For every action
88			* placed before the first cut this will return -1. Otherwise it will return the index
89			* of the cut preceding the action (eg., if action number 3 is after cut number 2, GetActionPosition(3)
90			* will return 2)
91			*
92			* @param iAction The index of the action (0 = first action)
93			* @return The position of the specified action
94			*/
95			int GetActionPosition(unsigned int iAction) {
96			return _actionsPositions[iAction];
97			}
98
99	pam-fi	1.1	/*! @brief The pre-analysis task definition.
100			*
101			* This override of the Setup() method calls Setup() for the base class PamCutCollection, and subsequently for each
102			* action contained in the SmartCollection.
103			*
104			* @param events The PamLevel2 pointer to the events that will be analyzed. Used only as parameter for
105			* CollectionAction::Setup().
106			*/
107			void Setup(PamLevel2 *events);
108
109			/*! @brief The post-analysis task definition.
110			*
111			* This override of the Finalize() method calls PamCutCollection::Finalize() and then the Finalize() method of
112			* each action contained in the SmartCollection.
113			*/
114			void Finalize();
115
116	pam-fi	1.3	/*! Applies the cuts and executes the actions.
117	pam-fi	1.1	*
118	pam-fi	1.3	* When cuts are applied, a SmartCollection will also execute the actions at the end of the bunches of cuts.
119	pam-fi	1.1	*
120	pam-fi	1.3	* @param event The event to analyze.
121	pam-fi	1.1	*/
122	pam-fi	1.3	int ApplyCut(PamLevel2 *event);
123	pam-fi	1.1
124	pam-fi	1.3	protected:
125	pam-fi	1.1
126	pam-fi	1.6	/! @brief The vector containing the actions /
127	pam-fi	1.1	std::vector<CollectionAction*> _actions;
128	pam-fi	1.6
129			/*! The vector of actions' positions
130			*
131			* An action is placed after N cuts, so that the SmartCollection, after applying N cuts, has to
132			* perform the action. The numbers N for each action are stored here: the element i is N for the
133			* i-th action in #_actions.
134			*/
135	pam-fi	1.7	std::vector<int> _actionsPositions;
136	pam-fi	1.1
137			};
138
139			#endif /* SMARTCOLLECTION_H_ */