Skip to main content

Call on Me

Posted by editor on January 3, 2006 at 8:14 AM PST

Rules for API designers

All of us are API consumers. Some of us are API producers. It seems obvious that when creating an API, you'll use the knowledge you've accumulated from using other API's in designing yours. So, given some well-established practices throughout the Java class libraries, this should all be straightforward, right?

Feel free to take a second and laugh at the thought of this.

Of course API design isn't easy. That's why there are remarkably bad examples throughout the Java universe, and more than a few in core Java itself.

But rather than curse the darkness -- and you can use the comments to this blog to point out some of the worst offenders if you like -- Eamonn McManus and Elliotte Rusty Harold (author of XOM and owner of the project Amateur) have offered to shine a light.

Eamonn's Artima blog entry Java API Design Guidelines summarizes a presentation by Eliotte from last month's JavaPolis and adds some pointers from McManus' own experience developing and working with API designs. "There are tons of books and articles about how to design and write good Java code, but surprisingly little about the specific topic of API design. Yet with the proliferation of new Java APIs, whether through JSRs or through Open Source projects, this is an increasingly important subject. I've been closely involved with the evolution of the JMX API for over five years and have learnt a great deal about what works and what doesn't during that time. During the talk, I had the odd experience of continually wanting to cheer as Elliotte made point after point that I hugely agreed with."

The key point to take away is that API's need to be able to evolve. Just thinking through that imposes some good design constraints: once you know your API will need to grow, and will be used in unanticipated ways, you'll think small, think expandable, and run some 0.x releases past your testers. Most importantly, you can never remove classes or method names, so just get the smallest set of absolutely correct functionality in there for your 1.0.

Also in Also in
Java Today

according to the article IT Spending Moving from CYA to SOA, "a new report from Financial Insights claims that IT spending over the next few years will be driven by enterprises migrating legacy architectures to SOA, and shoring up their data -- through management and security projects. The new survey reflects a shift in priorities for enterprise IT spending away from concerns about regulatory compliance, such as Sarbanes-Oxley projects."

In Projects and

Project Looking Glass, which uses modern GPU power to enhance the desktop experience, is nearing a major public debut. OpenSolaris has announced that the Project Looking Glass platform and sample desktop will be included in OpenSolaris, with a target release of November 2006.

The premiere episode of the GAME ON! Podcast features Sun Chief Gaming Officer, Chris Melissinos, speaking on the topic of Java game development. He talks about Sun's involvement in the gaming industry, lists five top games on, talks up noteworthy console games, and discusses the ESRB rating system.

In today's Forums,
tackline has some thoughts
Re: Turn Off Sorting for JTable TableModel Insert?
The obvious way to make new rows appear at the end is to sort first on a hidden column. The value can be cleared at a time appropriate for the application. The technique has the major advantage that concurrent updates to the table will still work. From a usability stand point, I don't think scrolling to the bottom of a sorted table when adding a new record makes much sense. Better would be to add to a matching, headerless table outside of the scrollable area. —

Re: primitive and generic complex number data types, mifeld writes:
"It is not simple to add complex numbers to Java. Of course, you (or Java team) can write generic class like ComplexNumber, but programmer will need to translate every expression to method calls. It is not easy to write the code and it is very difficult to read one. On the other hand, Java style cannot absorb C++ tricks like operator declaration."

Marcelo Mayworm says Teaching Java platform to undergraduate students is a process in today's Weblogs:
"Learning Java platform is a process. Some JUG Petropolis members and me have been teaching Java platform for five years free of charge in an academic environment. Our focus is to help somebody in a academic community, who wants to learn Java. I always describe a strategy to make sure that students can continue to learn Java effectively."

Kohsuke Kawaguchi reports on
Making process with Dalma, in which he offers
"a year-end progress report about my Dalma project. Byte code, byte code, and more byte code ... "

In Joel complains that Java is too easy, Jack Shirazi reports that "Joel Spolsky has written an article essentially complaning that Java is too easy."

In today's
News Headlines

Registered users can submit news items for the href=""> News Page using our
news submission
. All submissions go through an editorial review before being
posted to the site. You can also subscribe to the href=""> News RSS

Current and upcoming Java

Registered users can submit event listings for the href=""> Events Page using our href="">events submission form.
All submissions go through an editorial review before being posted to the

Archives and Subscriptions: This blog is delivered weekdays as
the Java
Today RSS feed
. Also, once this page is no longer featured as the
front page of it will be
archived along with other past issues in the href=""> Archive.

Rules for API designers