<!-- 
	 COLLECTION DEFINITION 

		 Version 1.04
     Date   02/07/2000


    MODIFIED    (MM/DD/YY)
    rzkrishn    08/24/05 -  preserveCR in ItemProperty
    nigandhi    03/07/05 - bug_4225458
    njagathe    12/23/04 - Reverting 2422059 
    njagathe    12/21/04 - Adding separate clear messages support 
    njagathe    08/20/04 - Adding ENABLED, REQUIRED attribute to 
                           CollectionItem 
    xxu         08/09/04 - add ALERT_CONTEXT 
    xxu         07/15/04 - add like operator 
    njagathe    06/18/04 - Allow schedule-less CollectionItem s 
    aaitghez    06/14/04 - add CategoryValue to Condition 
    gachen      05/20/04 - add more upload flag for MetricColl 
    njagathe    05/21/04 - Add CONFIG_METADATA_VERSION attribute 
    gachen      05/07/04 - set upload flag for MetricColl 
    njagathe    10/24/03 - Adding INITIAL_UPLOADS 
    rzkrishn    10/10/03 - adding COMBINE_WITH_OTHER_COLLECTION for runTime 
    jabramso    09/16/03 - Add missing ValidIf 
    njagathe    08/19/03 - Add GEN_INIT_CLEAR attribute 
    njagathe    07/25/03 - Adding support for PUSH attribute in Condition
    njagathe    06/26/03 - Adding ValidIf support
    njagathe    05/23/03 - Adding AltSkipCondition
    gachen      05/19/03 - 2951216: filter after severify checking
    njagathe    03/28/03 - Remove TRANSACTIONAL attribute, replace with CONFIG
    njagathe    02/21/03 - Add POSTLOAD_PROC and PRELOAD_PROC
    xxu         01/08/03 - add nlsid
    gachen      11/27/02 - use CDATA for number
    rzkrishn    03/06/03 - review changes
    rzkrishn    03/04/03 - change in CollectionItem dtd
    itarashc    01/17/03 - 
    njagathe    09/10/02 - Adding PROXY_TARGET_TZ_REGION
    cfowler     08/08/02 - Fix DTD syntax error
    lyang       05/09/02 - lyang_move_emsdk_common
    njagathe    03/26/02 - Add NO_CLEAR_ON_NULL attribute
    gachen      03/14/02 - allow only warning
    xxu         02/20/02 - add collection levels
    njagathe    01/31/02 - Add proxy target support
    njagathe    12/12/01 - Change in Collections DTD
    vnukal      10/22/01 - Adding collection dependancy override
    vnukal      09/13/01 - Code review comments
    vnukal      09/05/01 - Adding UPLOAD/collection freq
    rzkrishn    07/30/01 - renaming Filter to ItemProperty
    rzkrishn    08/02/01 - adding LimitRows
    aaitghez    07/16/01 - syntax issues
    njagathe    07/09/01 - Adding UPLOAD_ON_FETCH attribute
    gachen      06/21/01 - fix dtd inconsistency
    gachen      06/20/01 - build more message
    gachen      06/05/01 - support regular expression
    gachen      05/30/01 - new schedule
    gachen      05/07/01 - include default Collection by attr
    gachen      04/18/01 - support fixit-job

This definition drives the background collection of metrics
for the purposes of uploading their values in a central repository
and/or the check of their values against specified conditions.

Note that the XML files conforming to this DDT will be generated 
by the system (Could be generated from Servlet Frontend or collector). 

EMD can have more than one collection files each containing metrics
needs to be collected for a particular target.

-->
 
<!ENTITY % Schedule SYSTEM "Schedule.dtd">
%Schedule;

<!-- 
A TargetCollection describe the metric need to be collected for a particular
target, It can have 0 or more  CollectionItem and IncludeCollectionFile

Attrributes:
  TYPE:  The target type.  
  NAME:  The name of the target. If it is the top level element
                this must not be null.  If this file is included. It could
                be null.	              
  LEVEL: The collection level.
         The default will be the minimum.
  INCLUDE_DEFAULT:  If set to TRUE, will include default collection with the
      same target TYPE.
-->


<!ELEMENT TargetCollection  ( CollectionLevel*, CollectionItem* ) >
<!ATTLIST TargetCollection
  TYPE CDATA #REQUIRED
  NAME CDATA #IMPLIED
  LEVEL CDATA #IMPLIED
  INCLUDE_DEFAULT (TRUE|FALSE)  "TRUE" 
>

<!-- ====================================================================
  Collection Level List
  The order implies the contains relationship.

  NAME:  the name of the collection level
-->
<!ELEMENT CollectionLevel EMPTY>
<!ATTLIST CollectionLevel
  NAME CDATA #REQUIRED
>

