Burk on Books - Practical API Design

Practical API Design: Confessions of a Java Framework Architect

Author: Jaroslav Tulach

Published by: Apress on July, 2008

ISBN: 1430209739

If you write code then you are designing APIs and this book is for you.

Jaroslav Tulach, is the founder and initial architect of NetBeans and in this book he shares with us the lessons he learned during ten years of designing APIs that are used by developers around the world.

If others use your APIs, then the lessons found here are worth far more than the price of the book and the time it takes to read and digest it. Do yourself, and your users, a favor and start studying it today. And if others don’t use your APIs, then it might be that you need this book even more.

“Practical API Design” is divided into three parts: In part one, Jaroslav describes the theories underlying his approach to API design and his reasons for writing “another design book.” This section is reasonably brief and introduces the main concepts underpinning the rest of the book. In part two Jaroslav draws on his decade of experience and expounds on what works and what to avoid when designing frameworks and APIs for public consumption. Part three is where the rubber meets the road and Jaroslav shows how the theories and ideas from part one can be applied in daily life to achieve the practical application of the rules as described in part two.

The information in this book is relevant to every developer, though I will admit that some probably need it more than others. If you write code, you’re creating APIs - even if you’re the only one using them. If you’re creating APIs then knowing how to create and evolve those APIs benefits you and anyone who depends on those APIs to get things done.

For me, the bottom line on this book is that anyone who writes code winds up creating APIs, so it makes sense to learn how to create, evolve, and maintain them without breaking any code that already uses them.

There are some nice resources out there for anyone interested in learning more about this book. Here are just a few:

Jaroslav has created a website at “http://wiki.apidesign.org/wiki/Main_Page” with the intent of building a community around the book and the ideas he’s expressed in it.

Download chapter 1 from Apress at “http://www.apress.com/book/view/9781430209737”.

Check out InfoQ's interview with Jaroslav Tulach at “http://www.infoq.com/articles/tulach-practical-api-design”. In it there's a link to download chapter 3.

If you’re interested in learning more about the book, I have a more detailed review on DZone (and I’m told they may be giving away a copy) at http://books.dzone.com/reviews/practical-api-design.

Happy reading!

Burk Hufnagel

ITARC 20009 was a great success!

The Atlanta, GA edition of ITARC 2009 was held a couple of weeks ago and, based on the feedback I got from attendees and my own experience, it was a great success. Over 150 architects and people interested in becoming an architect spent two days in a beautiful environment (Thank you, IBM!), with good food, and learning from each other's experiences as well.

But the best thing was the wide variety of talks available, and the quality of the speakers (including Grady Booch via second life) who gave them. As a member of the chapter hosting the conference, and one of the speakers, I may be biased. But, I was able to attend a number of the talks and not only did I learn a good bit, but I found the speakers to interesting, well informed, and worth listening to.

The bottom line is that this year's ITARC was great and that you should make every effort to attend next year's Atlanta ITARC. For those of you not familiar with it, ITARC is short for "IT Architect Regional Conference"; so there may be one coming to your area later this year. I do know there's one scheduled for New York in late September, and you can always check the IASA home page for more information.

For any of you wondering about my talk, I'd say it went very well. The room was set up for 24 people but another eight or nine showed up and wound up standing in the back, so the attendance was excellent. During the talk itself, people looked interested and asked some questions, and the feedback I received from IASA indicted that the attendees enjoyed it and thought it was well done.

Mini Java puzzler - Zapped by static

I was modifying some legacy code (defined as code with no automated tests) and found something unexpected when I tried to use it. The original code was rather complicated (possibly because there were no tests), but this simplified version has the same odd behavior:

public class Test {
    static {
        initName();
    }

    static String name = "Sue";
    static Test instance = new Test();

    public static String getName() {
        return name;
    }

    private static void initName() {
        name = "Bond, James Bond";
    }

    public static void main(String[] args) {
        System.out.println("My name is " +
                Test.getName() + ".");
    }
}

