ChartDirector 7.0 (Java Edition)
Installation
ChartDirector for Java is a Java library for creating charts as vector and raster images and as PDF. It includes features to support user interactions for Java web applications.
ChartDirector for Java has two editions. One is with J2EE/Java EE support, and the other with Jakarta EE support. For web applications that runs on a J2EE/Java EE or Jakarta EE based web server, please use the edition that matches your web server. For non-web applications, either ChartDirector editions can be used.
What are J2EE/Java EE and Jakarta EE?
J2EE (Java 2 Platform, Enterprise Edition) is a set of specifications extending the Java SE (Java Standard Edition). They include the API for web programming. Most Java web servers comply to these specifications. This allows code written for J2EE to be usable on most Java web servers. Many package names in J2EE start with "javax". An example is "javax.servlet".
After Oracle acquired SUN Microsystems (the company that developed Java), it renamed newer versions of J2EE to Java EE. Java EE is backwards compatible with J2EE.
Oracle later submitted Java EE to the Eclipse Foundation, which is home to many open source projects. Due to trademark issues, the Eclipse Foundation cannot use the Java and javax names. As a result, newer versions of Java EE are renamed to Jakarta EE, and the "javax" packages are renamed to "jakarta". For example, "javax.servlet" becomes "jakarta.servlet".
Due to the different package names, J2EE/Java EE and Jakarta EE are incompatible. That is why there are two editions of ChartDirector for Java. They are identical except one uses J2EE/Java EE for web application support, while the other uses Jakarta EE.
ChartDirector for Java is distributed as a zip file, with a directory structure compatible with that of a Java Web Application Archive (WAR). This allows ChartDirector for Java to be directly installed to a Java web server as a web application.
Installing ChartDirector as a Java Web Application
If you are planning to use ChartDirector in a Java web server, you may consider to install ChartDirector as a Java web application. To do this, simply rename the ".zip" file extension to ".war" and use it as a WAR. Virtually all Java web servers support installing WAR. Please refer to your web server's documentation for details.
The advantages of installing ChartDirector as a web application are that the system will be set up automatically for running the sample code and testing ChartDirector. You can also easily uninstall ChartDirector by uninstalling the web application.
After installing ChartDirector as a Java web application, you can access the ChartDirector documentation and sample code using:
http://server_name/context_path
where "context_path" is the path of the servlet context that you use during installation.
Most web servers will automatically extract (or unzip) the WAR file during installation. However, some web servers, such as Tomcat configured with unpackWARs="false", may use the WAR file directly without extracting it. In this case, ChartDirector will work normally, but you will be unable to modify the sample code and experiment with ChartDirector.
If your web server does not automatically extract WAR files, you may unzip the WAR file to a directory first, and install the extracted directory to the web server. You may then modify the sample code and experiment with ChartDirector.
Installing ChartDirector in a Web Server Manually
If you do not want to automatically install ChartDirector using WAR, you can manually install the ChartDirector sample code by copying the necessary files.
- Extract the ChartDirector for Java distribution into an empty directory.
- Copy "WEB-INF/lib/ChartDirector.jar" (for J2EE/Java EE) or "WEB-INF/lib/ChartDirector_Jakarta.jar" (for Jakarta EE) to the "WEB-INF/lib" subdirectory of your web application.
- Copy the entire sample code directory "jspdemo" to your web application.
For some JSP web servers, you may need to restart the web application after modifying the "WEB-INF/lib" subdirectory.
You may then access the sample code using:
http://server_name/context_path/jspdemo/index.htm
Using ChartDirector in Your Own Web Application
To use ChartDirector in your own web application, you need to:
- Copy the ChartDirector Java library to your web application.
The ChartDirector Java library is in "WEB-INF/lib/ChartDirector.jar" (for J2EE/Java EE) or "WEB-INF/lib/ChartDirector_Jakarta.jar" (for Jakarta EE). Please copy it to the "WEB-INF/lib" subdirectory of your web application.
- (Optional) Map URL of the format "*.chart" to the ChartDirector.GetSessionImage servlet.
*** Note ***: The ChartDirector.GetSessionImage servlet is for compatibility with ChartDirector 6.x or earlier, in which the chart image is delivered to the browser using a separate HTTP connection like a normal image. ChartDirector 7.0 no longer uses this servlet.
This step is needed if you are writing servlet applications that do not use JSP. If you are using JSP, this step is usually not needed.
To set up the servlet mapping, please enter the following lines in the "web.xml" file of your web application.
<servlet>
<servlet-name>GetSessionImage</servlet-name>
<servlet-class>ChartDirector.GetSessionImage</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>GetSessionImage</servlet-name>
<url-pattern>*.chart</url-pattern>
</servlet-mapping>
If you are using a front-end web server to forward servlet requests to a back-end servlet container (eg. using an Apache web server to forward servlet requests to a Tomcat servlet container), please set up your web server so that it forwards "*.chart" to the servlet container, otherwise the servlet container will not see the "*.chart" requests.
Javadoc for IDE Integration
Currently, ChartDirector documentation is not in Javadoc format. Instead, it is in both CHM and HTML formats, with the HTML format being similar to the CHM format. The CHM format is preferred because it has integrated search facility, better indexing features, supports bookmarks, and is easier to print.
If you are currently reading the ChartDirector documentation in HTML format, and you are using a Microsoft Windows computer, you are recommended to download the CHM documentation from
http://www.advsofteng.com/download.html.
Some integrated development environments (IDE) can import "Javadoc" and use it to provide "intellisense" tool tips in the source code editor. To support these features, ChartDirector includes "Javadoc" in the "ide_javadoc" subdirectory. Note that the "Javadoc" does not contain any text for human reading. It just contains the ChartDirector API prototypes to allow the IDE to pop up prototypes with proper parameter names in "intellisense". For human reading, please use the CHM (recommended) or standard HTML documentation.
Installing the ChartDirector License
If you have purchased a license to use ChartDirector, you should have a license key delivered to your via email and postal mail. Please install the license key as according to the following instructions.
Even without a license key, ChartDirector will work normally, but the charts will include a yellow bar at the bottom that marks the charts as produced by the "unregistered" ChartDirector. You can freely test ChartDirector for as long as necessary.
If your license key is for upgrading from a previous version of ChartDirector, please append the upgrade license key to the previous version license key, and use the combined license key.
ChartDirector Developer License
Please follow the steps below to install the license key for the "ChartDirector Developer License":
- Create an ASCII file using Notepad or other text editor, and put the license key in it. The whole file should contain only the license key. Save the file as "chartdir.lic".
Note that some text editors, such as Notepad, may automatically append ".txt" to the filename. If file is saved as "chartdir.lic", it may end up as "chartdir.lic.txt". In this case, please rename the file back to "chartdir.lic".
- Copy the "chartdir.lic" to the windows directory (normally "c:\windows" on Windows) or the "/etc" directory (for Linux/macOS).
The above directory is a system directory and may require administrative privileges for write access. If you are copying using the command prompt, please make sure you use "Run As administrator" to start the command prompt (for Windows), or use "sudo" (for Linux/macOS).
- If you cannot copy to a system directory (eg. due to lack of administrative privilege), you can copy "chartdir.lic" to the Java class path visible to "ChartDirector.jar" (eg. "WEB-INF/classes" in a web application, or the root directory of a JAR archive).
The license file should remove the "unregistered" message on the charts. If the license file appears to have no effect, please refer to
http://www.advsofteng.com/license_diag.html for trouble-shooting instructions.
ChartDirector Redistribute License
The "ChartDirector Redistribute License" can be installed using the same method as that of the "ChartDirector Developer License". If your application is distributed as a compiled executable, you can compile the license key directly into the executable. This avoids redistributing the license file. To do this, simply add a line in your code to call
Chart.setLicenseCode and pass the license key as the argument.
Chart.setLicenseCode(".....your-license-key.....");
© 2022 Advanced Software Engineering Limited. All rights reserved.