<!-- ====================================================================
A CollectionItem defines the collection of one or more metrics.
  It has a schedule.

  For backward compatibility, a single metric can be specified using the
  NAME attribute, and its properties, filters and conditions can be provided
  as child elements.

  The *new* preferred DTD has one or more Metric elements within a  
  CollectionItem each indicating a metric to collect, and the filters, 
  thresholds, etc. to associate with it.

  UPLOAD:   if not specified will be deemed as YES. NUMBER indicates how often
          the CollectionItem is uploaded. (Upload every 'n' collections)
  ATOMIC_UPLOAD: CollectionItems marked as ATOMIC_UPLOAD will be bundled up
     into a single collection file which will be uploaded in the regular upload
     cycle.  Collection of CONFIG metrics cannot specify a FALSE value for this 
     attribute.
  UPLOAD_ON_FETCH:  Behavior is similar to ATOMIC_UPLOAD with 1 difference -
     Collection Items marked UPLOAD_ON_FETCH will be uploaded immediately.
  POSTLOAD_PROC, PRELOAD_PROC: Only applicable in UPLOAD_ON_FETCH situations,
     these are optional pl/sql procedures that the the receiver should invoke 
     when it receives the file with the contents of this collection 
     (starting with 4.1)
  CONFIG : This attribute is used to tag collections of CONFIG metrics - these
     are handled specially by the EM framework 
     (starting from 4.1)
  CONFIG_METADATA_VERSION : This attribute is used to specify version of 
     CONFIG metrics
     (starting from 4.2)
  COLLECT_WHEN_DOWN: The default behaviour is that the collection stops if the
     the Response metric(if present for the target) says that the status of the
     target is down. The exception being the Response metric iteself. But the
     behaviour of not collecting when target is down can be overriden by 
     setting this attribute to TRUE.
  COLLECT_WHEN_ALTSKIP : The default behaviour is that the collection of 
     metrics stops if an AltSkipCondition has been defined and there is a
     severity on the condition. Setting this attribute to TRUE allows 
     collections to proceed even when this is the case.
     Note that a severity on the Response/Status condition is only overcome
     by using the COLLECT_WHEN_DOWN attribute.
  COMBINE_WITH_OTHER_COLLECTION :  
      Agent typically combines collections and executes them in a 
     single thread sequentially to save on threads based on the interval. this
     can cause some delay in the metric execution if a previous one is taking
     some time. However some metrics would require to be executed on time. 
     setting this flag to FALSE would ensure that this metric is executed in 
     its own thread. default is TRUE for this attribute.
  NAME:  the name of the collection
  TIMEOUT: This is the time by which the metric evaluation is expected to 
           finish. users can provide in seconds. If the evaluation takes more
           than this time, the agent aborts the metric evaluation and returns a
           TIMEOUT exception. If this attribute is not provided or a value of 
           zero the agent
           defaults to twice the frequency of this metric evaluation in the 
           collection file. Users can provide  less than zero
           to avoid any sort of timeout. < 0 will make the agent to wait until
           the metric is evaluated completely. 
           (starting with 4.0.1)

  The following three properties are used for proxy collection support. This
  feature allows
  PROXY_TARGET_NAME : Name of target data and sevs should be uploaded for
  PROXY_TARGET_TYPE : Type of - do - 
  PROXY_TARGET_TZ_REGION   : Timezone Region String (Eg "US/Pacific")
        (OR)
  PROXY_TARGET_TZ   : Timezone (minutes from GMT : eg -420)

  The PROXY_TARGET_TZ_REGION takes precedence over PROXY_TARGET_TZ if both are
  specified

  INITIAL_UPLOADS : Defaults to 2, but can be set to a different number if more
          initial uploads need to be sent up before skipping uploads based on
          the UPLOAD parameter (starting with 4.1)


  DISABLED : If set to TRUE, the agent will ignore this collection item
             (starting 10.2)

  REQUIRED : If set to TRUE, the console will disallow users from disabling
             this item (starting 10.2)
-->
<!ELEMENT CollectionItem (ValidIf*, Schedule?, 
                          (MetricColl+ |
                           (ItemProperty*, Filter*, LimitRows?, Condition*)
                          )
                         )>
<!ATTLIST CollectionItem
  NAME CDATA #REQUIRED
  LEVEL CDATA #IMPLIED
  UPLOAD CDATA "YES"
  UPLOAD_ON_FETCH (TRUE | FALSE) "FALSE"
  ATOMIC_UPLOAD (TRUE | FALSE) "FALSE"
  POSTLOAD_PROC CDATA #IMPLIED
  PRELOAD_PROC CDATA #IMPLIED
  CONFIG       (TRUE | FALSE) "FALSE"
  CONFIG_METADATA_VERSION CDATA #IMPLIED
  TIMEOUT  CDATA  #IMPLIED
  COLLECT_WHEN_DOWN (TRUE | FALSE) "FALSE"
  COLLECT_WHEN_ALTSKIP (TRUE | FALSE) "FALSE"
  COMBINE_WITH_OTHER_COLLECTION (TRUE | FALSE) "TRUE"
  PROXY_TARGET_NAME CDATA #IMPLIED
  PROXY_TARGET_TYPE CDATA #IMPLIED
  PROXY_TARGET_TZ   CDATA #IMPLIED
  PROXY_TARGET_TZ_REGION   CDATA #IMPLIED
  INITIAL_UPLOADS CDATA #IMPLIED
  DISABLED (TRUE | FALSE) "FALSE"
  REQUIRED (TRUE | FALSE) "FALSE"
