B Report File Configuration Elements

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 Elements," for a detailed reference of the report group deployment descriptor elements.

This appendix includes the following sections:

• Report File Deployment Descriptor

• Element Reference

B.1 Report File Deployment Descriptor

The report file deployment descriptor specifies a report for displaying management information that is based on MBeans. The coherence.jar/reports directory contains many predefined report files. Modify the reports or create new reports as required. See Chapter 6, "Analyzing Report Contents," for additional information about the predefined 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 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 that is located in the coherence.jar library is always used at run time even if the xsi:schemaLocation attribute references the Web URL.

• Omit the xsi:schemaLocation attribute to disable schema validation.

• When deploying Oracle 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 nonterminal report file deployment descriptor elements.

Table B-1 Report File Deployment Descriptor Nonterminal 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 subelement.

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. The following values are valid: attribute – (default) A column that contains the data from an MBean attribute. key – A column that contains the value from an MBean key attribute. method – A column that contains the result of an MBean method invocation. function – A column that contains the result of a function or aggregation. See the function-name element in this table. 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 that contains a constant string of numeric value. property – A column that 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. The value of the name element is used if this item is omitted.
delim	Optional	Specifies a character that separates 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 is hidden in the report. Valid values are true and false.
column-ref	Optional	Specifies a reference to a column identifier. The reference passes 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. The following values are valid: 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 is 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 is returned to the query. Negative values are considered error or not available codes on Oracle Coherence MBeans. By default, these codes return zero to not affect column calculations. Valid values are true and false. The default values is false.

filter

Used in: filters

Description

The filter element defines a filter to use in the report. The filter element supports the use of an id attribute to uniquely identify the filter. Use the ID when referring to a filter with the filter-ref element. Filters can be referenced from within a params element and a query 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. The following values are valid: equals – A filter that compares the result of two or more column references for a value equality. greater – A filter that compares the results of two column references for the 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 that compares the results of two column references for the less than condition. If any of the values is resolved to null, the evaluation yields false. not – A filter that returns the logical not of a filter reference. and – A filter that returns the logical and of two filter references. or – A filter that 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 any number 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	Defines a filter to use in the report

params

Used in: column, filter, query

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 passes a filter as an argument to a query or another filter.
column-ref	Required	Specifies a reference to a column identifier. The reference passes 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. Enter queries within a <pattern> element.

Examples

The following example includes all node MBeans in the report or column:

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

The following 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 in the query pattern, define a reporter.cacheName system property 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. Use the key attribute to retrieve an attribute from a related (joined) MBean. For example, because the Coherence:type=Service,* pattern is known to result in MBeans in the Coherence:type=Service,nodeId=NNN format, the following configuration below prints 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 include in the report
filter-ref	Optional	Specifies a reference to a filter ID. The reference passes 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. A report can include any number of report elements; however, a report file typically contains a single report definition.

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 associated report or column.
file-name	Required	Specifies the file name for the generated report. The file name is either absolute or relative to a directory that is 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 three macros: {batch} – This macro is replaced with a counter (a sequential number). {node} – This macro is replaced with the cluster member ID. Use this macro to differentiate reports 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 report output directory.
delim	Optional	Specifies a character that separates column or array values. Valid values are {tab}, {space}, or any non-whitespace character.
hide-headers	Optional	Specifies whether the report includes description and column headers. 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 row

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 include 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 the information that generates a report column