Integrate Java and GraphicsMagick – gm4java

Introduction

Now we added interactive or batch mode support to GraphicsMagick (GM hereafter), we need to enable the Java side of the integration to complete the implementation of the proposed solution. Hence the gm4java library is born.
In this post, we’ll briefly discuss how gm4java is implemented, then put more focus on its features and API.
Update (3/30): gm4java is available from central maven repository.

Implementation

The implementation of gm4java that we are going to discuss sounds to be complicated but the good news is you don’t have to deal with that because gm4java encapsulates the complexity and does the heavy lifting for you. If you are not interested in the detail, you can skip right to “Feature and API” section. But I believe having some understanding of what’s under the hood always makes me a better driver.
Source code of gm4java can be found at http://code.google.com/p/kennethxublogsource/source/browse/trunk/gm4java/ (update 4/15: moved to https://github.com/sharneng/gm4java)

Interacting with GM Process

gm4java uses Java ProcessBuilder to spawn GM process in interactive mode. Code below illustrate how the GM process is started

   1:  process = new ProcessBuilder().command(command).redirectErrorStream(true).start();

   2:  outputStream = process.getOutputStream();

   3:  inputStream = process.getInputStream();

Note that a pair of the input and output stream are obtained from the process. gm4java uses them to communicate with the GM process, by sending commands to, and receiving feedback from it.
gm4java uses below GM batch options to start GM batch process.

        gm batch -escape windows -feedback on -pass OK -fail NG -prompt off

• gm4java always use Windows style escape for the compatibility across the platforms
• prompt is turned off because it is just noise in the machine communication.
• feedback is turned on because that is how gm4java come to know
  • If GM had completed the execution of the command.
  • The result of the command, whether it was failed or succeeded.
• gm4java choose OK/NG for pass/fail feedback text, as it is unlikely that the output of any command will produce such text alone in one line.

You now understood that gm4java relies on the proper batch option to operate correctly. Hence, you should never use “set” command directly in gm4java.

GM Process Pooling

Using one single GM batch process in a highly concurrent environment is obviously not enough. Managing multiple GM batch processes is a difficulty task to say the least. gm4java solves this problem by maintaining a pool of GM batch processes for you. It internally uses Apache Commons Pool but hides the complex detail from you so you don’t need to know the Commons Pool in order to use gm4java’s GM process pooling service.

Code Quality

gm4java has nearly 100% code coverage excluding simple getter and setters.

Features and API

The API of gm4java was elaborately designed to be simply. The public interface is very well documented by Javadoc. I’ll cover the basics of the API but I refer you to the API documentation (javadoc) for further reading.
The use of gm4java is very much like using JDBC connection and connection pooling, which most of Java developers are very familiar with.
The primary interface of gm4java is GMConnection.

GMConnection Interface

Just like each JDBC Connection object represent a physical connection to database server, each GMConnection instance represent an interactive session with a GM process running in interactive mode until the connection is closed by invoking its close() method.

   1:  public interface GMConnection {

   2:      String execute(String command, String... arguments) throws GMException, GMServiceException;

   3:      String execute(List<String> command) throws GMException, GMServiceException;

   4:      void close() throws GMServiceException;

   5:  }

GMConnection has two overloaded execute methods, those are the methods you would use to execute GM commands. Each command passed to the execute methods is send to the interactive GM process for execution. The output of the command is then return as a String if it was executed successfully. Otherwise a GMException is thrown and the exception message contains the output of the GM command.
The two execute methods are essentially identical, having two of them is to give you the convenience of passing the command in one way or another.
In simply uses case, you can use varargs version for simplicity. e.g.

    String result = connection.execute("identify", "a.jpg");

But if you need to construct the command conditionally and dynamically, you’ll find the List version is more convenient.
You can use execute methods to run any GM command supported in interactive mode except “set” command. Currently gm4java doesn’t prevent you from doing it but the result is undetermined, mostly failure of all subsequent commands but can also hung. In future, gm4java will try to prevent you from being able to send “set” command.
You must call close() method after you are done with GMConnection, this is again similar to database connection, failure to do so can cause connection leaking. The close() method can effectively end the associated GM process, or just returns the GM process to the pool depends on the implementation of the GMConnection.
Below is the typical usage pattern to ensure connection is closed.

   1:  final GMConnection connection = ...

   2:  try {

   3:      // use connection to run one or many GM commands

   4:  } finally {

   5:      connection.close();

   6:  }

All three methods may throw GMServiceException. It doesn’t like GMException, which is only relevant to the specific GM command being executed, GMServiceException from these methods is usually a permanent condition. It indicates a communication error between gm4java and the interactive GM process, for example, you get this exception if the GM process crashed.
Lastly, please be warned that like JDBC Connection, GMConnection is NOT thread safe!
So far all sounds simple and easy, but GMConnection is an interface, where can we get a real instance of it? That’s is GMService.

GMService Interface

Continue the JDBC analog, GMService is like DataSource. GMService defines three methods, but the important one is the getConnection() method,

   1:  public interface GMService {

   2:      String execute(String command, String... arguments) throws GMException, GMServiceException;

   3:      String execute(List<String> command) throws GMException, GMServiceException;

   4:      GMConnection getConnection() throws GMServiceException;

   5:  }