>

<!--
    ValidIf contains a group of category properties which must be meet all together.
    It can be used at different levels like metric, QueryDescriptor,
    ExecutionDescriptor, InstanceProperty, DynamicProperty, etc..
-->
<!ELEMENT ValidIf (CategoryProp+)>
<!--
    CategoryProp describes all choices of one category property.
    CHOICES contains values seperated by ";".
-->
<!ELEMENT CategoryProp EMPTY>
<!ATTLIST CategoryProp
        NAME CDATA #REQUIRED
        CHOICES CDATA #REQUIRED
>

<!-- ====================================================================
  The MetricColl element refers to a metric that is being collected within a 
collection item. 

  NAME : This is the name of the metric to collect.

  TRANSIENT : Indicates if the data of this metric should be uploaded or is
    only collected to refresh the cache, so other metrics can evaluated.
    (Starting from 10.2)

  UPLOAD_IF_SEVERITY: only effective when UPLOAD=NO and UPLOAD=N>1 
         (starting 10.2)
        CHANGE_ONLY:  upload data when there is severity change. ( Default behavior )
        WARNING:      upload data when there is severity change and 
                      when any condition is in WARNING or CRITICAL
        CRITICAL:     upload data when there is severity change and
                      when any condition is in CRITICAL 
-->
<!ELEMENT MetricColl (ItemProperty*, Filter*, LimitRows?, Condition*)>
<!ATTLIST MetricColl
  NAME CDATA #REQUIRED
  TRANSIENT (TRUE | FALSE) "FALSE"
  UPLOAD_IF_SEVERITY (WARNING|CRITICAL|CHANGE_ONLY)  "CHANGE_ONLY"
>

<!-- ====================================================================
  Schedule defines the how often will the Metric be collected.
  It could be defined as 
  1> by an interval
  2> in some day in a week.
  3> in some day in a month.


 please refer to Schedule.DTD

-->

<!--=======================================================================
  LimitRows is a filtering mechanism that can be applied to the collected 
  data, before the data is sent to the repository via the Upload Manager.
  It limits the number of rows hat are uploaded. 
-->

<!ELEMENT LimitRows EMPTY>
<!ATTLIST LimitRows
          COLUMN_NAME CDATA #IMPLIED
          SORT_ORDER (ASCEND|DESCEND|NO_ORDER) "NO_ORDER"
          LIMIT_TO    CDATA   #REQUIRED
>

<!-- =======================================================================
  PRESERVECR (optional) : Flag to specify if CR in PCData needs to be 
                          protected from XML parser. XML Parser removes or
                          converts CR to LF.
-->