So we have a class with one static variable, three static methods and one static initializer. Other than the static initializer, it looks like a pretty simple class that's easy to understand doesn’t it?

In case you’re not familiar with static initializers, let me paraphrase a bit of Sun’s Java Tutorial: "A static initialization block is a normal block of code enclosed in braces, { }, and preceded by the static keyword. They can appear anywhere in the class body, and the Java runtime guarantees they are called in the order in which they appear in the source code." 

That sounds kind of cool, but what’s the point? Why would you use one? Well, a static initializer executes when the class is loaded into memory and it is normally used to do some kind of one-time processing for the class. In this case, the initializer calls the initName() method when the Test class gets loaded into memory and before it’s main method executes.

So, getting back to the puzzle, the question is this: What does the above code do when you run the class?

Here are the possible answers:
   A) It prints “My name is Sue.”
   B) It prints “My name is Bond, James Bond.”
   C) Nothing, because it doesn’t compile.
   D) None of the above.

I recommend taking some time to figure out your own answer before reading any further. You’ll get more out of this is you do. Don’t worry, I’ll don’t mind the wait.

Ready to look at the answers? Good. First things first. Answer C, "Nothing, because it doesn't compile" is not correct. I included it just so I can tell you that I don’t like that kind of answer on a puzzle, or Java certification exam for that matter. Any IDE worth using will tell you if the code will compile or not. While it may have been a useful skill years a go, when our only tools were stone knives and bearskins, we’ve had better tools for so long now that it seems unreasonable to ask a question where “it won’t compile” is the right answer. OK, back to the puzzle.

What about answer B? Well, if you’ve attended one of Josh Bloch’s Java Puzzlers talks (or read my earlier Mini Puzzler), you know the whole point of this is to show you code that looks simple but behaves strangely. So you probably didn’t pick answer B - even though it looks like that’s exactly what should happen. And you would be right in doing so. The code doesn’t print  “My name is Bond, James Bond.”

What about the ever popular “None of the above.” Sorry, not this time. Answer D is not correct either.

By the process of elimination, the correct answer must be A. It prints “My name is Sue.”  and, as it turns out, that is just what does happen. Don't trust me on this, run it yourself - then come back for the explanation.

When I ran the original test code, I didn’t believe the results. It didn’t make any sense so I ran it in the debugger. If you do the same, you can see that the initName() method does get called before the main() method, and that when initName() finishes, the value of “name” is “Bond, James Bond” - just as we expected.

So what’s going on? How does “name” get set to “Sue”? Well, to mis-quote the spirit of Obi-Wan, “Use the source, Luke.”

In looking at the source, you can see that right after the static initializer, we’re declaring and initializing the “name” variable. Which seems odd because the initName() method already set “name” to a value - so it must already exist, right?

Sort of. The compiler sets aside space for the variable and includes code to initialize it but, because “name” is a static variable, its initialization happens when the class is loaded into memory instead of when the class constructor is called. It also appears that, like a static initializer, static variable initialization also happens “in the order in which it appears in the source code.” So after the static initializer is called, the code that initializes “name” to “Sue” executes and overwrites the value we expected to see. Believe it, or not.

So, how do we fix it? Simple. Swap the two lines so the variable is declared and initialized before the static initializer block gets called. Actually, there’s an even better solution for this kind of situation. Since the static initializer is only determining the value for one variable, have the line that declares the variable call a private static method that returns the variable’s initial value. Doing so would’ve prevented this problem in the first place, and ensures that nobody can accidently re-order the lines and start wondering why they’re seeing a line from a Johnny Cash song instead of something Sean Connery ought to be saying.

If you’ve got any feedback on this please post a comment.

Thanks for reading,
Burk

DevNexus 2009 review