The getConnection() method returns a GMConnection object associated to either a newly started GM interactive process, or one retrieved from a pool. Whether former or later depends on the actual implementations that we’ll cover in the following sections.
The two execute methods are convenient methods to execute one GM command. Both internally calls the getConnection() method to obtain a connection, execute the given GM command and immediately close the connection. Please see the Java API document for more detail on this.
All methods in GMService are guaranteed to be thread safe.
Although, GMService methods also throw GMServiceException, but it is not necessary, and usually is not, a permanent condition. This is because every time, it deals with a difference instance of GMConnection, hence a different GM process.
GMService is an interface, gm4java provides two concrete implementations of it.

SimpleGMService

SimpleGMService, telling by its name, is a simple implementation of GMService, Its getConnection method always starts a new GM interactive process and return an instance of GMConnection that is associated with that GM process. Closing of that GMConnection effectively stops the associated GM process. Because of this nature, applications use SimpleGMService to create GMConnection should make max use of the connection before closing it. Below is a typical usage pattern.

   1:  GMService service = new SimpleGMService();

   2:   

   3:  public void bar() {

   4:      GMConnection connection = service.getConnection();

   5:      try {

   6:          // use connection to run a lot of GM commands 

   7:      } finally {

   8:          connection.close();

   9:      }

  10:  }

The two execute methods in the SimpleGMService are provided for the purpose of completeness and should not be used in general. The implementation starts a new GM interactive process, run the given command and stop the GM process. That is actually slower than simply running the GM in the old single command mode.
SimpleGMService also has a property called gmPath. You’ll need to set this to full path of GM executable if it is not already in the command search path.

PooledGMService

PooledGMService is the real star in gm4java. Analog to a JDBC connection pool, PooledGMService is able to manage a pool of GM interactive process and distribute the GM commands across them. Hence it is capable of delivering high performance and scalability in a heavily concurrent environment.
Since it internally uses Apache Commons Pool, it can support all pooling features brought in by Commons Pool which is a highly configurable object pool implementation. PooledGMService must be constructed with an instance of GMConnectionPoolConfig object, which contains a list of properties to configure the pool.
The getConnection() method in PooledGMService returns an instance of GMConnection that is associated with a pooled GM interactive process. The close() methods of the returned GMConnection effectively returns the GM interactive process back to the pool for reuse.
For the applications that run many concurrent threads and each thread is just to run one GM command, the PooledGMService is especially helpful. Its two execute() methods become very useful now. Not only they simplify the code to be written, but also optimize internally to perform better. e.g., code below

   1:  final GMConnection connection = service.getConnection();

   2:  try {

   3:      return connection.execute(command, arguments);

   4:  } finally {

   5:      connection.close();

   6:  }

can be simplified to

    return service.execute(command, arguments);

and the later is more efficient.

im4java Integration

So far, gm4java gives a new way to communicating with GM process to get the work done efficiently. It requires you to know the GM command very well and pass each command and its parameters to the execute methods. For people who are not familiar with native GM commands, there can be a steep learning curve.
Thankfully, im4java did a great job of providing a Java friendly interface to construct the GM commands. So gm4java doesn’t need reinvent the wheel. We’ll let you use your familiar im4java interface to construct operations, then give it to gm4java to executed it efficiently.
GMBatchCommand is the bridge between im4java and gm4java. The usage of it is best illustrated by a few sample programs.
Execute a convert command

   1:  GMService service = ...;

   2:   

   3:  public void foo() {

   4:      GMBatchCommand command = new GMBatchCommand(service, "convert");

   5:   

   6:      // create the operation, add images and operators/options

   7:      IMOperation op = new IMOperation();

   8:      op.addImage("input.jpg");

   9:      op.resize(800, 600);

  10:      op.addImage("output.jpg");

  11:   

  12:      // execute the operation

  13:      command.run(op);

  14:  }

Execute the identify command

   1:  GMService service = ...;

   2:   

   3:  public List<String> foo() {

   4:      GMBatchCommand command = new GMBatchCommand(service, "identify");

   5:   

   6:      IMOperation op = new IMOperation();

   7:      op.ping();

   8:      final String format = "%m\n%W\n%H\n%g\n%z";

   9:      op.format(format);

  10:      op.addImage();

  11:      ArrayListOutputConsumer output = new ArrayListOutputConsumer();

  12:      command.setOutputConsumer(output);

  13:   

  14:      command.run(op, SOURCE_IMAGE);

  15:   

  16:      ArrayList<String> cmdOutput = output.getOutput();

  17:      return cmdOutput;

  18:  }

Please note that there are limitations of GMBatchCommand, at this time it doesn’t support im4java asynchronous mode and doesn’t support BufferedImage as output.
We do recognize the integration between im4java and gm4java is still weak. But we also believe there exists strong synergy between im4java and gm4java. Together, we can provide next level of integration between Java and GM.

Future

In next post of this series, I’ll present the new test result of the same web application that we have tested before. This time it uses gm4java.

Other Posts in the “Integrate Java and GraphicsMagick” Series

1. Conception
2. im4java Performance
3. Interactive or Batch Mode
4. gm4java
5. gm4java Performance