Configuring metadata for additional element attributes

As an implementor of an pentaho-reporting extension, from time to time you will need to store additional information along with report elements.

Pentaho reporting allows all elements to carry additional attributes on elements. Attributes are stored as objects and described by metadata.

1. Attributes without metadata

If attributes are stored on elements without suitable metadata descriptions, the engine will fall back to an default mode. If the attribute value is a string, the attribute value will be stored in the PRPT file when the report is saved. Values of undeclared attributes, that are not strings, will be lost.

If the PRPT file is parsed and the xml-parser encounters an undeclared attribute, the attribute's raw string value will be stored in the parsed element. Upon the next save, such an attribute's value will be preserved.

2. Attribute Metadata properties

All meta-data in Pentho Reporting follows a similar schema. Metadata describes features and their presentation to the user. All metadata is held in various metadata registries.

The attribute metadata is bound to an element-type. Attributes are keyed by a namespace and name pair. The namespace denotes the organization responsible for maintaining the property. Metadata for extensions should be placed in their own namespace to avoid conflicts with the built-in metadata.

Element Attribute metadata properties are:

property	description
name	A internal name, used to retrieve metadata from the registry
namespace	A internal namespace, used to retrieve metadata from the registry. The name and namespace is also needed by the API.
target-type	The expected target type for the attribute. This is the name of a Java-Class. This is a hint used when parsing and writing PRPT files.
display-name	The display-name is used to name the attribute in the user-interface. This property is localized.
description	The description is used to describe the attribute in the user-interface. Use the description to provide text for tool-tips. This property is localized.
grouping	The grouping property organizes attributes and includes them in a logical grouping of similar attributes. The Pentaho Report Designer uses grouping in the user-interface to make large number of attributes more accessible.
ordinal, grouping-ordinal	Ordinals are numeric properties that define the order of properties and groups. Although they are stored in the resource bundle, they should not be localized. Grouping ordinals must be the same for the same group-localization, as the grouping text as well as the grouping ordinal are used for it.
deprecated	Deprecation is a mechanism to mark properties are obsolete. These properties will go away in the future. We mark properties as deprecated if their meaning is fundamentally broken and cannot be safely fixed. Use the deprecated-message property to give an explanation for the user.
expert	A flag indicating that the feature is for advanced users. The Report Designer can filter expert options out.
preferred	A flag marking common properties that should be highlighted to make them stand out to the user.
hidden	A flag indicating that the properties should never be shown to the user. This is usually an internal property.
experimental	A flag indicating that the property or feature is not supported. It is part of the code to test it out or to deliver it to the community. Such features may change at any time and we do not guarantee their existence or backward compatibility.
mandatory	A flag indicating that the property must have a value and cannot be <null>.
computed	A flag indicating that the property is computed by the system and therefore the value assigned can be lost at any time.
transient	A flag indicating that the property should be omitted from serialization and writing into a PRPT file. This is usually combined with the computed property.
bulk	A flag indicating that the attribute contains large data and should be written as CDATA-element instead of XML-attribute. This does not affect the runtime, but marking properties as bulk can help make PRPT contents easier to debug.
design-time-value	A flag indicating that the attribute is only modified in the design-time tools. A design-time property does not have attribute-expressions.
property-editor	Specifies the class that implements a custom property editor. Property editors allow the report-designer to specify how values are presented to the user.
value-role	A design-time hint for string-attributes. The value role can be one of "Value", "Resource", "Content", "Field", "Group", "Query", "Message", "Bundle-Key", "Bundle-Name", "Name", "ElementName", "DateFormat", "NumberFormat".

3. Declaring metadata

Metadata should be declared or parsed during the reporting engine's boot process. If metadata is registered after reports have been parsed, the reporting engine's behaviour is undefined.

The safest way to inject code into the boot process is by writing an reporting-engine extension module.

An OEM can declare attribute metadata by two methods. Either the metadata is declared in an XML file or hard-coded in a Java-Class. Both methods are equally valid and yield the same result, although the XML-declaration tends to be more maintainable.

3.1 Hard-coded attribute metadata

To declare metadata programmatically, you need to add an AttributeMetaData instance with suitable properties to the target element's attribute-registry.

The attribute registry provides access to the attribute definitions of an element and can be retrieved like this:

final AttributeRegistry registry = ElementTypeRegistry.getInstance().getAttributeRegistry("master-report");

Pentaho reporting comes with a default implementation of the AttributeMetaData interface. You will need to provide a resource-bundle for any localized property. The resource-bundle must be loadable via the standard Java-API call ResourceBundle.getBundle(..).

