B Report File Configuration Reference

This appendix provides a detailed reference of the report file deployment descriptor elements and includes a brief overview of the descriptor. See Appendix C, "Report Group Configuration Reference," for a detailed reference of the report group deployment descriptor elements.

The following sections are included in this appendix:

B.1 Report File Deployment Descriptor

The report file deployment descriptor specifies a report for displaying management information that is based on Coherence MBeans. Coherence includes many predefined report files for most of the MBeans. The default files are located in the coherence.jar file in the /reports directory. The reports can be modified as required or new reports can be created. See Chapter 6, "Analyzing Reporter Content," for additional information about the default reports.

The report file deployment descriptor schema is defined in the coherence-report-config.xsd file which is located in the root of the coherence.jar library and at the following Web URL:

http://xmlns.oracle.com/coherence/coherence-report-config/1.0/coherence-report-config.xsd

The <report-config> element is the root element of the deployment descriptor and typically includes the XSD reference, the Coherence namespace reference, and the location of the coherence-report-config.xsd file. For example:

<?xml version='1.0'?>

<report-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-report-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-report-config
   coherence-report-config.xsd">

Notes:

  • The schema located in the coherence.jar library is always used at run time even if the xsi:schemaLocation attribute references the Web URL.

  • The xsi:schemaLocation attribute can be omitted to disable schema validation.

  • When deploying Coherence into environments where the default character set is EBCDIC rather than ASCII, ensure that the deployment descriptor file is in ASCII format and is deployed into its run-time environment in the binary format.

Element Reference

Table B-1 lists all non-terminal report file deployment descriptor elements.

Table B-1 Report File Deployment Descriptor Non-Terminal Elements

Element Used in

column

row

filter

filters

filters

report

params

filter, column

query

report, column

report

report-config

report-config

root element

row

report-config

column

Used in: row

Description

The column element contains information to generate a report column. The column element supports the use of an id attribute to uniquely identify the column. The ID is used within the column-ref element.

Elements

Table B-2 describes the subelements of the column element.

Table B-2 column Subelements

Element Required/
Optional		 Description

type

Optional

Specifies an XmlColumn implementation. The type element defines the type of the column in the report. Valid values are:

  • attribute – (default) A column which contains the data from a MBean attribute.

  • key – A column which contains the value from a MBean key attribute.

  • method – A column which contains the result of an MBean method invocation.

  • function – A column which contains the result of a function or aggregation. See function-name below.

  • global – A column that contains a value not related to any specific MBean. Global column names are {report-time}, {report-count}, and {node-id}.

  • constant – A column which contains a constant string of numeric value.

  • property – A column which contains a value of a Java system property.

name

Optional

Specifies an attribute or method name on the MBean. For composite data types, the name element can contain a slash (/) delimited name sequence.

header

Optional

Specifies the column header. If this item is omitted, the value of the name element is used instead.

delim

Optional

Specifies a character that is used to separate column or array values. Valid values are: {tab}, {space}, or any non-whitespace character.

query

Optional

Specifies information necessary to construct a JMX query to find all MBeans contributing to the report or column.

hidden

Optional

Specifies whether the column value should be hidden in the report. Valid values are true and false.

column-ref

Optional

Specifies a reference to a column identifier. The reference is used to pass a column value as an argument to a filter or another column.

function-name

Optional

Specifies the name of the calculation to apply to the associated MBean attribute values. This element is only valid when the type element is function. Valid values are:

  • sum – The sum of all retrieved attribute values.

  • avg – The average value for all retrieved attribute values.

  • min – The minimum numeric value for all retrieved attribute values.

  • max – The maximum numeric value for all retrieved attribute values.

  • add – The sum of values for two column references.

  • subtract – The difference between values for two column references.

  • multiply – The product of values for two column references.

  • divide – The ratio between values for two column references.

params

Optional

Specifies an argument column or a filter reference.

data-type

Optional

Specifies the data type of a constant column. Valid values are double and string.

value

Optional

Specifies the value of a constant column.

group-by

Optional

specifies whether the column should be included in the group by clause of the query. Valid values are true and false. The default values is false.

subquery

Optional

Specifies whether the column is included as part of a subquery. Valid values are true and false. The default values is false.

return-neg

Optional

Specifies if a negative value should be returned to the query. Negative values are considered error or not available codes on Coherence MBeans. By default, these codes are returned as zero to not impact column calculations. Valid values are true and false. The default values is false.

filter

Used in: filters

Description

The filter element defines a set of filters that can be used in the report. The filter element supports the use of an id attribute to uniquely identify the filter. The ID is used within the filter-ref element.

Elements

Table B-3 describes the subelements of the filter element.

Table B-3 filter Subelements

Element Required/
Optional		 Description

type

Optional

Specifies an XmlFilter implementation. The type element defines the type of the filter in the report. Valid values are:

  • equals – A filter which compares the result of two or more column references for a value equality.

  • greater – A filter which compares the results of two column references for greater than condition. If any of the values is resolved to null, the evaluation yields false. (This approach is equivalent to the way the NULL values are handled by SQL.)

  • less – A filter which compares the results of two column references for less than condition. If any of the values is resolved to null, the evaluation yields false.

  • not – A filter which returns the logical not of a filter reference.

  • and – A filter which returns the logical and of two filter references.

  • or – A filter which returns the logical or of two filter references.

