Chart Java API

Relevant source files

• charts/npm/demo.html
• charts/npm/src/components/pfj-chart-bullet.js
• charts/npm/src/react-wrapper.js
• charts/src/main/resources/META-INF/externs/charts.externs.js
• showcase/code.java
• showcase/package.json
• showcase/src/main/java/org/patternfly/showcase/Showcase.java
• showcase/src/web/main.js

The Chart Java API (patternfly-java-charts module) provides Java component wrappers for PatternFly chart visualizations. This module packages chart components as a GWT library (gwt-lib) that integrates with both GWT and J2CL applications. The Java API serves as a type-safe interface to chart web components that are implemented using React and distributed via the @patternfly-java/charts NPM package.

For information about the underlying web component implementation, see Chart Web Components. For details on the NPM package build process, see Chart Build and Publishing.

Module Overview

The patternfly-java-charts module follows the standard PatternFly Java architecture but uses specialized packaging to support chart-specific requirements. The module provides Java component classes that extend BaseComponent and integrate with the chart web components at runtime.

Sources: charts/pom.xml1-77

GWT Library Packaging

The charts module uses the gwt-lib packaging type, which differs from standard JAR packaging in several important ways:

Aspect	Configuration	Purpose
Packaging Type	gwt-lib	Produces a GWT library archive suitable for both GWT and J2CL consumption
Module Name	org.patternfly.Charts	Defines the GWT module descriptor location
Resource Inclusion	.js files from src/main/java and src/main/resources	Includes JavaScript resources needed by chart components

The gwt-lib packaging is configured via the gwt-maven-plugin:

charts/pom.xml68-74

This packaging type ensures that:

1. Java source files are included in the artifact for compilation
2. GWT module descriptors (.gwt.xml files) are preserved
3. JavaScript resources are bundled with the library
4. The artifact can be consumed by both GWT and J2CL projects

Sources: charts/pom.xml31 charts/pom.xml68-74

Module Dependencies

The charts module depends on two core PatternFly Java modules:

Core Dependencies

1. patternfly-java-core - Provides foundational classes:

   • BaseComponent for HTML element wrapping
   • Elemento builder API integration
   • Component lifecycle management
   • Event handling infrastructure

2. patternfly-java-tokens - Provides design system integration:

   • Token enum with CSS custom properties
   • Design token constants for styling
   • Access to PatternFly theme variables

charts/pom.xml35-43

Sources: charts/pom.xml35-43

JavaScript Resource Handling

The charts module includes JavaScript files as resources, which are packaged with the GWT library for runtime access. This configuration allows chart components to load necessary JavaScript code when integrated into applications.

The resource configuration includes two directories:

charts/pom.xml52-64

This dual-directory approach allows:

• Co-location of JavaScript code with Java components (src/main/java)
• Separation of pure JavaScript resources (src/main/resources)
• Flexible resource organization while maintaining GWT compatibility

Sources: charts/pom.xml52-64

GWT Module Descriptor

The module defines a GWT module descriptor named org.patternfly.Charts, which serves as the entry point for integrating chart components into GWT applications. Applications using charts must inherit this module in their own .gwt.xml file:

The module descriptor:

1. Declares dependencies on patternfly-java-core and patternfly-java-tokens modules
2. Specifies source paths for Java-to-JavaScript compilation
3. Configures resource loading for JavaScript files
4. Ensures proper inheritance chain for GWT compilation

charts/pom.xml72

Sources: charts/pom.xml72

Chart Component Architecture

Chart components in the Java API follow the standard PatternFly Java component pattern, extending BaseComponent to wrap custom HTML elements. The architecture bridges type-safe Java code with React-based web components through a carefully designed interop layer:

Chart Component Flow

1. Java Component Creation - Developer instantiates a chart component (e.g., ChartDonut)
2. Element Generation - Component creates custom HTML element (<pfj-chart-donut>)
3. Attribute Binding - Component properties are set as element attributes
4. Type Safety - Externs file ensures Closure Compiler preserves property names
5. Web Component Activation - Browser activates custom element definition
6. React Rendering - ReactWrapperElement renders corresponding React chart component

Sources: charts/pom.xml36-39 charts/src/main/resources/META-INF/externs/charts.externs.js1-205

Available Chart Types

The Java API provides components for the following chart types:

Chart Type	Java Component	Web Component Tag	React Component
Donut Chart	ChartDonut	pfj-chart-donut	ChartDonut
Donut Utilization	ChartDonutUtilization	pfj-chart-donut-utilization	ChartDonutUtilization
Donut Threshold	ChartDonutThreshold	pfj-chart-donut-threshold	ChartDonutThreshold
Bullet Chart	ChartBullet	pfj-chart-bullet	ChartBullet
Pie Chart	ChartPie	pfj-chart-pie	ChartPie

Each Java component extends BaseComponent and provides builder methods for chart configuration.

Sources: charts/npm/README.md9-15 charts/npm/demo.html49-109

Type Safety with Externs

For J2CL compilation, the charts module includes a Closure Compiler externs file that declares JavaScript types used by chart components. This ensures property names are preserved during minification and provides type checking between Java and JavaScript.