Our default metadata implementation queries the bundle using a known prefix and a set of well-known entries.

This is an example of an properties-file based resource bundle that contains an attribute declaration using the prefix "attribute.pir.":

&nbsp;&nbsp;&nbsp; attribute.pir.VERSION.display-name=pir-version
&nbsp;&nbsp;&nbsp; attribute.pir.VERSION.grouping=internal
&nbsp;&nbsp;&nbsp; attribute.pir.VERSION.grouping.ordinal=9900
&nbsp;&nbsp;&nbsp; attribute.pir.VERSION.ordinal=10
&nbsp;&nbsp;&nbsp; attribute.pir.VERSION.description=
&nbsp;&nbsp;&nbsp; attribute.pir.VERSION.deprecated=

The recognized attributes are:

name	description
display-name	a human-readable name for display in the user interface of design-tools
grouping	a human-readable name for groupings. All group elements must share the same name to be considered part of the same group.
grouping.ordinal	an numeric ordinal to define the group's display order. This is relative to all other groups within the same element.
ordinal	an numeric ordinal to define the attribute's display order in the UI. This value is relative to all other attributes within the same group within the same element.
description	A human-readable description, usually used for tool-tips.
deprecated	(Only applicable if the attribute is marked 'deprecated'): A human-readable message describing the reason for deprecating the element and details on which attribute or method should be used instead.

The report designer allows users to edit the values of all declared attributes. When you want to use a attribute to bind data from your application onto an report-element, you usually do not want users to see or edit these attributes.

To declare a standard hidden attribute of type 'String', which gets persisted when the report is saved, use the following code:

// the class or resource-name for the resource-bundle that holds all human-readable
// texts. This follows the standard java way of declaring and loading resources.
String bundleLocation = "org.pentaho.reporting.platform.plugin.metadata";

// the prefix for attributes. See above.
String keyPrefix = "attribute.pir.";
// Compatibility version. Needed for compatibility mode. Set this
// to the version of the reporting engine your attribute was first added.
int version = ClassicEngineBoot.computeVersionId(3, 8, 0);

// replace NAMESPACE and ATTR_NAME with your own namespace and name values
DefaultAttributeMetaData metaData = new DefaultAttributeMetaData ("NAMESPACE", "ATTR_NAME", bundleLocation, keyPrefix, String.class, true, version);

// register the new attribute with the master-report element.
AttributeRegistry registry = ElementTypeRegistry.getInstance().getAttributeRegistry("master-report");
registry.putAttributeDescription (metaData);

3.2 Declaring attributes in XML

Instead of coding the registration, it can be easier to declare the metadata via xml-files. The XML-based metadata is parsed at the beginning of the boot-process. The main metadata xml files provides extension points for developers to inject additional attributes.

The xml-based configuration works with conventions around how metadata is declared.

Elements allow to define attributes on the element-tag itself and additionally pull in attribute declarations via attribute-groups. Each element has a attribute group named after its name. For example, to configure attributes for a master-report element, use the 'master-report' attribute group.

In addition to the per-element groups, the metadata contains logical groups centred around common functions, like fields, rich-text support, etc. that is shared across several elements.

A typical attribute group declaration looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<meta-data xmlns="http://reporting.pentaho.org/namespaces/engine/classic/metadata/1.0">

   <attribute-group name="master-report">
       <attribute namespace="http://reporting.pentaho.org/namespaces/engine/attributes/pentaho/interactive-reporting"
                  namespace-prefix="pir"
                  name="VERSION"
                  mandatory="false"
                  expert="true"
                  hidden="true"
                  value-type="java.lang.String"
                  value-role="Value"
                  compatibility-level="3.8.0"/>
   </attribute-group>
</meta-data>

For attribute metadata declared in XML, the meta system expects localized content in a resource-bundle. The bundle is the same as for element attributes registered via code.

Attribute declarations in a shared group always use the fixed key prefix pattern 'attribute.<ns-prefix>.<name>.' to access properties.Attributes declared on an element declaration use the prefix pattern 'element.<type>.attribute.<ns-prefix>.<name>.' to access properties.
To inject a xml-based attribute-definition into the boot-process, you need to register the file within the module's configuration. A module's configuration is held in the 'configuration.properties' file next to the module class.

If you do not have a module, use the global configuration in the file '/classic-engine.properties', which must be placed in the root of your classpath.

Add the following key, and replace <your-id> with a unique identifier of your chosing.

org.pentaho.reporting.engine.classic.core.metadata.global-includes.<your-id>=res://com/your/company/package/metadata.properties

The configuration above assumes that the metadata is in your classpath in the package "com.your.company.package".