/**
   \file
   Interface for particles lists to particles on the ground recorded by
   an air shower simulator.
   \author Lukas Nellen
   \version $Id$
   \date 4-Apr-2003
*/

#ifndef _utl_VShowerFileParticleIterator_h_
#define _utl_VShowerFileParticleIterator_h_

static const char CVSId_utl_VShowerFileParticleIterator[] =
  "$Id$";

#include <utl/CoordinateSystemPtr.h>


namespace utl {

  class Particle;
  class ShowerParticleIterator;


  /**
    \class VShowerFileParticleIterator VShowerFileParticleIterator.h
    "utl/VShowerFileParticleIterator.h"

    \brief Interface class for accessing a list of particles from a
    shower file.

    This class defines the interface by which the ShowerParticleIterator
    fetches the particles of the ground particles list from the output of an
    air-shower simulation.

    \ingroup particles stl
  */

  class VShowerFileParticleIterator {
  public:
    VShowerFileParticleIterator()
      : fAssociatedIterator(0), fExternalShowerCS() { }

    virtual ~VShowerFileParticleIterator() { }

    /// Get the local CS in the shower core position
    CoordinateSystemPtr GetExternalShowerCoordinateSystem() const;

    /// Set the local CS in the shower core position
    void SetExternalShowerCoordinateSystem(const CoordinateSystemPtr&
                                           theCoordinateSystem);

    /// Member function to fetch the next particle.
    /** This method has to return a pointer to the current particle in the
        shower file. Then it steps the cursor in the shower file forward.
        This corresponds to the way a typical interface library for Aires
        or CORSIKA provides access to the particles on the ground.

        If no more particles are available, return a null pointer.

        Call Rewind() before calling this function. This puts the underlying
        library into a defined state.

        It is the responsibility of the concrete implementation to
        react appropriately to illegal calls to GetOneParticle()
    */
    virtual Particle* GetOneParticle() = 0;

    /// Rewind the particle list in the shower file to the beginning.
    /** After a call to this function, calls to GetOneParticle() start
        returning particles starting from the first particle recorded
        for the shower.
    */
    virtual void Rewind() = 0;

    /// Compute the coordinate system for the ground particle file
    /** This is a template-pattern function that implements the
        computation of the coordinate system in which the external
        code stores the coordinates of the ground particle
        information.
     */
    virtual CoordinateSystemPtr
    ComputeExternalShowerCoordinateSystem(const CoordinateSystemPtr&
                                          theCoordinateSystem) = 0;

  private:
    /// Flag to prevent the association of multiple ShowerParticleIterator's
    const ShowerParticleIterator* fAssociatedIterator;
    /// The coordinate system of the ground particle coordinates
    CoordinateSystemPtr fExternalShowerCS;
  };

}


#endif

// Configure (x)emacs for this file ...
// Local Variables:
// mode: c++
// compile-command: "make -C .. -k"
// End: