A White Blood Cell Capturing a Bacterium

Java Web Apps - Integrating Charts into a Servlet

Adding a chart to a Java web application is really easy to do - thanks to the open source Java charting API XChart. XChart's charting library lets you very easily make charts an integrate them into all your Java-based applications. In this blog post, I am going to demonstrate how to add charts to a Java web application. If you want to integrate XChart charts in your Java applications, download the JAR here. You can also see more XChart exmaples here.

The Basic Idea

The basic idea for adding XChart charts to a web app is as follows. First, you have a JSP or HTML page with a link on it that will request a new page with a chart. The new JSP or HTML page that is generated has an img tag in it with a reference to an in-memory chart stored in a HashMap in a Servlet that maps the reference and the chart. When the page reloads, the browser parses the img tag and subsequently requests the image from the Servlet. The Servlet then streams the chart to the browser and it is rendered on the page.

An Example

If the basic idea explanation above did not make complete sense, the following example should make it clear.

Step 1: ChartServlet. This Servlet does one of two things in the doGet() method, depending on the request. If it receives and 'action', it generates a chart. Here you could pass in different 'action' parameters to create different charts if you want. If it receives a 'chart_id', it pulls the chart from CHART_MAP and streams it out to the browser.

import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;

import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.xeiam.xcharts.BitmapEncoder;
import com.xeiam.xcharts.Chart;
import com.xeiam.xcharts.QuickChart;

@javax.servlet.annotation.WebServlet(name = "ChartServlet", urlPatterns = { "/chart" })
public class ChartServlet extends HttpServlet {

    private static Map<String, Chart> CHART_MAP = new HashMap<String, Chart>();

    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

        // generate the Chart
        String action = request.getParameter("action");
        if (action != null && !action.equals("null")) {
            String chartId = generateRandomChart();
            request.setAttribute("chart_id", chartId);
            request.getRequestDispatcher("/chart.jsp").forward(request, response);
        }

        // Fetch the Chart
        String chartId = request.getParameter("chart_id");
        if (chartId != null && !chartId.equals("null")) {

            Chart chart = CHART_MAP.get(chartId);
            if (chart != null) {
                response.setContentType("image/png");
                ServletOutputStream out = response.getOutputStream();
                try {
                    BitmapEncoder.streamPNG(out, chart);
                } catch (Exception e) {
                    e.printStackTrace();
                }
                out.close();
                chart = null;
                CHART_MAP.remove(chartId);
            } else {
                System.err.println("CHART NOT FOUND!!!");
            }
        }
    }

    // generate the chart
    public static String generateRandomChart() {
        Chart chart = QuickChart.getChart("XChart Sample - Random Walk", "X", "Y", null, null, getRandomWalk(105));
        String uuid = UUID.randomUUID().toString();
        CHART_MAP.put(uuid, chart);
        return uuid;
    }

    // generate random walk data set
    private static double[] getRandomWalk(int numPoints) {
        double[] y = new double[numPoints];
        y[0] = 0;
        for (int i = 1; i < y.length; i++) {
            y[i] = y[i - 1] + Math.random() - .5;
        }
        return y;
    }
}

Step 2: Chart JSP. To request and display the Chart, the JSP contains two DIVs - one for a link to request the chart and one for a IMG tag to display the Chart image. I named this JSP chart.jsp.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head>
     <meta http-equiv="content-type" content="text/html;charset=utf-8" />
     <% String chartId = (String) request.getAttribute("chart_id");%>
 </head>
    <body>
     <div>
      <a href="<%=request.getContextPath()%>/chart?action=whatever">Generate Chart</a>
     </div>
     <%if(chartId != null){ %>
     <div>
      <img src="<%=request.getContextPath()%>/chart?chart_id=<%=chartId %>"/> 
     </div>
  <%} %>
    </body>
</html>

Step 3: Test it. Now deploy your webapp with the new Servlet and JSP and in your browser go to: http://localhost/YourWebAppContext/chart.jsp

