/var/adm/blog

gearman-java 0.01 released

Today we released the 0.01 version of the gearman-java project ... woo hoo!

== WHAT IS THE GEARMAN-JAVA PROJECT ==

The purpose of the gearman-java project is to provide a pure Java based Gearman implementation that can be easily used by Java applications to define and submit gearman jobs as well as allow for Java based workers to interact with a Gearman System. The Gearman Java project will provide a 'pure java' implementation for the Gearman Client and Gearman Worker but does not include an implementation

of the Gearman Job Server.

While the gearman-java library provides Java implementations of the Gearman Worker and Client abstractions, there is no requirement that a Java Client use a Java Worker (or vice versa). The Workers and Clients make no assumption about their counter-parts and it is legitimate for a Java client to execute a C based Worker or for a perl client to execute a Java worker. One of the advantages of the Gearman framework is that the implementation details are irrelevant.

As you can see from the 0.01 version number, this is the first release of the project, and as such, you can expect that there will be bugs and I would expect that the API will most likely go through some revisions, and there certainly will be a lot of improvements coming in the near future, so you probably should not hook it up immediately to your production system.

But we would really like to encourage people to play with it and to give us feedback on how this implementation does or does not meet your needs. If you like it, great, let us know what works for you. If you don't like it, well, believe it or not, that's great too, as long as you can tell us what you don't like about it. We don't get offended easily and will use your feedback to make the system better. If you find a bug, let us know, we'll fix it. Bonus points if you can provide us with a test case. Double bonus points if you can provide us with a test case and a fix.

== WHERE CAN I GET IT ==

You can download the jar/source/javadocs from the URL below:

https://launchpad.net/gearman-java/trunk/0.01

== REQUIREMENTS ==

• JDK5 or higher.
• A Gearman Job Server. The gearman-java Library has been tested using the 0.8 C based gearmand Gearman Job Server, but in theory should work with any server that understands the Gearman Protocol.
• If you plan on building the project, as opposed to just using the pre-built jar, you will need ant on your path. The build has been tested with ant 1.7 but probably works with earlier versions.
• To execute the regression tests in the source tree, Junit 4.6 will need to be available on your system.

== KNOWN ISSUES==

• Performance. Performance is significantly slower than the C library. We will be addressing this soon.
• Memory leak in GearmanClientImpl.  When submitting an attached job, if you do not call selectUpdateJobsEvents() method on a semi-regular basis, the client will leak memory. To work around this, call selectUpdateJobEvents() after a job is reported as done.
• Client and Worker will not attempt to re-establish connection to server if the connection drops.

== EXAMPLES ==

There are some examples that ship with the source tar ball, located in src/org/gearman/examples, which provide some real world examples on how to use the gearman-java library. Below are some quick snippets for those of you too lazy to go look.

Gearman Worker Implementation

The easiest way to create a worker is to create a class that extends org.gearman.worker.AbstractGearmanFunction and to implement the

executeFunction(). Below is a class that simply reverses a String.

 public class ReverseFunction extends AbstractGearmanFunction {
    public GearmanJobResult executeFunction() throws Exception {
        StringBuffer sb = null;
        byte [] warnings = new byte[0];
        byte [] exceptions = new byte[0];
        int numerator = 0;
        int denominator = 0;
        sb = new StringBuffer(ByteUtils.fromUTF8Bytes((byte[]) this.data));
        GearmanJobResult gjr = new GearmanJobResultImpl(this.jobHandle,
                true, sb.reverse().toString().getBytes(),
                warnings, exceptions, numerator, denominator);
        return gjr;
    }
}

Gearman Worker Registration

The easiest way to instantiate a worker and have it registered with a Gearman Job Server is to use the example WorkerRunner, also found in org.gearman.example

The example below will load the reverseFunction for execution and then register it with a GearmanJobServer running on the localhost using the default port. The example assumes that the class org.gearman.examples.ReverseFunction exists and is on the class path.

Gearman Job Submission

The snippet below demonstrates how to create a job, submit it for execution, and to then retrieve its results.

        
GearmanJobServerConnection conn = new GearmanNIOJobServerConnection("localhost");
String function = ReverseFunction.class.getCanonicalName();
String uniqueId = null;//an id to identify the job, null is OK for now.
byte[] data = ByteUtils.toUTF8Bytes("How now brown cow");
GearmanJob job = GearmanJobImpl.createJob(function, data, uniqueId);

client = new GearmanClientImpl();
client.addJobServer(conn);

client.submit(job);

GearmanJobResult res = job.get();
       
return ByteUtils.fromUTF8Bytes(res.getResults());

== HOW DO I CONTRIBUTE ==

The top 10 ways you can contribute are listed below in RDL (Reverse David Letterman) order.

1) Use it! This is an early release and we are itchin' at the bit to get some feedback on what works and what doesn't.

2) File a bug. We can't fix it if we don't know about it.

3) Submit a test case. A product is only as good as its' test suite. Want a bug fixed? We'll get to it that much quicker if we don't have to figure out how to reproduce it.

4) Improve a test case. You see a bad test case or find one that does not adequately cover a feature, well, make it better.

5) Submit a feature request. You have an idea for how we can do things better, tell us.

6) Implement a feature. Take a look at the project blueprints, find something that looks fun to you, sign up for it and do it.

7) Help us document. If you see some documentation that is unclear,wrong, or missing, we hereby grant you the power to fix it.

8) Write a worker.

9) Blog about the gearman-java library. Blogging ... its' your ticket to stardom.

10) Become a member. Subscribe to the Gearman Discussion list and actively participate.

== FEEDBACK ==

If you have any feedback that you want to give, you can use any of the following

== CONTRIBUTORS ==

The following individuals contributed to this release:

• Robert Stewart
• Eric Herman
• Trond Norbye
• Eric Day
• Eric Lambert

Posted at 04:31PM Jul 16, 2009 by Eric Lambert in Gearman  |  Comments[0]