The Entrance Java API

Overview

All Entrance applications support the 'plotql' script language for visualizing data in JDBC databases.   plotql is SQL with a single extension for drawing charts, called PLOT:

PLOT
  AXISLABELS, ORANGE LINE
  WITH
    GRIDLINES
SELECT
  year, avg FROM cpi_annual;

Scripts generate the same charts when run from EntranceServlet, desktop Entrance, or the Entrance command line utility.   This API makes it possible to embed them in other Java applications.   It also makes it possible to extend plotql with new functionality.

The Entrance Jars

To use the API you need entrance.jar and cotta.jar on the Java classpath. These jars are bundled with any of the Entrance desktop application downloads. When installed on Macintosh computers they will be buried in /Applications/Entrance.app/Contents/Resources/Java   On other platforms they will be in the directory where you unzipped the download.

There are some licensing issues to consider.   The first thing to know is that you can always use Entrance IDE jars for Java applications running on any desktop with a licensed copy of the Entrance IDE.

The Entrance jars are dual licensed: there are Community versions that are released subject to the GPL v. 2 license and IDE versions released subject to other licenses.   You should use the Community versions and comply with the GPL, if you plan to redistribute an application, unless you have obtained a license agreement from us for making copies of the IDE jar.  

The Cotta library, cotta.jar, is released subject to Apache License, Version 2.0 by the Cotta Project, http://cotta.sourceforge.net/.

If you have any questions, please get in touch by emailing support at dbentrance.com

com.dbentrance.charts.Chart

Chart is the base class for Entrance chart types.   Use createChartFromScript() to create a Chart using PLOT syntax
    import com.dbentrance.charts.Chart;
    ...
    Chart chart = Chart.createChartFromScript("plot axislabels, blue area"); 
LineChart is the default type and allows you to mix LINE, BAR, AREA, and SWATH series. You can specify other types too:
    Chart chart = Chart.createChartFromScript("plot xychart x, y"); 

Use setData() to hook the chart up to data, taking care to match up data columns 1-to-1 with PLOT series types:

    ResultSet rs = con.execute("select year, value from cpi;");
    chart.setData(r);
or
    Object[][] arr = new Object[][] {{"one", 1}, {"two", 2}, {"three", 3}};
    chart.setData(arr);
Finally, draw the chart:
    chart.draw(g);

Entrance charts also provide support for reverse mapping, panning and zooming, and color overrides. Notes in the source code for Chart provide details.   The desktop "painting" demos on YouTube, e.g. "Painting Scattered Data With Entrance and MySQL", hint at the possibilities.

Generating PNG files from plotql

An API class, EntrancePlot, provides methods for rendering plotql into images saved as PNG files. In each case, you must specify a JDBC connection to use for processing the script.

Specify the JDBC connection using url, user, and password using this method:

     exportPNG(String plotql, String pngPath,
         String url, String user, String pwd, int width, int height)
These take a JDBC connection as an argument:
     generatePNG(Connection con, String pngFile, String plotql)

     generateTempPNG(Connection con, String plotql) {

Building chart servlets

This is the pattern for making a servlet doGet() method that returns images:
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
             throws ServletException, IOException {

      BufferedImage image = ... make an image ...
      resp.setContentType("image/png");
      ImageIO.write(image, "png", resp.getOutputStream());
   } 
This uses the pattern to serve an Entrance chart "decorated" with a timestamp:
import java.util.Calendar;
import java.util.TimeZone;

  public class MyServlet extends HttpServlet {
    ...
    static Calendar cal = Calendar.getInstance(TimeZone.getTimeZone("pt"));
    ...

    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
             throws ServletException, IOException {

      // the Entrance chart
      Chart chart = Chart.createChartFromScript("plot axislabels, blue area"); 
      ResultSet rs = stmt.executeQuery("select year, avg from cpi;"); 
      chart.setData(rs);
      BufferedImage image = chart.saveToBufferedImage(false, -1, -1);

      // decorate it with the current time
      Graphics g = image.createGraphics();
      g.drawString(image.getWidth() - 200, image.getHeight() - 20,
            myCal.getTime())
      g.dispose();

      // send it
      resp.setContentType("image/png");
      ImageIO.write(image, "png", resp.getOutputStream());
   }

Customization

Extend Chart, or one of its subclasses, to visualize data a new way:
       package mypackage;

       import com.dbentrance.charts.LineChart;
     
       public class MyChart extends LineChart {
           public MyChart() {
           }

           public void draw(Graphics2D g) {
               // ... really great code ...
          }
       }

Build the new class into a jar named "entrancex.jar" and put it in an Entrance 'lib' directory. Now you can refer to the new type in plotql scripts using its class name:

       plot mypackage.MyChart blue line, datalabels

Take advantage of the fact that Entrance is open source and have a look at the classes in com.dbentrance.entrance.charts. You will see that certain patterns recur. The way HighLowChart extends LineChart is a good example for study.

Need Help?

The details about plotql and PLOT are online here. and in the Help menu of desktop Entrance versions. There is a Google Group for Entrance here

The dbEntrance Software site, http://dbentrance.com/ has links to documentation and videos that may be useful as well.

Zipped javadoc for the api is here.

These notes refer to the API provided with versions of Entrance 1.7.5 or later.

Copyright (c) 2010 dbEntrance Software, All Rights Reserved

Revised 2010.5.21