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 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.
There are methods to tune Chrome in high volume applications. See the Chrome.setPoolSize() method in the API.
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.
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.
(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.
(4) Stop the Chrome headless server.
In a web servlet application chrome.stop() should be called once in Servlet.destroy().
MAIN LIBRARY CLASSES
The Chrome class is a singleton that provides methods to control the Chrome headless server.
- Starts and Stops a new instance of a Chrome headless server. See the start() and stop() methods.
- Chrome headless is started with a set of default Chrome arguments. Chrome arguments can be specified using the setChromeArguments() method.
- When starting Chrome headless, 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 will need to specify the Chrome binary with the setChromeBinaryPath() method.
Standard search locations:
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.
- The library creates Java temporary files that the Chrome headless server will need permission to access.
The files will be created in the Java system-dependent default temporary-file directory.
If required this directory can be specified by using the setLibraryTempFileDir() 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.
The ImageGenerator class provides methods to generate the required PNG/JPEG/WEBP/PDF images.
- 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.
- 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
Include the following method calls:
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();
You must have Chrome 71 or later installed on your system. The library requires a Chrome version that supports the DevTools protocol v1.3. We recommend that you install the most recent Chrome version.
Please refer to the Highcharts license page for further details.
CHROME HEADLESS VERSIONS
Chrome Versions 90 and Older
For Chrome versions 90 and older, the Chrome createTarget() method to create pages does not operate correctly. If you are experiencing startup errors and are using Chrome version 90 or older, use the Chrome class setChromeFix(“force-use-json-new;”) method to rectify this Chrome issue.
Chrome Versions 111 and Older
For Chrome versions 111 and older, there is only one version of Chrome headless available. The Chrome argument “–headless” will start Chrome in headless mode.
The HyJavaImages library v1.5.6 and older automatically adds the argument “–headless”.
Chrome Versions 112 and Newer
As of Chrome version 112, the Chrome development team have added a new Chrome headless. There are now “old” and “new” Chrome headless versions available.
The Chrome argument “–headless” will start Chrome in the “old” headless mode. Note: the Chrome development team may change this at any time.
The Chrome argument “–headless=old” will start Chrome in the “old” headless mode.
The Chrome argument “–headless=new” will start Chrome in the “new” headless mode.
For HyJavaImages library v1.6.0 or newer the default is to use the “old” Chrome headless. The library automatically adds the argument “–headless=old”. The default can be changed by using the ChromeArguments class setChromeHeadlessType() method.
The HyJavaImages library requires Java 8 or greater.
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.
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.