OVERVIEW
The HyJavaImages library is a pure Java library that allows you to create PNG, JPEG, WEBP and PDF images of your JavaScript charts.
There is built-in support for Highcharts, Highcharts Stock, ApexCharts and Vaadin charts JavaScript charting libraries.
There are Java methods to convert:
- Highcharts, Highcharts Stock, Apexcharts and Vaadin charts chart options to a base64 encoded image in PNG, JPEG, WEBP or PDF format
- HTML to a base64 encoded image in PNG, JPEG, WEBP or PDF format
- A URL to a base64 encoded image in PNG, JPEG, WEBP or PDF format
The chart options method above allows for direct integration with HyJavaCharts, HyJavaStock, HyJavaApex and Vaadin charts.
You are now able to generate JavaScript charts and create an image, all from within a Java application on the server, with no JavaScript coding!
The library also allows you to create an image of any web page or supplied HTML text.
This allows you to create images of charts generated using any JavaScript charting library.
The library will start a Chrome headless server/or connect to an existing running Chrome headless server.
It then establishes a Web Socket connection to the Chrome headless server and uses the DevTools Protocol to control Chrome.
LIBRARY DOCUMENTATION
The best sources of documentation on how to use the libary are:
- This document.
- The HyJavaImages Javadoc.
The Javadoc contains a large amount of information on how best to use the library. - The Demo application included in the download.
The demo application contains many examples on how to use the library.
JAVADOC API
The HyJavaImages API can be viewed online or refer to the API jar provided in the product download.
HOW TO USE THE LIBRARY
Ensure Chrome is installed on your system.
Include the HyJavaImages jar in your project.
The code below will generate a base64 encoded string in png format for Highcharts, Highcharts stock and Apexcharts chart options.
// Startup Chrome headless - (1)
Chrome chrome = Chrome.getInstance();
chrome.start();
// Generate as many chart images as needed - (2)
String base64;
ImageGenerator img = new ImageGenerator();
// Highchart png example - (3)
img.setJavaScript(LibraryType.HIGHCHARTS, null, "highcharts.js");
base64 = img.toBase64Image("{your chart options...}");
// Highstock png example - (3)
img.setJavaScript(LibraryType.HIGHCHARTS_STOCK, null, "stock/highstock.js");
base64 = img.toBase64Image("{your chart options...}");
// ApexCharts png example - (3)
img.setJavaScript(LibraryType.APEXCHARTS, null);
base64 = img.toBase64Image("{your chart options...}");
// HTML text png example
base64 = img.htmlToBase64Image("<html> your html... </html>");
// URL png example
base64 = img.toBase64Image(new URL("https://www.google.com"));
// Close down Chrome headless - (4)
chrome.stop();
Code description:
(1) Get the instance of Chrome and start the Chrome headless server using all defaults.
In a web servlet application chrome.start() should be called once in Servlet.init().
(2) The ImageGenerator class provides all methods to generate chart images.
(3) The setJavaScript method tells the library which JavaScript libraries to use to render the chart. The 2nd parameter is the library version or null for the latest.
(4) Stop the Chrome headless server.
In a web servlet application chrome.stop() should be called once in Servlet.destroy().
MAIN LIBRARY CLASSES
Chrome Class
The Chrome class is a singleton that provides methods to control the Chrome headless server.
Main functionality:
- Starts and Stops a new instance of a Chrome headless server. See the start() and stop() methods.
- Chrome is started with a set of default Chrome arguments. Chrome arguments can be specified using the setChromeArguments() method.
- When starting Chrome, the library will search in the standard install locations for the Chrome binary. If the library cannot find the binary or you wish to use a non-standard install you can also specify the Chrome binary with the setChromeBinaryPath() method.
Search locations:
Linux: “/opt/google/chrome/chrome”;
Windows: “/Program Files/Google/Chrome/Application/chrome.exe” and “/Program Files (x86)/Google/Chrome/Application/chrome.exe”;
MacOS: “/Applications/Google Chrome.app/Contents/MacOS/Google Chrome”. - The library can connect/disconnect from an existing running Chrome headless server. See the connect() and disconnect() methods. Chrome headless would need to be started by another process. I.E. not by the HyJavaImages library.
- When starting/connecting with the start() or connect() methods the library will create a pool of Chrome pages ready for re-use.
The default pool size value of 2 will suit most applications. Large volume applications can set this to a higher value to handle a higher concurrency.
See the setPoolSize() method.
When generating images the library will acquire a page from the pool, generate the image, release the page back to the pool. If there are no available pages in the pool the library will wait until one becomes free. - By default the Chrome headless server will listen on a random available port. You can specify the port using the setPort() method.
- By default the image size created will be 800 x 600 pixels. You can specify the image size using the setWindowSize() method.
- HyJavaImages can also be run as a HTTP server. To route HyJavaImages requests to a shared HTTP server use the setViaHTTPServerURL() method. Refer to the HTTP Server section below.
ImageGenerator Class
The ImageGenerator class provides methods to generate the required PNG/JPEG/WEBP/PDF images.
Main functionality:
- To generate a chart image Base64 encoded string from Highchart, Highchart stock or Apexcharts chart options see the toBase64Image() methods.
- To generate a chart image Base64 encoded string from html text see the htmlToBase64Image() methods.
- To generate a chart image Base64 encoded string from a URL see the toBase64Image() methods.
- One or more sets of global chart options can be specified with the setGlobalOptions() method.
- By default the image created will be 800 x 600 pixel in PNG format. If required use the ImageOptions class to define the image format (PNG/JPEG/WEBP); the JPEG quality; the image scale (resolution); a full page image; the x, y, width and height to determine the rectangular area that the image will be taken from.
- By default the PDF created will be portrait, 8.5 x 11 inch with 0.4 inch margins. If required use the PdfOptions class to define the paper size; the paper width and height, the margins; portrait or landscape; the header/footer; continuous page; page ranges; scale. There are static helper methods cm() and px() to convert cm and pixels to inches.
- The setJavaScript() and setJavaScriptAlternate() methods enable the library to load the required JavaScript to render the chart. Also see the setJavaScriptAdditional() and setJavaScriptStatements() methods.
- If required use the setCSSExternal() and setCSSInternal() methods to enable the library to load any required CSS.
- Each chart is contained within its own div tag. If required use the setChartDivAttributes() method to define the chart div tag attributes. The method can be used to specify values for the style or class attributes of the div. Also see the setChartDivSize() method.
- To emulate a device, media type, locale, timezone or geolocation see the setEmulate…() methods.
- To include multiple charts in the one image see the setAdditionalChartOptions() method. Also the setAdditionalChartDivAttributes() and setChartGroupDivAttributes() methods may be of interest.
VAADIN CHARTS SUPPORT
If you are using the library with Vaadin Charts, you will need to include some additional JavaScript as Vaadin Charts modifies the JSON generated.
Include the following method calls:
img.setJavaScriptAdditional("https://www.hyjavacharts.com/content/js/vaadin-inflate.js");
img.setJavaScriptChartOptions("__inflateFunctions(chartOptions);");
We recommend you download the vaadin-inflate.js JavaScript and store it locally.
RUNNING CHROME AS ROOT
On Linux based systems if you wish to run Chrome as root and are seeing this error: “ERROR: Running as root without –no-sand-box is not supported.”, you will need to include a Chrome Argument before starting Chrome.
chrome.setChromeArguments(new ChromeArguments().addArgument("--no-sandbox"));
chrome.start();
HyJavaImages HTTP SERVER
The HyJavaImages HTTP server is a high performance HTTP server that allows all HyJavaImages requests to be routed to a shared HTTP server.
The HTTP server will handle all image generation requests and return the base64 image format.
To use the HTTP server the only code change required is to replace the Chrome.start() method with the Chrome.setViaHTTPServerURL() method.
Your applications would not be required to start a Chrome headless server.
For more information see the HyJavaImages HTTP Server Product page.
REQUIREMENTS
You must have Chrome 71 or later installed on your system. The library requires a Chrome version that supports the DevTools protocol v1.3.
To render Highcharts chart images the HyJavaImages library requires a commercial or free Non-commercial license for the Highcharts JavaScript library.
To render Highcharts Stock chart images the HyJavaImages library requires a commercial or free Non-commercial license for the Highcharts Stock JavaScript library.
Please refer to the Highcharts license page for further details.
JAVA VERSION
The HyJavaImages library requires Java 8 or greater.
SUPPORT
If you have any questions or issues on the HyJavaImages library, please contact our support team via the Contact Us area on the home page.