params

Optional

Specifies an argument column or a filter reference.

filters

Used in: report

Description

The filters element contains a group of filter elements.

Elements

Table B-4 describes the subelements of the filters element.

Table B-4 filters Subelements

Element Required/
Optional		 Description

filter

Optional

Specifies a set of filters that can be used in the report.

params

Used in: column, filter

Description

The params element identifies an argument column or a filter reference.

Elements

Table B-5 describes the subelements of the params element.

Table B-5 params Subelements

Element Required/
Optional		 Description

filter-ref

Required

Specifies a reference to a filter id. The reference is used to pass a filter as an argument to a query or another filter.

column-ref

Required

Specifies a reference to a column identifier. The reference is used to pass a column value as an argument to a filter or another column.

query

Used in: column, report

Description

The query element contains information necessary to construct a JMX query to find all MBeans contributing to the report or column. Queries are entered within a <pattern> element.

Examples

An example that includes all Node MBeans in the report or column:

<query>
   <pattern>Coherence:type=Node,*</pattern>
</query>

An example that includes only the Cluster MBean in the report or column:

<query>
   <pattern>Coherence:type=Cluster</pattern>
</query>

The pattern string allows macro substitutions with run-time values that come from report columns. For example, to provide a cache name into the query pattern, define a system property called reporter.cacheName and use the following construct:

<report>
   ...
   <query>
      <pattern>Coherence:type=Cache,name={CacheName},*</pattern>
   </query>
   <row>
      <column id="CacheName">
         <type>property</type>
         <name>reporter.cacheName</name>
      </column>
   </row>
</report>

Sometimes a query pattern is known to result in a list of MBean names that have a well known key attribute. That key attribute could be used to retrieve an attribute from a related (joined) MBean. For example, since the Coherence:type=Service,* pattern is known to result in MBeans in the Coherence:type=Service,nodeId=NNN format, the configuration below is used to print the MemberName attribute from a corresponding NodeMBean along with the ServiceName attribute for the ServiceMBean.

<report>
   ...
   <query>
      <pattern>Coherence:type=Service,*</pattern>
      <params>
         <column-ref>MemberName</column-ref>
         <column-ref>NodeId</column-ref>
         <column-ref>ServiceName</column-ref>
      </params>
   </query>
   <row>
      <column id="MemberName">
         <type>attribute</type>
         <name>MemberName</name>
         <query>
            <pattern>Coherence:type=Node,nodeId={NodeId}</pattern>
         </query>
      </column>
      <column id="NodeId">
         <type>key</type>
         <name>nodeId</name>
      </column>
      <column id="ServiceName">
         <type>key</type>
         <name>name</name>
      </column>
   </row>
</report>

Elements

Table B-6 describes the subelements of the query element.

Table B-6 query Subelements

Element Required/
Optional		 Description

pattern

Required

Specifies a JMX query or Object name to be included in the report.

filter-ref

Optional

Specifies a reference to a filter id. The reference is used to pass a filter as an argument to a query or another filter.

params

Optional

Specifies an argument column or a filter reference.

report

Used in: report-config

Description

The report element contains information necessary to generate a JMX based report. Any number of report elements can included; however, it is typical to have a single report definition for each report file.

Elements

Table B-7 describes the subelements of the report element.

Table B-7 report Subelements

Element Required/
Optional		 Description

description

Optional

Specifies a descriptive heading for the report.

file-name

Required

Specifies the file name for the generated report. The file name could be either absolute or relative to a directory specified in the corresponding report group deployment descriptor. If the specified file exists then the new report lines are appended to the file; otherwise, a new report file is created.

The file name may contain any of the three special macros:

  • {sequence} – The macro is replaced with an execution counter (a sequential number), which is used to generate new files for each report execution.

  • {node} – This macro is replaced with the member id of the report executing member. Use this macro to create different files for reports executed on different cluster members.

  • {date} – This macro is replaced with the current date (YYYYMMDD).

Note: a process running the reporter requires read, write, and create access to the location where the output files are created.

delim

Optional

Specifies a character that is used to separate column or array values. Valid values are: {tab}, {space}, or any non-whitespace character.

hide-headers

Optional

Specifies whether the description and the column headers should be included in the report. Valid values are true and false.

filters

Optional

Specifies a group of filters for the report.

query

Required

Specifies information necessary to construct a JMX query to find all MBeans contributing to the report or column.

row

Required

Specifies information to generate a report column.

report-config

Root Element

Description

The report-config element is the root element of the report configuration deployment descriptor and contains the report definition.

Elements

Table B-8 describes the subelements of the report-config element.

Table B-8 report-config Subelements

Element Required/
Optional		 Description

report

required

Specifies the information necessary to generate a JMX based report.

row

Used in: report-config

Description

The row element contains a list of columns to be included in the report.

Elements

Table B-9 describes the subelements of the row element.

Table B-9 row Subelements

Element Required/
Optional		 Description

column

Required

Specifies information that the Reporter uses to generate a report column.