Externs File Structure

Title: Externs Type Hierarchy

Key Extern Declarations

The externs file declares constructors and properties for:

Base Chart Properties (declared on ChartElement):

• categories - Array of category strings
• height / width - Numeric dimensions
• labels - Function for label generation (LabelsFn)
• legendData - Array of legend entries
• legendOrientation / legendPosition - String constants
• padding - Padding object with top/right/bottom/left
• subTitle / title - Title strings
• themeColor - Theme color string

Donut-Specific Properties (declared on DonutElement, DonutUtilizationElement, DonutThresholdElement):

• data - Chart data array or single data point
• thresholds - Array of threshold values for utilization charts

Bullet-Specific Properties (declared on BulletElement):

• comparativeErrorMeasureData / comparativeWarningMeasureData - Comparative measure arrays
• primaryDotMeasureData / primarySegmentedMeasureData - Primary measure arrays
• qualitativeRangeData - Range data array
• Corresponding *LegendData arrays for each measure type

Why Externs Are Necessary

When J2CL compiles Java to JavaScript, the Closure Compiler performs aggressive optimizations including property renaming. Without externs:

1. Property names like data, height, labels would be minified
2. The web components wouldn't recognize the minified property names
3. Chart rendering would fail at runtime

The externs file tells Closure Compiler: "These property names are part of an external API - preserve them exactly as written."

Sources: charts/src/main/resources/META-INF/externs/charts.externs.js1-205

Usage Patterns

Basic Chart Creation

Java components use a fluent builder API consistent with other PatternFly Java components. Chart data is typically set via properties that correspond to the web component attributes:

Data Binding Patterns

Chart components accept data in formats that match the web component API:

Simple Data (for donut utilization):

Array Data (for donut, pie, bullet charts):

Threshold Data (for utilization with thresholds):

Dynamic Updates

Charts can be updated after creation by modifying properties:

Legend Configuration

Charts support legend customization through properties:

Bullet Chart Patterns

Bullet charts have specialized data properties for different measure types:

Sources: charts/npm/demo.html54-109 charts/npm/README.md33-85 charts/npm/src/components/pfj-chart-bullet.js19-193

JavaScript Property Mapping

The Java API properties map to web component attributes and JavaScript properties. The mapping follows these patterns:

Attribute Conversion:

• Java camelCase property → Kebab-case HTML attribute
• Example: legendPosition → legend-position

Property Types:

• Primitives (string, number, boolean) → Set as HTML attributes
• Objects/Arrays → Set as JavaScript properties via element API
• Functions → Set as JavaScript properties (closures preserved)

Parsing in Web Components:

The web component layer (ReactWrapperElement) parses attributes using parseAttrValue:

The BOM (patternfly-java-bom) manages the version automatically.

GWT Applications

Inherit the Charts module in your .gwt.xml file:

This:

• Adds chart component sources to GWT compilation
• Includes necessary JavaScript resources
• Resolves transitive dependencies (core, tokens)

J2CL Applications

For J2CL projects:

1. Include patternfly-java-charts in the classpath
2. Ensure patternfly-java-j2cl module is present (handles integration)
3. The externs file is automatically included via META-INF/externs/ directory

The J2CL build process:

• Compiles Java chart components to Closure-compatible JavaScript
• Applies externs to preserve property names
• Bundles with other application code

Runtime Requirements

NPM Package Installation

The @patternfly-java/charts NPM package must be available at runtime:

JavaScript Import

Import the chart components in your application's main JavaScript file:

This registers the custom element definitions for all chart web components.

PatternFly CSS

Charts require PatternFly stylesheets:

Complete Example (from showcase application):

showcase/src/web/main.js16-19

Sources: charts/pom.xml1-77 showcase/src/web/main.js16-19 showcase/package.json21-25

J2CL Compilation Considerations

When compiling chart components with J2CL:

Externs Location

The externs file is located at:

charts/src/main/resources/META-INF/externs/charts.externs.js

J2CL automatically discovers and applies externs from META-INF/externs/ directories in dependencies.

Resource Packaging

The build configuration ensures JavaScript resources are packaged:

charts/pom.xml52-64

This configuration:

• Includes .js files from src/main/java (co-located with Java sources)
• Includes .js files from src/main/resources (standalone resources)
• Makes resources available to both GWT and J2CL toolchains

JsInterop Annotations

While the externs file provides type declarations, Java chart components may use @JsType, @JsProperty, and related annotations for direct JavaScript interop. These annotations:

• Mark types that interact with JavaScript
• Enable direct method calls on JavaScript objects
• Ensure proper type checking during compilation

Sources: charts/pom.xml52-64 charts/src/main/resources/META-INF/externs/charts.externs.js1-25

Testing Configuration

The charts module includes JUnit Jupiter for unit testing, following the standard PatternFly Java testing approach:

charts/pom.xml45-48

Tests verify:

• Component initialization and configuration
• Attribute serialization for web component integration
• Design token application
• Element hierarchy construction

Sources: charts/pom.xml45-48