Skip to main content

How Come U Don't Call Me Anymore?

Posted by editor on November 24, 2006 at 7:21 AM PST

What's the best way to make sense of an API?

For the earliest Java programmers, a handy copy of Java in a Nutshell was essential. Yet nowadays, the need to look up method signatures in a book has fallen by the wayside for a lot of people, as IDE's auto-complete method names and fill in parameters. Combined with Javadocs, this gives a lot of developers everything they need.

Or does it? How much information do you need to successfully use a given API? For example, Container.add (Component, Object) seems straightforward enough, but do it on a Swing root pane container (like a JFrame) and you get an exception (because you're supposed to add to the root pane, not the container itself). Even though the syntax is viable, the semantics aren't. This argues for some kind of documentation beyond just descriptions of methods, in favor of one that describes higher-level processes, and where the various method calls play into those processes.

Of course, some would say that's a design smell that indicates Swing itself is broken for having a seemingly sensible method call blow up in your face so badly. There are some who suggest that API's that aren't themselves self-documenting are inherently defective. You see this a lot from the Objective-C camp, where you have to name your parameters in every call, even when the possible parameter is obvious from its type (for example, if Obj-C had an equivalent to the Container.add() above, calling it might look like [myContainer add object: myComponent constraint: gridBagObject]. As you can see, this makes the purpose of the mysterious second argument explicit to every caller. More clarity, at the price of more keystrokes. So what do you think of that approach?

With this in mind, the latest Poll asks "What's your preferred form of API documentation?" Cast your vote on the front page, then visit the results page for current tallies and discussion.

In Java Today,
the second part of the SDN's introduction to JAX-WS has been posted, continuing a tutorial on how to develop web services and their clients with Java SE 6. In Introducing JAX-WS 2.0 With the Java SE 6 Platform, Part 2, you'll see how to create a client to the eBay production server, using Java SE 6 and NetBeans.

Started a project but don't know how to use the source control repository or even what it's for? partner Collabnet has posted An Introduction to Version Control on their openCollabNet site. It offers an overview of the concepts of version control, compares the lock-modify-unlock and copy-merge approaches, and offers a basic vocabulary of important version control terminology.

The Pragmatic Problem Solving blog has posted an article on Clustering - EJBs vs JMS vs POJOs with a focus on the Java EE technologies: "Scaling out a java application traditionally has not been easy. There are a number of technologies that allow you to distribute data across multiple JVMs, but most of them are cumbersome, high maintenance and do not scale linearly. Let's discuss the pain points involved in using three different approaches namely EJBs, JMS and POJOs."

Kohsuke Kawaguchi has been doing a little hardware hacking in DIYOrb - my own "extreme feedback" device for Hudson, the first of today's Weblogs: "I'm normally a software engineer, but one day I felt like doing a hobby electronics. This is my record of how I built my own orb."

Performance: Too much of a good thing?, Mark Lam writes:
"For a JavaME VM implementation, how much performance is enough performance? This article explains why some optimizations don't make sense."

Kirill Grouchnikov covers an attractive GUI effect in
Spicing up your buttons with rollover effects:
"This entry shows "image ghosting" effects on Swing buttons with icons."

atus is hoping to see the Isolation API in JDK7, in a message in today's Forums.
"A feature that I really wanted to see in JDK5, which was skipped again in JDK6, is the Isolation API. (In short, this feature makes it possible to run multiple Java programs in one JVM. E.g. the JVM could start as a service at boot time, making all Java program startups instantaneous. Memory consumption would reduce too. This would probably be the last step to make Java app(let)s feel native.)"

greeneyed says there's no perfect content management system, in the message
Re: CMS:
"We have been analisying a lot of CMS lately for our organization and all I can tell you is that there is no "best" product. It depends *a lot* on your requirements and how flexible they are and how much you can compromise to do things the way the product wants you to, instead of the products adapting to your way of working, as there is no perfect solution, no matter what they tell you. Before trying to choose a CMS, I would try first to decide "what you want the CMS for."

derjohannes is confused because
JAXB is demanding a file xjc does not create:
"A JAXB application I am trying to run on a JBoss Application Server cannot initalize a JAXBContext because a file is demanded that cannot be found. But: If I let xjc compile an XML schema file, there is no such file created and there seems to be no command line parameter to force xjc to do so. Where can I get the properties file?"

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.

What's the best way to make sense of an API?