Practical API Design

Posted by F 31/08/2008 at 18h14

I wrote about API design guidelines before, collecting links, resources, papers and hoping someone would write a book on the subject.

The wait is over! Jaroslav Toulash published a book on Practical API Design!

Take a look at the book’s accompanying website for more details.

I’m waiting for my copy.

Violating Java's privacy 3

Posted by F 19/02/2007 at 22h49

I found myself in the need to invoke a private method of a Java class that was out of my control. I really needed it.

So, I went ahead and violated the method’s privacy declaration via reflection. You can (under certain circumstances) invoke methods which are declared as private using the Reflection APIs (java.lang.reflect).

But before using reflection, I created two classes:

class A {
  public String method1() {
    return "Hello World!";

class B {
  public static void main(String[] args) {
    A a = new A();

They compiled, and java B said “Hello World!” as expected.

Then, I made A’s method private and recompiled A. And I run java B again. Nothing changed. It just worked again.

That cannot be right. This would mean you can handcraft a class with the same name and methods as the original one but making everything public. Then you could use this class only at compilation time, allowing your code to call any method. (Or, one could modify the Java compiler to ignore access declarations altogether).

On API Design Guidelines 7

Posted by F 19/11/2006 at 22h31

Update: Good news! Jaroslav Toulash emailed me that he published a book on Practical API Design !!!

Looks like Brian McAllister may be preparing a talk on Designing Elegant APIs.

I've been very interested in good API design for a long time. But I could never find a single book on the subject. Many design and programming books provide good advice and guidelines that are essential for designing good APIs, but none of them tackles the matter directly.

I reviewed "Interface Oriented Programming" a few months back with disappointment. It may not be a bad book, but I felt it was quite basic and superficial. May be my expectations were too high, and too focused on API design.

Over time, I collected some links on the subject and shared some with Brian:

So, let's hope Brian gives his talk at a big conference, signs a contract with a big publisher and fills the void.

AntDoclet 1.1

Posted by F 22/07/2006 at 16h43

I just released a new version of AntDoclet.

No major changes. Now the comments of inherited methods are properly extracted from the parent class comments.

Thanks to Daniel Lindner for this fix.


Posted by F 12/04/2006 at 22h16

Did you know about

It provides as-you-type lookups of reference documentation for HTML, CSS, Java, Perl and other programming languages and APIs.


Posted by F 26/12/2005 at 22h19

After nearly two years of procrastination, I finally decided to spend some time on wrapping things up and putting AntDoclet online for public consumption.

AntDoclet is a little tool for documenting Ant Tasks. It automatically generates HTML and LaTeX documentation from the source code of your Tasks.

I wrote it initially in January 2004, for documenting the Ant tasks provided with the FuegoBPM product. Recently, I needed to improve it a bit, and decided to make it public.

Thanks to Fuego Inc. –my employer– who allowed me to release AntDoclet.

Graphical Thread Dumps 10

Posted by F 24/11/2005 at 23h00

I am surprised by the high number of Java developers I meet that do not know what a Java Thread Dump is or how to generate one. I find it a very powerful tool, and it is always available as part of the JVM. I haven’t played much with Java 5 yet, but it comes with jstack, a new tool that makes it easier to generate thread dumps.

Earlier this year, I was working on a load test for for a well-known airline. We were tunning the environment all we could, monitoring and profiling to know where to focus our optimization efforts. The solution involved a fairly high stack: Apache httpd, WebSphere, FuegoBPM, Tibco messaging, Oracle RAC.

The system was holding load pretty well up to a certain point in which it immediatly halted and stopped processing new requests. Every time we run the load testing scripts we experienced the same symptoms. Not even the official testers –with allegedly powerful testing and monitoring tools– were able to identify the cause of the problem.

So, I decided to get a few Thread Dumps of WebSphere’s JVM. On Unix, you do ”kill -3 <pid>” and the dump goes to WebSphere’s native_stdout.log. We inspected the dumps but couldn’t identify dead-locks or any other obvious anomaly, although the answer was right before our eyes.

Micro and Blind Optimizations 1

Posted by F 03/11/2005 at 22h16

Yesterday, a good friend of mine and ex-coworker contacted to me to share his frustration.

(he hates to be called “Polino”, so I won’t.. doh!)

He finished a software solution for a customer, and now an expert is reviewing his Java code.

The expert code reviewer insists on small performance optimizations, but he is way off target. He wants to micro-optimize, and to do it blindly.

For example, he reported that the following code was doing “inefficient String concatenations”:

String myString = "Some text here "+
                  "Some text there "+
                  "Some more... ";

And that this was an “inefficient way of creating Longs”:

 myList.add(new Long(1));

These examples are probably well optimized by modern Java compilers. But even if they weren’t, they probably don’t affect much to the performance of the system as a whole.