include/AIDA/IAnnotation.h

0001 // -*- C++ -*-
0002 // AID-GENERATED
0003 // =========================================================================
0004 // This class was generated by AID - Abstract Interface Definition
0005 // DO NOT MODIFY, but use the org.freehep.aid.Aid utility to regenerate it.
0006 // =========================================================================
0007 #ifndef AIDA_IANNOTATION_H
0008 #define AIDA_IANNOTATION_H 1
0009
0010 //  This file is part of the AIDA library
0011 //  Copyright (C) 2002 by the AIDA team.  All rights reserved.
0012 //  This library is free software and under the terms of the
0013 //  GNU Library General Public License described in the LGPL.txt
0014
0015 #include <string>
0016
0017 namespace AIDA {
0018
0019 /**
0020  * The annotation holds arbitrary information represented with (key,value) pairs
0021  * of strings. A sticky bit is associated to every item to protect it (or not)
0022  * from a reset operation.
0023  *
0024  * @author The AIDA team (http://aida.freehep.org/)
0025  *
0026  */
0027
0028 class IAnnotation {
0029
0030 public:
0031     /// Destructor.
0032     virtual ~IAnnotation() { /* nop */; }
0033
0034   /**
0035    * The list of the commonly accepted keys :
0036    * "Title" for the title.
0037    *
0038    */
0039
0040   /**
0041    * Add a key/value pair with a given sticky flag.
0042    * If key alredy exists, override its value ?
0043    * @param key    The key to be added.
0044    * @param value  The key's value.
0045    * @param sticky The key's sticky flag. If <code>true</code> the item will
0046    *               not be removed when the method reset or removeItem are invoked.
0047    *               The default value for the sticky flag is <code>false</code>.
0048    * @return false If the key already exists.
0049    *
0050    */
0051     virtual bool addItem(const std::string & key, const std::string & value, bool sticky = false) = 0;
0052
0053   /**
0054    * Remove the item indicated by a given key.
0055    * @param key The key to be removed. If the key is flagged as "sticky" it
0056    *            will not be removed.
0057    * @return false If the key is sticky.
0058    *
0059    */
0060     virtual bool removeItem(const std::string & key) = 0;
0061
0062   /**
0063    * Retrieve the value for a given key.
0064    * @param key The key.
0065    * @return    The corresponding value.
0066    *
0067    */
0068     virtual std::string value(const std::string & key) const = 0;
0069
0070   /**
0071    * Set the value for a given key.
0072    * @param key   The key whose vale is to be changed.
0073    * @param value The new value.
0074    *
0075    */
0076     virtual void setValue(const std::string & key, const std::string & value) = 0;
0077
0078   /**
0079    * Set the sticky flag for a given key.
0080    * @param key    The key whose stick flag is to be set.
0081    * @param sticky The new sticky flag.
0082    *
0083    */
0084     virtual void setSticky(const std::string & key, bool sticky) = 0;
0085
0086   /**
0087    * Get the size of the IAnnotation, i.e. the number of keys contained in it.
0088    * @return The size of the IAnnotation.
0089    *
0090    */
0091     virtual int size() const = 0;
0092
0093   /**
0094    * Get the key at a given position within the IAnnotation.
0095    * @param index The key's position within the IAnnotation.
0096    * @return      The corresponding key.
0097    *
0098    */
0099     virtual std::string key(int index) const = 0;
0100
0101   /**
0102    * Get the value at a given position within the IAnnotation.
0103    * @param index The value's position within the IAnnotation.
0104    * @return      The corresponding value.
0105    *
0106    */
0107     virtual std::string value(int index) const = 0;
0108
0109   /**
0110    * Remove all the non-sticky items.
0111    *
0112    */
0113     virtual void reset() = 0;
0114 }; // class
0115 } // namespace AIDA
0116 #endif /* ifndef AIDA_IANNOTATION_H */