<!ELEMENT ItemProperty (#PCDATA)>
   <!ATTLIST ItemProperty
      NAME CDATA #REQUIRED
      ENCRYPTED (NA | FALSE | TRUE ) "NA"
      PRESERVECR (FALSE | TRUE ) "FALSE"
>


<!-- =====================================================================
   Filter defines a filtering mechanism that can be applied to the
   collected data, before the data is sent to the repository via the
   Upload manager. if filtering is not applied, all the data that are 
   collected via a Fetchlet is sent to the repository. As a result 
   the repository can be quickly filled when uploading certain
   metrics.To alleviate this problem, filtering mechanism is applied
   to the data before uploading. The filter criteria is specified in
   collection xml. 

   AFTER_SEVERITY_CHECKING: if set, filter will be applied after severity checking.
-->
<!ELEMENT Filter (#PCDATA)>
<!ATTLIST Filter
     COLUMN_NAME CDATA #REQUIRED
     OPERATOR  (EQ|LT|GT|LE|GE|NE|CONTAINS|MATCH) "EQ"
     AFTER_SEVERITY_CHECKING (TRUE|FALSE)  "FALSE" 
> 

<!--   ====================================================================
    Condition define when a severity will be triggered. 

     If it is Table Metric,  MetricColumn is used to define
     which column and key to use to identify the row and column

     The MESSAGE attribute is a messge template that will be
     used to generate message(s)to be sent along with the 
     event occurrence.
     This message can contain the following palce holders 

     %value%  : The value of the metric (or coulumn of metric)
     %target% : name of the target
     %metric_id% : metric id
     %column_name% This will be the value of any column
                        this can include value columns as well as
                        key columns
     %warning_threshold%: the warning threshold of the condition
     %critical_threshold%: the critical threshold of the condition
     %num_of_occur%:  number of occurrences 

     The MESSAGE_NLSID attribute is the name of the id that will be used to
     translate the content of the MESSAGE attribute for non-english languages
                        
    For table metric, 
        COLUMN_NAME defines which column will be checked.
        keyColumn will be used to identify a row
        
    If the result after the keys are applied contains more
    than one row, the event occurrence generated will have
    content/message for each row that has crossed the threshold.        

    MATCH is used for regular expression.  For example

    OPERATIOR="MATCH"  CRITICAL=".*ORA.*ERR.*"

    will match a string contains both ORA and ERR. such as "ORA-ERR 345"

    The NO_CLEAR_ON_NULL attribute is used to control severity clearing when
    a null value is returned for a metric column. 
    It defaults to FALSE with the behavior that a null value ends up clearing 
    previous alert severities. 
    With a TRUE value for this attribute, null values will be skipped in 
    severity evaluations without clearing the severity.

    The PUSH attribute is used to distinguish conditions created for push based
    alerts from conditions that are evaluated over collected data. The agent 
    does not evaluate PUSH="TRUE" conditions (Starting from 4.1)

    The GENERATE_INIT_CLEAR attribute can be used to override the agent's 
    behavior of not generating a severity the very first time a CLEAR is 
    generated. Set this to TRUE if you do want the initial CLEAR (Starting from
    4.1)

    The ALERT_CONTEXT attribute will be used to pass the related alert context.
    This new attribute may contain a list of column names separated by ";".

    CategoryValue sub tags are used to classify the Condition along
    two axis, CLASS and CATEGORY.  For e.g. CLASS=Fruits, CATEGORY=RedFruits
    Categorization of Conditions is useful for Root Cause Analysis
    among other things. (Starting with 10.2)

    The CLEAR_MESSAGE and CLEAR_MESSAGE_NLSID attributes allow the 
    specification of a different message when an alert is cleared. If these
    attributes are missing, the MESSAGE and MESSAGE_NLSID attributes are
    used for the clear cases as well. (Supported starting with 10.2)

-->
<!ELEMENT Condition (CategoryValue*, KeyColumn*, FixitJob? )>
<!ATTLIST Condition
  CRITICAL CDATA #IMPLIED
  WARNING  CDATA #IMPLIED
  OPERATOR (EQ | LT | GT | LE | GE | NE | CONTAINS | MATCH ) "GT"
  OCCURRENCES CDATA "1"
  NO_CLEAR_ON_NULL (TRUE | FALSE) "FALSE"
  MESSAGE CDATA #IMPLIED
  MESSAGE_NLSID CDATA #IMPLIED
  COLUMN_NAME CDATA #REQUIRED
  PUSH (TRUE | FALSE) "FALSE"
  GENERATE_INIT_CLEAR (TRUE | FALSE) "FALSE"
  ALERT_CONTEXT CDATA #IMPLIED
  CLEAR_MESSAGE CDATA #IMPLIED
  CLEAR_MESSAGE_NLSID CDATA #IMPLIED
>

<!ELEMENT KeyColumn (#PCDATA)>
<!ATTLIST KeyColumn
  COLUMN_NAME CDATA #REQUIRED
  OPERATOR    (EQ | LIKE) "EQ"
>

<!ELEMENT  FixitJob  (Property*) >
<!ATTLIST  FixitJob  
      TYPE    CDATA  #IMPLIED 
>           

<!ELEMENT Property (#PCDATA)>
<!ATTLIST Property 
      NAME  CDATA   #REQUIRED
      SCOPE (SYSTEMGLOBAL|INSTANCE|GLOBAL|COLUMNVALUE|CONDITION)  "GLOBAL"
>

<!-- The <Property> tag will define what context need to passed to exec the job. 

    The Scope will be defined similar to TargetMetadata.DTD. See code
    at emd.engine.MetricEngine.java::getPropertyValue for more detail.

    SYSTEMGLOBAL:  will lookup the emd.properties for the value.
    INSTANCE    :  will lookup the value in targets.xml
    GLOBAL      :  will be resolve in this context here
    CONDITION   :  will be resolved by the condition definition.   We define the following
                   name for the condition

                   WARNING
                   OPERATOR
                   OCCURRENCES
                   MESSAGE
                   COLUMN_NAME                 
                                                         
    COLUMNVALUE :  will be resolved at the time the metric is evaluate. The name here
                   is the metric column_name.  There are a few pre-defined name

                    TARGET_NAME
                    TARGET_TYPE
                    METRIC_NAME
                    COLLECTION_TIMESTAMP

-->