DevNexus is the new name for the Atlanta Java DevCon conference, which is organized and hosted by volunteers from the Atlanta Java User Group (AJUG). The conference was recently re-branded as DevNexus because it's not limited to Java anymore. Don't get me wrong, Java is still a major focus, but there are other languages (some of which run on the JVM) and technologies that AJUG members use and we wanted to include those too.  

DevNexus has expanded to two days this year and may be even bigger next year. Not only that, but it went from two tracks to three, so there were even more tempting talks to choose from.

Speakers ranged from Neal Ford (Meme-Wrangler at ThoughtWorks, well known NFJS speaker, and author of The Productive Programmer) to Emmanuel Bernard (lead developer at JBoss, and spec lead for JSR  303: Bean Validation), to Peter Higgins (project lead for the Dojo toolkit) and Doris Chen and Justin Bolter (Technology Evangelists from Sun); and the topics were just as varied.

After some introductory remarks from Burr Sutter (Java Champion and AJUG top-dog), Neal Ford got the ball rolling Tuesday with his keynote "On the lam from the Furniture Police," which was an excellent look at how to be productive in a corporate environment that seems designed to prevent it. Neal's excellent keynote was followed by four hours of technical break out session on topics like Test Driven Design (not Development), browser optimization (aka getting around browser restrictions), grid computing, and how to create and use RESTful web-services with Java. The official day ended with Emmanuel Bernard's keynote on "Scaling Hibernate" which also gave us a look at some of the new features Hibernate supports, like sharding and full text search capability. After that, there was a "cocktail reception" for people who preferred a friendly chat (sometimes called networking) with other developers and architects over sitting in rush-hour traffic.

Wednesday got off to an interesting start. Doris Chen and Justin Bolter gave their keynote speech titled "JavaFX: The Platform for Rich Internet Applications" which, not surprisingly, promoted JavaFX as the best solution for Java developers who want to build RIAs. This was followed by Yakov Fain's keynote, "Picking the right technology for Rich Internet Applications" which compared Adobe's Flex, Microsoft's Silverlight, and JavaFX. During the speech he stated his belief that JavaFX might be a contender in 2010, but not today. I found this a little disconcerting, having just heard about what JavaFX can do. While I'm not sure I agree with him, I do think Yakov made some good points, though things may change with the release of JavaFX 2.0 slated for later this year. In case you're interested, his recommendation for developers that need to start an RIA project today was to use Flex.

After the clash of the RIA titans, there were three hours of breakouts mostly geared toward RIA or web development; topics included JavaFX, Java and Flex, developing modular Web applications using Spring 3.0, and GWT.  There were also some server-side topics like a JEE 6 preview, a look at Spring 3.0, JSecurity also known as Apache's project 'Ki', anda look at JVM-based dynamic languages in the enterprise.

The conference ended with a rap-session hosted by Burr Sutter, AJUG's main leader and Java Champion, asking for ways to improve the conference next year and how we can get the word out about it so more people will attend. There were several good suggestions, and you've just read part of my solution to the question.

DevNexus was a great conference and well worth the cost (just $185 for the whole thing) so start planning to attend next year; you'll be happy you did. BTW, the price is set so that the costs of the conference are just about covered; this is not a 'for profit' venture, it's part of the way that AJUG works to build the Atlanta Java community. If you want to get involved, start attending the monthly meetings (they're free) and see what you've been missing out on.

If you were there, or wished you were, and have something you'd like to share then please leave a comment.  

Thanks for your attention,

Burk

97 Things Every Software Architect Should Know hits #1 at Amazon

A few days ago, I shared with you my joy about a new book titled "97 Things Every Software Architect Should Know" which I co-authored with 52 other architects .

Even though it's only been available for a couple of weeks, the book is doing very well. In fact, Amazon's sales ranking currently shows it at #7 in Software Development, and #1 in Design & Architecture. It's also #1 in Surveying & Photogrammetry, but I think that's because the tags include the word "architect".

(Note: If you click on the slightly blurry image below, the link will show you the actual image from Amazon.com in all its glory.)