After clicking on 'Generate Chart' your chart will appear on the web page. Each time you click it, a new chart will show up.

Piece of Cake!!!

See also: Java XChart Library Now Supports Error Bars

Using Yank as a MySQL Persistence Layer in Your Java Application

Yank is a lightweight JDBC persistence layer API for any type of Java application. Looking at the JavaDocs, we can see that it only has a grand total of 4 classes. I love APIs like this because I can dig into the JavaDocs and very quickly understand the design and structure, making it a snap to get up and running with working code. Yank makes it easy to interact with JDBC databases in a structured, organized, and clean-cut approach. If you don't use a persistence layer like this, you quickly find that your database querying code becomes an unmanageable mess.

The Basic Idea

Each table in your database has a corresponding Java object. The object has private fields with names and data types that match the column names of your table. In other words, the Bean is a Java object that is a one-to-one mapping of a single row in your table.

The next thing you need is a Data Access Object, or DAO, for the Bean. In this class, you create methods for interacting with the table. In each method, with only a few lines of code, you create the specific SQL query you want and use the com.xeiam.yank.DBProxy to handle the query for you.

The advantage of this is that your code for interacting with the database is all wrapped up in just two very simple classes for each table in your database - a POJO and a DAO. And because the actual nitty-gritty details of handling database connections and results sets in handled for you in com.xeiam.yank.DBProxy, you don't have to worry about coding that yourself. It saves time and prevents errors.

An Example

In order to make the relationship between a table, the Bean, and the DAO absolutely clear, I will walk through an example.

Step 0: Create a Database. We'll call the database "Yank", which matches the jdbc URL in step 4 exactly. How you create the database may be different than how I do it, but here's what I did at the command line:

$ /usr/local/mysql/bin/mysql -u root -p
mysql$ create database Yank;
mysql$ show databases;
mysql$ exit;

Step 1: Create a table. I'll be using similar code to the Yank example code for this. In MySQL create a database called 'Yank' and add the following table called 'Books' to it:

