HyJavaStock Full Documentation

the java api for highcharts stock

OVERVIEW

The HyJavaStock Java library is a pure Java wrapper for the Highcharts Stock Javascript library.
It allows your Java-based web applications to configure Highcharts Stock charts using only Java methods. There is no need to write any Javascript.
The library will generate the required Javascript code that Highcharts Stock needs to render the charts.

The Highstock class is the starting point for all charts.

To define the contents of a chart, you simply have to instantiate the Highstock 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 Stock API reference. The naming of the chart options in the HyJavaStock library in most cases exactly follows the Highcharts Stock Javascript API.

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

public class HighstockChart {

	public Highstock configure() {
		Highstock highStock = new Highstock();
		ChartOptions chartOptions = highStock.getChartOptions();
		
		chartOptions.getChart().setAlignTicks(false);
		chartOptions.getTitle().setText("AAPL Stock Volume");

		set all your required chart options......
		
		return highStock;
	}
	
}

JAVADOC API

In most cases the HyJavaStock API exactly matches the Highcharts Stock API. There is no need to learn another API. The HyJavaStock 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 many charts including Java source code for each example. Most of the Highcharts Stock Demos from the Highcharts Stock Demos page are included in this application.
The Java source code for the demo application including all chart examples is available from the Other Downloads page.

HOW TO USE THE LIBRARY

Java

Include the HyJavaStock jar in your project.

Configure your chart and generate the Javascript code for the global and chart options.

Highstock hs = new HighstockChart().configure();
String globalOptionsJs = hs.globalOptionsToJs();
String chartOptionsJs = hs.chartOptionsToJs();


The HighstockChart class will look something like this:

public class HighstockChart {

	public Highstock configure() {
		Highstock highStock = new Highstock();
		ChartOptions chartOptions = highStock.getChartOptions();
		
		chartOptions.getChart().setAlignTicks(false);
		chartOptions.getTitle().setText("AAPL Stock Volume");

		set all your required chart options......
		
		return highStock;
	}
	
}
Javascript

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

Highcharts.setOptions(${globalOptionsJs});
Highcharts.stockChart('container', ${chartOptionsJs});

Your Java code will pass the globalOptionsJs and chartOptionsJs strings to the markup variables ${globalOptionsJs} and ${chartOptionsJs}.
The method used to pass the generated chart options from the java to the web page will vary depending on your java web framework. (Refer to Java Web Frameworks below).

Web Page

Your markup will look something like this:

<script src=https://code.highcharts.com/stock/highstock.js></script>

<div id="container" style="min-width: 310px; max-width: 800px; height: 400px; margin: 0 auto"></div>

<script>
Highcharts.setOptions(${globalOptionsJs});
Highcharts.stockChart('container', ${chartOptionsJs});
</script>


That is all that is required to get a working Highcharts Stock chart example.

MAIN LIBRARY CLASSES

GlobalOptions Class

The GlobalOptions class maps directly to the Highcharts Stock global options in the Highcharts Stock API.
All Highcharts Stock global options will be configured using setter methods on this class.

ChartOptions Class

The ChartOptions class maps directly to the Highcharts Stock chart options in the Highcharts Stock API.
All Highcharts Stock chart options will be configured using setter methods on this class.

Highstock Class

The Highstock class wraps both the GlobalOptions and ChartOptions classes into one convenient class to make usage as simple as possible.
This class handles chart theming; the setting of global and chart options; generates Javascript for GlobalOptions and ChartOptions.
All Highcharts Stock global options can be configured by getting a reference to GlobalOptions from this class via getGlobalOptions().
All Highcharts Stock chart options can be configured by getting a reference to ChartOptions from this class via getChartOptions().
Usage of the Highstock class has been described in examples above.

HighstockOptions Class

As an alternative to using the Highstock class, global and chart options can be configured separately by using the GlobalOptions and ChartOptions classes outside of the Highstock class. Global options can be configured once and will apply to multiple charts. Global options are optional.
Usage is described below.

The HighstockOptions class handles chart theming and generates Javascript for GlobalOptions and ChartOptions.

Configure your chart and get the generated Javascript code for the global and chart options.

GlobalOptions globalOptions = new GlobalOptions();
globalOptions.getGlobal().setUseUTC(false);
set all your required global options......

ChartOptions stockChartOptions = new HighstockChart().configure();

String globalOptionsJs = new HighstockOptions().toJs(globalOptions); 
String chartOptionsJs = new HighstockOptions().toJs(stockChartOptions); 


The HighstockChart class will look something like this:

public class HighstockChart {

	public ChartOptions configure() {
		ChartOptions chartOptions = new ChartOptions();
		
		chartOptions.getChart().setAlignTicks(false);
		chartOptions.getTitle().setText("AAPL Stock Volume");
		
		set all your required chart options......
		
		return chartOptions;
	}
	
}
HighstockRenderer Class

The HyJavaStock library performance is extremely fast right out of the box.
In cases where thousands of charts are generated, for example batch processes, some improvements can be found using HighstockRenderer.toJs(…) rather than the Highstock.chartOptionsToJs() and Highstock.globalOptionsToJs().
Instantiate the HighstockRenderer class once and then use it to generate the chart options Javascript for multiple charts.
Note that there are no improvements when generating single charts.

JAVA WEB FRAMEWORKS

The HyJavaStock library is a pure Java library so can be used by any Java web framework.

