#if !defined(monitoring_annotations_included)
#define monitoring_annotations_included

@autoid @default_nested(TRUE)
module monitoring {

    /*
    * PERIODIC observable elements distributed at some period (which may be variable)
    *       even if there is no change. Because of this it is possible to
    *       implement the distribution using less resources (e.g. best effort
    *       QoS, no need to remember the previous value etc.
    *
    * ON_CHANGE observable elements distributed only if there is a (significant) change
    *       in the value relative to the previous value. Because of this
    *       the distribution needs to take care that no update is lost.
    *
    * The mechanism for collecting monitoring data from the observable elements is 
    * decoupled from the distribution of the data.
    *
    * Collection can use a Synchronous instrument (poll the value) or Asynchronous 
    * get value via callback when a change happens.
    * Distribution of the collected data can also be done ON_CHANGE (whenever the
    * value of an observed element changes) or PERIODIC (send it even if there is no
    * change from previous value.
    *
    * The DistributionKind controls only the distribution the data collected from an 
    * Observable Element. It does not affect how the data is collected.
    * is distributed by DDS Monitoring.  distrubu
    */
    enum DistributionKind {
        UNSPECIFIED,  // Match context
        PERIODIC,     // Sent (periodically) even if unchanged
        ON_CHANGE     // Sent if "significantly" different
    };

    // No annotation is interpreted depending on whether other members are annotated
    //   - If no other members are annotated  => @observable(UNSPECIFIED)
    //   - If some other member is annotated  => not observable
    @annotation observable {
        DistributionKind    distribution    default UNSPECIFIED; 
    };

    /*
     * May be applied to modules or structure members to chnage how the module or
     * member name appars in the Fully Qualified Name (FQN) of the Observable Elements
     * inside that module or element.
     *
     * - If the annotation is not present, the coresponding module name or member name that
     *   appeaers in the IDL type is used to construct the FQN.
     * 
     * - If the annotation is present and the value specified is the empty string, the
     *   the corresponding module name or member name is ommitted in the consruction of 
     *   the FQN.
     *
     * - If the annotation is present and the value is not empty, then the value specified
     *   in the annotation i sused instead of the module or member name in the consruction 
     *   of the FQN.
     */
    @annotation observable_name {
        string   value    default ""; 
    };

    /* This annotation may only be applied to a Structure type. 
     * This use of this annotation and the related @observable_view impact the mapping of structure 
     * into the Monitoring distribution datamodel. 
     *
     * The annotation is used to define an Observable Unit.
     * Observable Elements that appear nested inside the Observable Unit will not be propagated 
     * individually. Instead, they will appear grouped with the other Observable Element in the unit.
     */
    @annotation observable_unit {
        DistributionKind    distribution    default UNSPECIFIED; 
    };

    /*
     * This annotation may only be applied to a Structure type that has the @observable_unit annotation. 
     * It may appear multiple times in the same Structure. Each occurrence in a type shall use a different 
     * value for the “level” parameter.  
     *
     * The annotation determines the number of Observable Units created from the Structure type 
     * and the Observable Elements included in each unit.
     *
     * No annotation is interpreted as having a single view that selects all members 
     * A level is inclusive of the previous levels
     * The select expression uses the pattern matching syntax of makefiles
     */ 
    @annotation observable_view {
        @max(8) int8        level           default 0;        // level=0 => default level
        string              select          default "%";      // select="%" => select all
    };

    /* Applies to members. 
     * Each member can have at most one @view annotation.
     * Absence of the annotation is interpreted as having @view(level=0, member_level=0)
     */
    @annotation view {
        @max(31) uint8  level         default 0;  // 0 => default layer
        @max(31) uint8  member_level  default 0;  // member default layer
    };

    /*
     * No annotation is interpreted as not being a resource
     * @resource adds 2 fields to the distribution model:
     *      GUID_t guid
     *      string name
     *
     * They do not need to be explicitly added in the application model
     */
    @annotation resource {
        string   class    default "";  // Default => name automatically derived from type
        string   owner    default "";  // Default => root resource
        string   uses     default "";  // Default => does not use other resources
    };

    /* This annotation may be applied to members of a Structure Type. 
     * The annotation indicates that any Observable Elements related to the member 
     * (directly or nested within) that are Basic Types should be treated as Attributes. 
     * The use of the annotation overrides the default criteria used to make the decision.
     */
    @annotation label {
        boolean value default TRUE;
    };

};  // End of module monitoring
#endif /* monitoring_annotations_included */