Documentation

the highcharts java api

REQUIREMENTS

To use this library your Java web framework must be able to add the generated chart options to your Javascript in your page before sending to the browser.

A valid Highcharts license is also required. Please refer to Highcharts license page for further details.

OVERVIEW

The Highchart class is the starting point for all charts. It represents a single chart.
It has methods getGlobalOptions() and getChartOptions() to allow the setting of all global and chart options.
It has methods globalOptionsToJson() and chartOptionsToJson() to generate the options in json.

To define the contents of a chart, you simply have to instantiate the Highchart class and use its setter methods to define the chart options and chart data as required. For details on the effects of each chart option refer to the Highcharts API reference. The naming of the chart options in the HyJavaCharts library exactly follows the Highcharts Javascript API.

In the example below we are defining a bar chart.
Instantiate the Highchart class and then get a reference to ChartOptions. You then set the chart options as required.

public class YourBarChart {

 public Highchart generate() {
  Highchart highChart = new Highchart();
  ChartOptions chartOptions = highChart.getChartOptions();

  chartOptions.chart().type(ChartType.BAR);
  chartOptions.title().text("Historic World Population by Region");
  chartOptions.subtitle().text("Source: Wikipedia.org");

  set your options......

  return highChart;
 }

}

JAVADOC API

In most cases the HyJavaCharts API exactly matches the Highcharts API. There is no need to learn another API. The HyJavaCharts API can be viewed online or refer to the API jar provided in the product download.

DEMO WEB APPLICATION

To give you a kick start using the library, the demo web application provides thorough examples of more than 80 different charts including Java source code for each example. Most of the Highcharts Demos from the Highcharts Demos page are included in this application.
The full Java source code for the entire demo application is also available from the downloads page.

HOW TO USE THE LIBRARY

Java
Include the HyJavaCharts jar in your project.

Create your chart and get the global and chart options json values.

Highchart hc = new YourBarChart().generate();
String globalOptionsJson = hc.globalOptionsToJson();
String chartOptionsJson = hc.chartOptionsToJson();

The YourBarChart class will look something like this

public class YourBarChart {

 public Highchart generate() {
  Highchart highChart = new Highchart();
  ChartOptions chartOptions = highChart.getChartOptions();

  chartOptions.chart().type(ChartType.BAR);
  chartOptions.title().text("Historic World Population by Region");
  chartOptions.subtitle().text("Source: Wikipedia.org");

  set your options......

  return highChart;
 }

}

Javascript
Include required Javascript on your page as per Highcharts documentation.

Highcharts.setOptions(${globalOptionsJson});
Highcharts.chart('container', ${chartOptionsJson});

Your Java code will generate the json for ${globalOptionsJson} and ${chartOptionsJson}.
Add the options strings to your Javascript.

Thats it. You now have a working Bar chart example.

JAVA CHART OPTION METHOD NAMES

You have the choice to use method names to set each chart option that closely match the Highcharts Javascript API or use the getter/setter method names that follow the standard Java camelcase naming convention. Its totally up to you to use the naming convention you are most comfortable with.

Javascript:
chart: { type: 'bar' }

Java:
chartOptions.chart().type(ChartType.BAR);
 OR
chartOptions.getChart().setType(ChartType.BAR);

OPTIONS WITH MULTIPLE DATA TYPES

Where a chart option has more than one data type, eg. Number or String the Java API will include one method per type.

chartOptions.pane().innerRadiusAsNumber(25);
chartOptions.pane().innerRadiusAsString("50%");

DATA TYPES

Usage of Color Class
To set a color string value use: new Color(“#55BF3B”); or new Color().setColor(“#55BF3B”);
To set a json color value use: new Color().setJsonString(“jsonvalue”);

Usage of CSSObject Class
To set a CSS json value use: new CSSObject(“jsonvalue”); or new CSSObject().setCssString(“jsonvalue”);

Usage of Function Class
To set the body of a Function use: new Function(“functionbodystring”); or new Function().setFunctionBody(“functionbodystring”);
To add parameters to the function use: addParameter(“parameter”);

Usage of JsonObject Class
To set a Json value use: new JsonObject(“jsonvalue”); or new JsonObject().setJsonString(“jsonvalue”);

ARRAYS

There are methods for each chart option array to help simplify usage where there is only 1 element in the array.
In the example the xAxisSingle() method will add a new XAxis object to the xAxis array and operate on that object.

XAxis xAxis = new XAxis();
xAxis.allowDecimals(false);
chartOptions.xAxis().add(xAxis);
 OR
chartOptions.xAxisSingle().allowDecimals(false);

THEMES

Include your chosen theme.js on your page as per Highcharts documentation.
If your Java code uses the chartOptions.color() or chartOptions.getColor() methods you will also need to set the Theme in your Java prior to calling those methods.
eg. highChart.setTheme(Theme.DARK_UNICA);
All 10 standard Highcharts themes have been created in Theme.

If you have created your own theme you will need to create a Theme class as follows:
(1) create a new theme class implementing Theme.
(2) add the method getColors() to the class returning your theme colors.

public class YourNewTheme implements Theme {
  public List<Color> getColors() {
   return new ArrayList(Arrays.asList(
     new Color(Color.LIGHTSKYBLUE), new Color(Color.LIGHTGREEN), new Color(Color.LIGHTSALMON), 
     new Color(Color.LIGHTCORAL), new Color(Color.LIGHTSTEELBLUE), new Color(Color.LIGHTGRAY),
     new Color(Color.LIGHTPINK), new Color(Color.LIGHTSEAGREEN), new Color(Color.LIGHTCYAN),
     new Color(Color.LIGHTBLUE), new Color(Color.LIGHTYELLOW), new Color(Color.LIGHTSLATEGRAY)
     ));
   }
 }

You can also use color strings ie. new Color(“#87cefa”).
To use the theme: highChart.setTheme(new YourNewTheme());

CHART DATA SOURCES

Chart data sources can be databases, web services, files or any resource your application server has access to.
The Highcharts Data module allows access to CSV, HTML tables or remote CSV data by specifying a URL.

API ISSUES

Every endeavor has been made to ensure the HyJavaCharts Java API matches the Highcharts Javascript API.
Please contact us if there is a chart option missing from the Java API or if an option data type does not match the Highcharts API.
We will publish an updated API as soon as possible.

Generic Chart Options
Three generic options are available per option grouping to allow the developer to continue until the API is updated.
eg. If an option “allowAnimation” Boolean was missing from Chart in the API or the data type is incorrect you can still include the option as shown below.

 chartOptions.chart().get_genericOption1()
    .setName("allowAnimation")
    .setJsonStringValue("true");

SUPPORT

For any questions or issues on the HyJavaCharts API please contact our support team via the “Contact Us” area on the home page.
Please refer to the Highcharts API for usage of each chart option or contact Highcharts for support of the Highcharts product.