CREATE TABLE `Books` (
`TITLE` varchar(42) DEFAULT NULL,
`AUTHOR` varchar(42) DEFAULT NULL,
`PRICE` double DEFAULT NULL
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Step 2: Create a Bean for the table. First, add the fields corresponding to the column names. The names MUST match, although case doesn't matter. Finally add getters and setters for all the fields. In Eclipse, these can be easily auto generated.

package com.xeiam.yank.demo;

/**
 * A class used to represent rows in the BOOKS table 

 * Note: class member naming tip: data type and name must match SQL table!

 * Note: DBUtils uses reflection to match column names to class member names. 

 * Class members are matched to columns based on several factors:
 * 
 * 
set* methods that match the table's cloumn names (i.e. title <--> setTitle()). The name comparison is case insensitive.
 * 
The columns are matched to the object's class members
 * 
If the conversion fails (i.e. the property was an int and the column was a Timestamp) an SQLException is thrown.
 * 
 * 
 * @author timmolter
 */
public class Book {

  private String title;
  private String author;
  private double price;

  /** Pro-tip: In Eclipse, generate all getters and setters after defining class fields: Right-click --> Source --> Generate Getters and Setters... */

  public String getTitle() {

    return title;
  }

  public void setTitle(String title) {

    this.title = title;
  }

  public String getAuthor() {

    return author;
  }

  public void setAuthor(String author) {

    this.author = author;
  }

  public double getPrice() {

    return price;
  }

  public void setPrice(double price) {

    this.price = price;
  }

  /** Pro-tip: In Eclipse, generate a toString() method for a class: Right-click --> Source --> Generate toString()... */

  @Override
  public String toString() {

    return "Book [title=" + title + ", author=" + author + ", price=" + price + "]";
  }

}

Step 3: Create a DAO class. I'll add two methods to it - one for inserting a Book and one for selecting all the books in the table.

package com.xeiam.yank.demo;

import java.util.List;

import com.xeiam.yank.DBProxy;

/**
 * DAO (Data Access Object) Class for BOOKS table. 

 * This is where you create your own methods for SQL interaction with a database table.

 * Each table in your database should have it's own DAO Class.

 * 
 * @author timmolter
 */
public class BooksDAO {

  public static int insertBook(Book book) {

    Object[] params = new Object[] { book.getTitle(), book.getAuthor(), book.getPrice() };
    String SQL = "INSERT INTO BOOKS  (TITLE, AUTHOR, PRICE) VALUES (?, ?, ?)";
    return DBProxy.executeSQL("myconnectionpoolname", SQL, params);
  }

  public static List selectAllBooks() {

    String SQL = "SELECT * FROM BOOKS";
    return DBProxy.queryObjectListSQL("myconnectionpoolname", SQL, Book.class, null);
  }
}

Step 4: Use your new persistence layer in your code. For demonstration purposes, I'll create a simple class that calls the two methods in the DAO and prints out the results. In this class, first define the connection properties. The Yank API needs to know how to connect to your database: which JDBC driver, which table, which user, and the password, and how many Connections in the connection pool. For the last four properties, the word 'local' corresponds to the name of the connection pool. Notice in the DAO class that the DBProxy method calls are passed 'local' as the first parameter. This feature allows you to have multiple Connection pools in your application if you want.

import com.xeiam.yank.DBConnectionManager;

public class BooksExample {

    public static void main(String[] args) {

        Properties props = new Properties();
        props.setProperty("driverclassname", "com.mysql.jdbc.Driver");
        props.setProperty("local.url", "jdbc:mysql://localhost:3306/Yank");
        props.setProperty("local.user", "root");
        props.setProperty("local.password", "");
        props.setProperty("local.maxconn", "5");

        DBConnectionManager.INSTANCE.init(props);

        // Insert Book
        Book book = new Book();
        book.setTitle("Cryptonomicon");
        book.setAuthor("Neal Stephenson");
        book.setPrice(23.99);
        BooksDAO.insertBook(book);

        // Select All Books
        List allBooks = BooksDAO.selectAllBooks();
        for (Book book1 : allBooks) {
            System.out.println(book1.toString());
        }

        DBConnectionManager.INSTANCE.release();
    }
}

Here's the output:

Book [title=Cryptonomicon, author=Neal Stephenson, price=23.99]

Piece of Cake!!!

Additional Information

As you can see, it is really easy to use Yank to push and pull data into and out of a database from your Java application. On the Yank example page, you can see a few more advanced capabilities as well. You can set up your database connection information in a properties file rather than directly in your Java code if you want. You can also keep all you SQL statements in a single properties file and access them using the DBProxy.*SQLKey() methods. In addition to the insert and select statements shown above, you can query in anyway you want: update, insert ignore, replace, batch query, etc.

Yank has 3 dependencies, so in order to integrate Yank into your application you'll need not only the Yank jar on your classpath, but also these:
Apache Commons DBUtils
Simple Logging Facade for Java (SLF4J)
MySQL Connector/J

And remember, this will work with any type of database that has a JDBC driver, such as PostgreSQL. You would just have to add the appropriate JDBC driver to your classpath, and modify the connection properties appropriately.

Pull Entire Directory Using SCP on a Mac

The following command can be used to fetch an entire directory including all the files from a remote host to a local directory.

$ scp -r username@host:/fully/qualified/path/on/remote/host/ /fully/qualified/path/on/local/host/

An alternative approach is to reference a directory relative to the user's account.

$ scp -r username@host:user's/path/on/remote/host/ user's/path/on/local/host/

Or using '.', the files will be copied to the current working direcory

$ scp -r username@host:user's/path/on/remote/host/ .

To use a wildcard to fetch only certain file types use the * syntax.

$ scp -r username@host:user's/path/on/remote/host/*.png .

Piece of Cake!!!

Executing a Shell Script from Java

Using MySQL and Java? Check out an easier way: Yank

Today I figured out how to run a bash script from Java for the first time, and I wanted to jot down the essential steps needed to get it all working along with some things to watch out for. This is specific to mysqldump, but it should work for any script you have and want to run in the bash shell. This also demonstrates how to pass in an argument to the script.

Step 1: The first order of business in running a shell script from within a Java program is to setup a function that you can pass shell commands to. The following method takes a command as an argument and runs it in a bash shell. I put this method in a class called ExecUtils.

public static void execShellCmd(String cmd) {
        try {
            Runtime runtime = Runtime.getRuntime();
            Process process = runtime.exec(new String[] { "/bin/bash", "-c", cmd });
            int exitValue = process.waitFor();
            System.out.println("exit value: " + exitValue);
            BufferedReader buf = new BufferedReader(new InputStreamReader(process.getInputStream()));
            String line = "";
            while ((line = buf.readLine()) != null) {
                System.out.println("exec response: " + line);
            }
        } catch (Exception e) {
            System.out.println(e);
        }
    }

Step 2: Creating the script is pretty straight forward, but there are a few things to watch out for. For a bash script, you need #!/bin/bash on the first line. To pass an argument into the script, I used FILENAME=$1 and later used $FILENAME in my command. $1 represents the first argument. I also exit the script with the value returned from the mysqldump command.

#!/bin/bash
FILENAME=$1
exit mysqldump --user=username --password=pass --databases DB_XYZ | gzip -9 > temp/dump/$FILENAME

For this example, I placed my file, dump.sh in the directory '/temp'. One more thing to check is that your script is executable. Run this command in the terminal to make it executable:

sudo chmod 777 /temp/dump.sh

Step 3: Now just run the script through the execShellCmd method.

package mysql;

import java.util.Date;

import com.xeiam.utils.ExecUtils;

/**
 * This class demonstrates running a shell script from within Java
 */
public class MySQLDumpScript {

    public static void main(String[] args) {

        String fileName = "DUMPFILE.sql.gz";
        String shellCommand = "/temp/dump.sh " + fileName;
        ExecUtils.execShellCmd(shellCommand);
    }
}

You should now see a file called DUMPFILE.sql.gz in /temp/dump. Piece of Cake!!!

Executing mysqldump from Java and Pitfalls to Avoid

Using MySQL and Java? Check out an easier way: Yank

I just spent a lot of time figuring out how to run mysqldump from within my Java program. I came across several different problems. Each time it was not working, there was a different problem and solution, and never really easy to debug. Sometimes it would just not work at all. Sometimes it would create an empty file. In this blog, I document how I finally got it all to work and which pitfalls I fell into along the way.

Step 1: The first order of business in running mysqldump from within a Java program is to setup a function that you can pass shell commands to. The following method takes a command as an argument and runs it in a bash shell. I put this method in a class called ExecUtils.

public static void execShellCmd(String cmd) {
        try {
            Runtime runtime = Runtime.getRuntime();
            Process process = runtime.exec(new String[] { "/bin/bash", "-c", cmd });
            int exitValue = process.waitFor();
            System.out.println("exit value: " + exitValue);
            BufferedReader buf = new BufferedReader(new InputStreamReader(process.getInputStream()));
            String line = "";
            while ((line = buf.readLine()) != null) {
                System.out.println("exec response: " + line);
            }
        } catch (Exception e) {
            System.out.println(e);
        }
    }

Step 2: Now we just need to run the proper mysqldump command through our execShellCmd method. The following shellCommand String will backup the database DB_XYZ and write it to a file called /test.sql.gz.

private void mysqldump() {

        String shellCommand = "mysqldump --user=username --password=pass --databases DB_XYZ | gzip -9 > " + "/test.sql.gz";
        ExecUtils.execShellCmd(shellCommand);

    }

Pitfall 1: LOCK TABLES user permission. In order for the mysqldump command to work, the user which you define using the --user argument must have the LOCK TABLES permission. If that user does not have that privilege, you can add it with the following commands in MYSQL:

GRANT lock tables ON DB_XYZ.* TO 'username'@'localhost' IDENTIFIED BY 'pass';
GRANT lock tables ON DB_XYZ.* TO 'username'@'%' IDENTIFIED BY 'pass';
flush privileges;

Pitfall 2: False file permissions. In order for the /test.sql.gz to be written to disk, the user in which the Java program is running must have permission to write a file there. In this case: '/'.

Pitfall 3: mysqldump cannot be found on system PATH. In the command above I used the unqualified 'mysqldump' as the command to execute. You could just as easily replace 'mysqldump' with the fully qualified version: '/usr/local/mysq/bin/mysqldump', as in my case on my local machine. One possible problem with this approach though is that your Java code doesn't become portable to other platforms. For example, on one of my Linux machines, mysqldump is found here: '/usr/bin/mysqldump'. To be able to use just 'mysqldump' you have to make sure it is on the system PATH. This is how you do that...

On my Linux machine:

$ locate mysqldump
/usr/bin/mysqldump

OK, using the command 'locate' I determined that 'mysqldump' is located in the directory '/usr/bin'. Now let's check if '/usr/bin' is on PATH:

$ echo $PATH
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games

Yes, it is. No problem using 'mysqldump' directly.

On my Mac machine:

$ locate mysqldump
/usr/local/mysql/bin/mysqldump

OK, using the command 'locate' I determined that 'mysqldump' is located in the directory '/usr/local/mysql/bin'. Now let's check if '/usr/local/mysql/bin' is on PATH:

$ echo $PATH
/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin:/usr/local/git/bin

Nope. Now we need to add /usr/local/mysql/bin to PATH on Mac OS X (10.5 Leopard). Here's how I did that. I created a file in /etc/paths.d called mysqldump

$ sudo vim /etc/paths.d/mysqldump

and added the following text:

/usr/local/mysql/bin

and restarted my computer.

Now let's check again if '/usr/local/mysql/bin' is on PATH:

$ echo $PATH
/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin:/usr/local/git/bin:/usr/local/mysql/bin

Yup, all good!

Jewel Wasps

Intel's Tri-Gate Process for Their Future Transistors

A Random Tomcat Error

Want to integrate charts into your webapp? Check out XChart.

Here's another nano-blog that will hopefully help someone solve a Tomcat error that I was dealing with today:

java.lang.NoSuchMethodException: org.apache.catalina.deploy.WebXml addServlet

The problem was that I was deploying catalina.jar within my .war file. Once I fixed up my build file to not include the catalina.jar file in the .war file, the error went away.

Java One-Jar Example Using Ant and Eclipse

One-Jar is an amazingly clever and simple tool that let's you package an entire Java application containing external jar files all into one Jar. But just like anything, it's simple and easy to use only AFTER you figure out how to get it working. Having just worked through using One-jar, I thought I'd lay out the steps needed to successfully use One-jar in Eclipse using Ant.

Step 1: Get One-jar. Go to the One-jar download page on Source-Forge and download the "one-jar-ant-task-0.97.jar" file.

Step 2: Integrate this jar into Eclipse so that when running Ant, Ant has access to the one-jar Ant Task. If you don't do this, you may get and error like:

/eclipse/helloworkspace/HelloOneJar/build.xml:54: Problem: failed to create task or type one-jar
Cause: The name is undefined.
Action: Check the spelling.
Action: Check that any custom tasks/types have been declared.
Action: Check that any / declarations have taken place.

Move the jar to your Eclipse plugins folder. For me, that was in /eclipse/plugins. You can really put this anywhere you want, but it made sense for me to put it here as Eclipse stores a lot of jars it needs here.

In Eclipse, open preferences, drill down to Ant-->Runtime, highlight Ant Home Entries, and click "Add external JARs...". Find the one-jar JAR, and add it here.

Step 3: Create Ant build file. For demonstration and testing purposes, I created a tiny Java Project called HelloOneJar which contains a Hello class. All the Hello class does is log two messages using log4j. Here is a screenshot of the project structure and the Hello class:

build.properties

project.name=hello-onejar
lib.dir=lib
src.dir=src
build.dir=build
dist.dir=dist

build.xml

<?xml version="1.0"?>
<project name="hello-onejar" default="onejar" basedir=".">
 
    <taskdef name="one-jar" classname="com.simontuffs.onejar.ant.OneJarTask" onerror="report" />
 
    <property file="build.properties"/>
 
    <tstamp>
       <format property="timestamp" pattern="yyyy-MM-dd HH:mm:ss" />
    </tstamp>
 
    <path id="classpath">
     <fileset dir="${lib.dir}" />
    </path>

    <target name="clean">
        <echo>Cleaning the ${build.dir}</echo>
        <delete dir="${build.dir}"/>
        <delete dir="${dist.dir}"/>
    </target>

    <target name="init" depends="clean">
        <echo>Creating the build directory</echo>
        <mkdir dir="${build.dir}"/>
        <mkdir dir="${dist.dir}"/>
    </target>
 
    <target name="compile" depends="init">
        <echo>Compile the source files</echo>
        <javac srcdir="${src.dir}" destdir="${build.dir}" debug="on">
            <classpath refid="classpath"/>
        </javac>
    </target>

 <target name="mainjar" depends="compile">
       <jar jarfile="${dist.dir}/main.jar">
         <manifest>
            <attribute name="Built-By" value="${user.name}"/>
             <attribute name="Build-Date" value="${timestamp}"/>                 
             <attribute name="Main-Class" value="com.hello.Hello"/> 
           </manifest>
          <fileset dir="${build.dir}">
              <include name="**/*.class"/>
          </fileset>
        </jar>
 </target>

    <target name="onejar" depends="mainjar">
     
        <!-- Construct the One-JAR file -->   
  <one-jar destfile="${dist.dir}/${project.name}.jar">
         <main jar="${dist.dir}/main.jar">
         </main>
         <lib>
             <fileset dir="${lib.dir}" />
         </lib>
  </one-jar>
    </target>
 
</project>

The follwing parts are very important!

<taskdef name="one-jar" classname="com.simontuffs.onejar.ant.OneJarTask" onerror="report" />
without that line, the one-jar task is undefined. Remember to tell Ant where this class is in step 2!

<attribute name="Main-Class" value="com.hello.Hello"/>
without this in the manifest you may get an error like this when you run your jar:

Exception in thread "main" java.lang.Exception: hello-onejar.jar main class was not found (fix: add main/main.jar with a Main-Class manifest attribute, or specify -Done-jar.main.class=), or use One-Jar-Main-Class in the manifest
at com.simontuffs.onejar.Boot.run(Boot.java:327)
at com.simontuffs.onejar.Boot.main(Boot.java:168)

Step 4: Run the Ant build. In this example, I run the "onejar" task that I defined. This build file first creates a jar called main.jar that contains my application code. This jar has it's own manifest and could be ran separately. The onejar target wraps main.jar in hello-one-jar.jar and packages all the jar(s) in the lib folder inside. Both jars are created in the ./dist folder.

Step 5: Inspect the built jar. This is how I did this on my Mac. First I created a folder: /HelloOneJar and moved the hello-onejar.jar into it. Then, in terminal:

cd /HelloOneJar
jar -xvf hello-onejar.jar

Now the jar is unpacked and we can see what's in it. You can do the same for main.jar and verify that the manifest file was created correctly.

Step 6: Run the jar and make sure it all works. This is how I did this on my Mac. First I created a folder: /HelloOneJar and moved the hello-onejar.jar into it. Then, in terminal:

cd /HelloOneJar/
java -jar hello-onejar.jar

The following output appeared in Terminal:

0 [main] INFO com.hello.Hello - Hello.
1 [main] INFO com.hello.Hello - Bye Bye.

Exactly what I expected!

Piece of Cake!!