As long as your framework can add the generated Javascript chart options to your markup at page build time then you can use this library.
Most (if not all) Java web frameworks will offer some method of adding javascript to a page.

We have included several example applications showing usage of the HyJavaStock library with various frameworks. These include:-

  • a Spring MVC demo web application;
  • a JSF demo web application;
  • a Struts2 demo web application;
  • a GWT demo web application;
  • a basic servlet demo web application;
  • a JSP servlet demo web application;
  • a Wicket demo web application;
  • a Vaadin framework 8 demo web application;
  • a Vaadin platform (14+) demo web application;
  • a JavaFX demo application;
  • a Java Swing demo application.

  • The Java source code for these example applications is available from the Other Downloads page.

    OPTIONS WITH MULTIPLE DATA TYPES

    Where a chart option has more than one data type, eg. Number and String the Java API will include one method per type.
    Setter methods will be overloaded. Getter methods will include a suffix.

    chartOptions.getChart().setWidth(25);
    chartOptions.getChart().setWidth("50%");
    
    chartOptions.getChart().getWidthAsNumber();
    chartOptions.getChart().getWidthAsString();

    SETTING OPTIONS TO NULL

    In some (rare) cases you need to set a Highcharts Stock chart option to null. Where a chart option has only one datatype you simply set the option to null as below.

    chartOptions.getChart().setBorderRadius(null);
    


    Where a chart option has more than one data type, eg. Number and String, the setter method will be overloaded. You can use the helper class NullOption to set the option to null.

    chartOptions.getChart().setWidth(NullOption.NULL_STRING);
    OR
    chartOptions.getChart().setWidth(NullOption.NULL_NUMBER);
    


    Where a chart option has more than one data type and the type is a chart option class, eg. Chart.animation has datatypes Boolean and AnimationOptions. You can use the helper static variable AnimationOptions.NULL to set the option to null. Every chart option class has a static variable named NULL to make this as easy as possible.

    chartOptions.getChart().setAnimation(AnimationOptions.NULL);
    

    MAIN OPTION DATA TYPES

    Color Class

    Maps to the Highcharts Color, Highcharts.ColorString, Highcharts.GradientColorObject, Highcharts.PatternOptionsObject data types.
    To set a color string value use: new Color(“#55BF3B”); or new Color().setColor(“#55BF3B”);

    To set a javascript color value use: new Color().setColorValue(“jsvalue”);
    To set a RGB color value use: new Color(255, 255, 255); or new Color().setRGB(255, 255, 255);
    To set a RGBA color value use: new Color(255, 255, 255, 0.5); or new Color().setRGBA(255, 255, 255, 0.5);
    To set a linear or radial gradient color value use: new Color(LinearGradient, stops); or new Color(RadialGradient, stops);
    To set a pattern fill color value use: new Color(PatternOptions);
    To brighten a color use: new Color(“#55BF3B”).brighten(0.2); or new Color(255, 255, 255).brighten(0.2); or new Color(255, 255, 255, 0.5).brighten(0.2);

    140 Web color code strings are also defined in this class. Eg. new Color(Color.ALICEBLUE).

    CSSObject Class

    Maps to the Highcharts CSSObject or Highcharts.CSSObject data type.
    To set a CSS javascript value use: new CSSObject(“jsvalue”); or new CSSObject().setCssValue(“jsvalue”);
    Use the methods provided to set any of the other available CSS options.

    Function Class

    Maps to the Highcharts Function or any Highcharts.*CallBackFunction data type.
    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”);

    General Class

    To set a javascript value use: new General(“jsvalue”); or new General().setJsValue(“jsValue”);

    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.setAllowDecimals(false);
    chartOptions.getXAxis().add(xAxis);
       OR
    chartOptions.getXAxisSingle().setAllowDecimals(false);

    THEMES

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

    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());

    If you are using the ChartOptions class then set your theme with:
    new HighchartOptions().setTheme(HighchartTheme.DARK_UNICA, chartOptions);
    or
    new HighchartOptions().setTheme(new YourNewTheme(), chartOptions);

    As an alternative to defining your theme in Javascript it is also possible to define the full Theme in Java.
    Instantiate the Highstock class, get a reference to ChartOptions and configure all required theme chart options.

    You would then apply the theme on your web page by using the Highcharts.setOptions() Javascript method.
    Please refer to the Highcharts Theme documentation for further details.

    CHART DATA SOURCES

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

    JAVA VERSION

    The HyJavaStock library requires Java 8 or greater. There are no external dependencies.

    API ISSUES

    Every endeavor has been made to ensure the HyJavaStock Java API matches the Highcharts Stock 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 Stock API.
    We will publish an updated API as soon as possible.

    Generic Chart Options

    To allow the developer to continue until the Java API is updated, generic options that can have any property name and value are available on every Highstock model class.
    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.getChart().get_genericOption()
        .add(new GenericOption("allowAnimation", "true"));
    OR
    chartOptions.getChart().get_genericOption()
        .add(new GenericOption()
            .setPropertyName("allowAnimation")
            .setPropertyValue("true"));

    SUPPORT

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

    The Java API’s fully support all chart types and chart options in Highcharts v5.x, v6.x, v7.x, v8.x;  Highcharts Stock v8.x and ApexCharts v3.x.


    Current versions supported are:

    HyJavaCharts

    HyJavaStock

    HyJavaApex

    Start the HyJavaCharts demo Java web application


    Start the HyJavaStock demo Java web application


    Start the HyJavaApex demo Java web application