// SampleFramework-- Sample of using the ErrorLogger mechanism.
//
// This is part of the principal sample of how to use the ErrorLogger
// mechanism in a realistic setting.
//
// 	The sample is meant to be taken as a starting point, and modified to
//	meet an experiment's needs.  Or it can be viewed as a fairly complete
//	illustration of most of the commonly used features in ErrorLogger.
//
// The overall structure assumed is that some programmer(s) provide a
// "framework" including the main program, various setups and event-flow
// controls, and so forth.  Then each group of physicists provide "modules"
// (or, in D0 language, "packages") which do steps of physics calculation --
// the framework will pass an event from package to package.
//
// This sample is composed of five files:
//	SampleFramework	contains the framework: the setup, setting up each
//			module,	and the Event loop.
//	SampleModule	holds the Module base class.  This likely already is
//			part of the experiment framework, or it may be added
//			to define modules for error logging purposes.
// 	SampleEvent	contains the definition of Event, whiich is very
//			simple here but would be huge in reality.  .h only.
//
//	SampleModuleA	contains the physics code written by group A to act
//			as module A.  This is just one .h and one .cc file,
//			though physics code would probably have several
//			subroutines, each with its own files.
//	SampleModuleA	contains the physics code written by group A to act
//			as module B.  This is just one .h and one .cc file,
//			though physics code would probably have several
//			subroutines, each with its own files.
//
// Each experiment has its own means of hooking up modules or packages to
// form the flow executed for each event.  In this sample program, we
// bury that issue in the SampleFramework constructor, where a list of
// modules to invoke is established.

// The strange comments like // $$ 9:3 refer to the fact that this line
// exercises something in section 9 (for example) of the design document.
//

#ifndef SAMPLE_FRAMEWORK_H
#define SAMPLE_FRAMEWORK_H

#ifndef ZMENVIRONMENT_H
  #include "ZMutility/ZMenvironment.h"
#endif
		// ZMenvironment.h provides platform portability features.
		// Code using ZOOM packages should routinely include it.

#include "ErrorLogger/ELcontextSupplier.h"
	        // This framework will provide a class derived from
		// ELcontextSupplier.

#include "ErrorLogger/ErrorLog.h"
		// We will have an ErrorLog data member in the framework so
		// that the framework can itself send messages.
	
class ELadministrator;

#include <string>	// RunEventContext uses strings.

#include <list>		// SampleFramework has a list of
class SampleModule;	// pointers to user modules.

//
// SampleFramework is a class embodying the overall structure of the program.
// --------------- It contains data which otherwise might be global, such as
//		   run and event numbers.  But the main features are its methods
//		   setup() and eventLoop().

class SampleFramework {

public:

  SampleFramework();
  ~SampleFramework();

  void setup();
  void eventLoop();

  int getRun() const;
  int getEventNum() const;

  //
  // RunEventContext is contained in SampleFramework, with functions that can
  // --------------- be called (by the logger) when the logger is invoked, to
  //		     find out which event is being processed.  Thus when no log
  //		     messages are issued, there is NO overhead to advance this
  //		     context.  We have place RunEventContext inside the scope
  //		     of the framework because nobody else has use for it, and
  //		     so that it has easy access to such framework variables as
  //		     eventN and runR.

  class RunEventContext : public ELcontextSupplier  {    	     // $$ 9:1

  private:
    SampleFramework & f;

  public:
    RunEventContext ( SampleFramework & ff );
		// The scheme this sample uses to get the run and event number
		// information involves calling a method of the framework.
		// So RunEventContext has to know about the framework it is in.
		// Your application may use some different scheme and may not
		// need to do this.
    ZM_COVARIANT_TYPE(ELcontextSupplier *, RunEventContext *)
                    clone() const;
		// This would in standard C++ be RunEventContext* clone()
		// but VC++ will not accept that.
		// The peculiar ZM_COVARIANT_TYPE macro fixes that problem.
    std::string       context() const;
    std::string       fullContext() const;
    std::string       summaryContext() const;
		// All three of these must be provided.  The summaryContext
		// should be short (1-16 characters) and is used when the
		// statistics are giving a few sample events for a type of
		// message.  The context is what is used in ordinary output.
		// The fullContext can provide more info, but is typically
		// just set to return context().

  };  // RunEventContext

private:	// private data in SampleFramework class

  // Member data not related to the Error Logger:
  int eventN;
  int runR;

  // The master list of modules to be invoked for each event:
  std::list<SampleModule*> eventSteps;

  // Members relevant to the logger:
  RunEventContext reContext;		// Object that supplies context info
  ELadministrator* logger;		// The overall logger object
  ErrorLog errlog;			// A place for the framework itself
					// to log messages.  Each module has
					// is own errorlog.

  // Controls for all the logging destinations:
  ELdestControl logfile;
  ELdestControl problemLog;
  ELdestControl output;
  ELdestControl stats;

}; // SampleFramework

#endif  // SAMPLE_FRAMEWORK_H