Blogs

From APIDesign

The Theory | Practical Design | Daily Life

[edit] Confessions of API Designers

For a long time I was asked to create a blog and join the blogosphere. One my friend even told me, that people having no blog really do not exist. That is why, here is my blog to prove my existence. However, in the spirit of TheAPIBook, I'd like this to be place for cooperation. So, if you feel you have something to say about API design, and you are looking for a place to prove your own API and Blog existence, just tell me. You are more than welcomed to join!

[edit] Theory Thoughts

[edit] Why SQL is not Ready for Internet Age?

Time to finish my SQL story. Today has been my last day in Sun. Tomorrow I'll sit at the same office and chair, but I'll be Oracle employee. Before that happens I can enjoy for the last time complete cluelessness about SQL. So here is it: follow this link to learn why SQL is not ready for internet age.

--JaroslavTulach 20:23, 31 August 2010 (UTC)

[edit] A Brief, Incomplete, and Mostly Wrong History of SQL

The SQL story was in my mind for a while. I was lazy to write it down, I just talked about it with various persons directly. But I can't wait any longer. Since Sep 1, 2010 I will start working for a major SQL database vendor and as such I should publish my SQL essays as soon as possible. Later it might contradict opinion of my employer. Learn about the alternative view of SQL history now!

--JaroslavTulach 09:53, 23 August 2010 (UTC) .

[edit] Are You Waiting for Your Application to Launch?

I am not sure what is your experience, but fast Startup is one of the important things netbeans:performance team focuses on. Did you find yourself having coffee break while waiting for your application to start? Then, you probably care. However not every kind of startup is similarly important. As such I have written little classification or startups. Walk through various startup types here.

--JaroslavTulach 05:46, 22 July 2010 (UTC)

[edit] Choose Your Dependencies Wisely!

I've just seen following quote in my mailbox: 'perhaps NetBeans is easiest to build plugin for...' (read: easier than other IDEs).

Well, the mileage may vary. However if you want (or even have people with knowledge of) 'standard' modularity and standard UI toolkit, then NetBeans Platform 6.9 is the easiest way to merge these two. We support Swing for ages and dedicated last nine months to interoperability with OSGi. Some even say it is easier to use Equinox with NetBeans IDE 6.9 than with Eclipse IDE.

I'll continue to investigate various interoperability options as part of my daily job. At the end it should not matter whether you code for Eclipse or NetBeans, but whether you have the right dependencies (read: no SWT, bunch of Swing and don't forget Lookup ;-). This is another sign that (when there is a common ground - a lingua franca - e.g. common module system for Java) interoperability will be easier than ever. Building applications will be like composing them from Lego bricks. There is only one prerequisite:

Choose your dependencies wisely!

--JaroslavTulach 08:11, 19 May 2010 (UTC)

[edit] Simplest Teleinterface

New Teleinterface has just been discovered! I was reading through my older posts today and I realized that MagicalStrings are in fact a form of Teleinterface.

--JaroslavTulach 10:11, 9 May 2010 (UTC)

[edit] Blame Your Architect!

As a continuation of my sporadic thoughts about MetaDesign I decided to look closer to the topic of responsibility today. To introduce the topic let me ask. What is more effective: if one architect does its job correctly or if thousands of users adjust to poor design? Find the the answer and instructions for proper use of your trashcan here!

--JaroslavTulach 07:44, 25 April 2010 (UTC)

[edit] Is OSGi Secret Society Ruling the World by Using Magical Buzzwords?

Do you know how to build a secret society? Use MagicalStrings! Recently my OSGi adventures and generous help of Tom Watson resulted in two things: I made Netigso more efficient. I realized that any API that uses strings can be made quite cryptic! Learn more about my inquiry...

--JaroslavTulach 20:15, 8 April 2010 (UTC)

[edit] Ever met an architect?

Is there anything like universal architecture rules? For a while I am seeking for ones and today it is the right time to share my findings. They are not complete, but join me with your comments on this discovery journey.

--JaroslavTulach 19:29, 10 March 2010 (UTC)

[edit] Know it Better!

Based on classical SuperVsInner example I'd like to formulate one important advice to follow when designing an API.

--JaroslavTulach 12:40, 24 February 2010 (UTC)

[edit] What is a chance?

What is a chance?

--JaroslavTulach 19:11, 17 February 2010 (UTC)

[edit] History Repeats in Cycles

Let me quote Tim and Andreas conversation about Ruby. Is every human activity destined to repeat what has already been invented? Repeat on a new, advanced level, so we can not only repeat old mistakes, but also add new ones?

--JaroslavTulach 05:23, 28 January 2010 (UTC)

[edit] Is Paradox unnatural?

Do you like paradoxes? Do you seek for them? Do you find them strange? Here is my little explanation why this is very natural, very human.

--JaroslavTulach 09:57, 19 January 2010 (UTC)

[edit] Quiz: Name the First OOP Language!

Do you know what was the first OOP language? I thought I knew - till yesterday when I read great essay about OOP. Enlighten yourself, read it too and learn name of the grandfather of all OOP languages!

--JaroslavTulach 08:20, 3 November 2009 (UTC)

[edit] Retarded Swing Programmer. Was: AWT Dispatch Thread...

I have to defend myself. I have received a lot of comments in response to my recent essay about use of AWT Dispatch Thread. Especially this one: Why was the event display thread used for non-painting computation in the first place? It's Swing 101 to not have long delays on the EDT...it's covered in any book on Swing as well. made me feel retarded for a while. But I am not bad (Swing) programmer. Thus I started to seek deeply in my soul and I have an explanation why some think we are doing things in wrong way, while we don't: It is because of DCI's specifics!

--JaroslavTulach 20:42, 30 October 2009 (UTC)

[edit] AWT Dispatch Thread Shall be Used Only for Painting!

Here is a little essay building up on adventures of this week and explaining the difference between our attitude towards rationalism and empiricism.

--JaroslavTulach 14:32, 23 October 2009 (UTC)

[edit] OSGi: Too Much Love will Kill You

Recently I was thinking about the way RangeDependencies are specified in OSGi and I was trying to find reasons why that is wrong and inside out. I don't think I succeeded yet, but I can at least show that with RangeDependencies one increases the risk of running into NP-Complete problems. RangeDependencies give you so much lovely power, that they somehow need to strike back and hurt you. Get ready for that!

--JaroslavTulach 19:53, 18 October 2009 (UTC)

[edit] Quiz: Who invented Convention over Configuration?

Do you know who invented Convention over Configuration paradigm? Me!? No, I am joking. But today I wanted to write a blog about one API Design Anti Pattern and surprisingly I realized that Convention over Configuration hype started by modern frameworks was in fact outrun by one core Java framework. Or do you know about older example of Convention over Configuration in Java? C? Fortran?

--JaroslavTulach 12:16, 20 September 2009 (UTC)

[edit] Is Maven Over Abstracted?

Not really. It is just not properly documented. I'd like to thank you all for your feedback on my recent post about Maven. I have successfully used the assembly plugin to create ZIP containing all my application JARs. This time I'd like to point out why I failed to do so without your help before.

--JaroslavTulach 09:14, 15 September 2009 (UTC)

[edit] Can Math Save Your Life? Sure, by eliminating NP-Complete Problem!

New proof is here!

The LibraryReExportIsNPComplete outlined the problem one has to face when practicing DistributedDevelopment. The page also proved that in its global scope the problem is NP-Complete with all its implications.

Surprisingly there seems to be an easy cure that eliminates the NP-Complete nature of the library re-export. Visit LibraryWithoutImplicitExportIsPolynomial to learn about complete repositories.

--JaroslavTulach 08:46, 2 September 2009 (UTC)

[edit] Imagine Living without Compatibility!

BackwardCompatibility is the only weapon we have against the madness of wikipedia::NP-Complete problems. Unless you want to turn your developers and application assemblers into highly performant NP problem solvers, learn how to achieve BackwardCompatibility.

--JaroslavTulach 20:46, 27 August 2009 (UTC)

[edit] Math that Affects Your Life. Learn to Avoid NP-complete Problems!

Hi all mathematicians out there! At least I hope there is someone with a little bit of math background among people reading this blog. I have a proof of existence of a new NP-Complete problem. First of all I need someone to look at it and tell me if it is correct. I believe the idea is fine, I am not sure if the proof itself is technically correct.

Hi the rest of us! For those who don't want to bother with complexity theory and rather stick with their keyboards or planning sheets, there is also a summary. Look at it and learn why a little bit of math can be good for your own design skills.

--JaroslavTulach 07:52, 25 August 2009 (UTC)

[edit] Changing Rules of the Game

When facing a problem, what can you do? Either seek a solution or redefine the problem. If you have power to change the rules of the game, then all problems become immediately much simpler. See this general principle in action during modularization of the Java SE.

--JaroslavTulach 05:49, 25 June 2009 (UTC)

[edit] False Expectations

Are you about to modularize your API? Do you understand what such step can bring you? Good. However check this note to also understand what it cannot help with...

--JaroslavTulach 14:57, 16 June 2009 (UTC)

[edit] Close Proximity of API-less APIs

Can you imagine world without APIs? I can now...

--JaroslavTulach 21:27, 11 June 2009 (UTC)

[edit] Hail to Modularity!

I've moved the modular programming manifesto into wiki. Will it stimulate readers to fix it and make it more up-to-date?

--JaroslavTulach 13:26, 22 May 2009 (UTC)

[edit] A Brief, Incomplete, and Mostly Wrong History of Programming Languages

A short look at history can quickly explain all our sufferings. I did such excursion in Chapter 1. The need for Cluelessness is shown there by describing history of computer languages and their oscillation between Rationalism and Empiricism resulting in more easy to use languages (e.g. for dummies) that produce programs requiring gigabytes of memory, tons of CPU time and sometimes enormous amount of virtualization to execute.

I believed my explanation was at least a bit entertaining, but it is definitely nothing compared to A Brief, Incomplete, and Mostly Wrong History of Programming Languages. Give it a try and read it! Very entertaining and in my opinion showing the incorrigible mankind's desire for cluelessness too.

--JaroslavTulach 17:14, 15 May 2009 (UTC)

[edit] Feeling Independent?

Most of our programs don't live in a vacuum. They require some supporting environment in order to work. One might think that such dependencies on surrounding are unified for whole lifecycle of a library. That would be false assumption. As the following note discusses there seem to be many TypesOfDependencies.

--JaroslavTulach 16:47, 23 February 2009 (UTC)

[edit] How current can you be? Not much, that's certain!

Looks like the Practical API Design book has a new reader. Welcome! Moreover David is not an ordinary reader. He is not afraid to ask questions. Perfect! Thanks for your interesting question and please check my answer.

--JaroslavTulach 21:09, 6 February 2009 (UTC)

[edit] Just Three Kinds of BackwardCompatibility?

Finally I finished the online page describing what it is BackwardCompatibility. It defines three different kinds: source, binary and functional and I am curios to know: Is that all? Or can you think about other types of compatibility?

--JaroslavTulach 15:30, 21 December 2008 (UTC)

[edit] Declarative Registrations

I see the year 2009 as the year of annotations. At least for the NetBeans project - we are about to use them much more frequently than we did so far. That is why I cannot stop thinking about various ways of using Declarative Programming. As a result, there will be more blog posts about such programming style. Here is one: my little explanation why less is better when using the Declarative Programming registrations.

--JaroslavTulach 14:43, 5 December 2008 (UTC)

[edit] 3 Sides to Every API

3 Sides to Every API is my reaction to excellent Beauty matters summary provided PetrHejl. It is my attempt to agree with him, while defending TheAPIBook's often proposition that beauty does not matter...

--JaroslavTulach 21:37, 24 November 2008 (UTC)

[edit] Beauty Matters

J. Tulach in his Practical API Design book claims that beauty is not the most important requirement when you design your API. Because he is repeating this multiple times at various places I got the bad feeling that this could be easily misunderstood. Let me clarify...

--PetrHejl 14:38, 11 November 2008 (UTC)

[edit] What Makes a Technology good?

Dear API users, can you help me define term Good Technology? What makes a technology good, useful? How do you evaluate quality of the APIs you use? I've just written few thoughts about this topic down, however I'll be glad to hear your opinion. Is NetBeans platform Good Technology or bad?

--JaroslavTulach 18:26, 3 November 2008 (UTC)

[edit] The Better Compiler the Worse API!?

Today I am ready to announce a really nice addition to the collection of weird examples of APITypes. Did you ever suffered with compiler optimizations? Did you ever thought about them as being an example of an API?

--JaroslavTulach 18:57, 16 October 2008 (UTC)

[edit] More on Ruby, Gems and Modularity

The Ruby anonymous coward which brought duck-typing into attention of readers of this blog, added new comments to our discussion. The note presents Gems and I have to admit that by having Gems as standard packaging and dependency management tool, the Ruby gets far ahead standard offerings of Java. Of course unless you decide to use NetBeans runtime container or similar...

--JaroslavTulach 09:32, 30 September 2008 (UTC)

[edit] Are APIs like diamonds or like stars?

Is it uncommon that the same invention is discovered multiple times? Multiple times by different people? At the same time? It is indeed surprising to see something like that, however if you look back at the history of science, it is not that uncommon. I know that lightning rod has been independently invented by at least two people in the middle of 18th century. What was so special then that allowed such independent break-through?

For a centuries great mathematicians were troubled by Euclid's fifth postulate. It felt somewhat unnatural compared to the first four, the general expectation was that it is not necessary and it can be derived from the four others. Many tried, yet nobody succeeded. However, at the begging of 19th century things changed. Independently János Bolyai, Nikolaj Lobačevsky and maybe also Gauss discovered that fifth postulate is independent on the others. As such we can have geometries accepting and denying it and yet they'll make sense. Why at that time? Why three people at once?

There are many more cases that exhibit such coincidence. I do not think anyone has reasonable explanation for that, my personal feeling is that each era has something in the air that turns people's attention towards similar problems and tunes their mind to frequencies helping discover similar solutions.

I've been thinking about the laws of proper API design since 2001 and for a long time I believed that I am the only one who cares about such topic. I was pleasantly surprised during the Java One 2005 fully crowded BOF. However I still believed NetBeans is the only organization that does some research in this area. You can imagine how much I was surprised when I found out, at the end of 2005, that Josh Bloch had spent some time thinking about API design too. And that was not enough, my surprise even grew, when I found out that 80% of his observation in his presentation are similar to mine. There must have been something in the air, mustn't it?

As one comment stated: These things are a lot in Jaroslav Tulach's new book. Only real difference is that 'diamonds' above are 'stars' there. This comment brings us to the title of this post. Things looking similar at first sight may not be same underneath. At the end of 2005, most of the ideas were ready. They just waited for someone to put them into a book. When I finally began to write TheAPIBook, I was searching proper allegory to introduce the reader to the special context of API design. I knew the diamonds methaphor, but I could not use it, as I believe it is missing something important!

There is a significant difference between diamonds and stars. While diamonds are said to be forever, nobody considers stars eternal. As such the allegories are not the same. They are in fact quite different. If you get through the Practical API Design book to chapter 15 and chapter 19, you'll find out that if you have good support from runtime container, properly versioned APIs and you know how to allow co-existence of multiple versions of similar APIs, you can make your old APIs disappear, yet keep backward compatibility. Of course, this is not a common operation, just like stars do not burn out everyday. However, if you really need to, you can send your API (aka your star) towards a black hole and make it disappear there. Moreover, you can do it in a completely user driven way, where the speed of dying is driven by number of remaining users of the old API, e.g. observers of your star. This is all possible and the NetBeans project done that few times.

In short, although APIs look eternal, they are not forever, they are more like stars.

--JaroslavTulach 03:34, 26 September 2008 (UTC)

[edit] Can duck-typing help with API evolution?

I've just received a comment mentioning Ruby's duck-typing as a solution to evolution problem in API discussed herein earlier. Interesting food for thought! Thanks! However so far I have to admit that there is no obvious benefit, at least not in the particular case. Read more and feel free to comment...

--JaroslavTulach 15:54, 22 September 2008 (UTC)

[edit] getDate() method evolution thoughts by Tim Band

Imagine that you have a class with method getDate() which returns the date of creation of that object. Can you add setDate() in new version? Can that change be compatible? This is topic discussed recently by Tim Band at LtU discussion forums:

If the get_date function had a comment stating "Returns the date at which the object was created" then you have to update that comment -- and that semantic change to get_date is the break.

It is hard to think of a semantic meaning for a get_date function that covers the setting of an arbitrary date, so let's imagine that we want to add "refresh_date" and that the original documentation of get_date said "Returns some date between the creation of the object and the calling of the function", then adding refresh_date is OK.

If get_date is undocumented or ambiguously documented, you need some process to resolve this. At Symbian we have a board of beard-strokers (of whom I am an occaisional member) who deliberate on the difficult cases and inform the customers of our decisions, and get feedback on certain issues. This process is considered integral to our backwards compatibility promise.

It is tempting to dream of a world where a programming language or supporting infrastructure would free us of the compatibility burden, turning it into just another language feature. However, it is in the mucky world of semantics, where interfaces meet the world of human use and abuse where this stuff really matters. You can break compatibility if you know it won't matter (we once changed our formerly weird floating-point implementation to match IEEE with no-one even noticing), but you can't make some compatible changes (changing priorities of processes that have no stated dependency on each other is a classic).

Having said all that, there is much work to be done on merely keeping interfaces stable. You can get quite far just by assuming that the source interface (your class and function signatures in your .h files in C++) matches the semantics, and picking up incompatible changes to that over time (removal of functions for example) and alterations of the binary interface in relation to the source interface (adding a virtual function for example).

Of course, occasionally you must allow customers to override common sense; I'm sure many readers here are familiar with the story of Microsoft Windows' memory manager running in a different mode if it detected Sim City running -- this is always a risk and you have to be aware that you might be forced to retract changes in the face of politics.

I should probably stop now, although really I'm just getting started! Tim Band

--JaroslavTulach 07:32, 17 September 2008 (UTC)

[edit] Joel Neely on Enums in APIs

Today I found out that there is an interesting comment to the blog entry published by Andrei a week ago. Andrei shared with us few thoughts on the use of enums in API. Joel Neely noted that it all depends on how the enum is used in the API. I cannot do anything else than agree with his words, yes it depends on whether the enum is used covariantly or contravariantly. If the enum is used covariantly only, then extending it with new constant in new version of the API is OK.

The only problem is that as soon as you publish an enum, one can immediately write a switch statement over it. And the switch statement's behaviour is contravariant. That is no good news for the API writers and compatible extensibility of their enum based APIs...

--JaroslavTulach 21:22, 26 August 2008 (UTC)

[edit] Are there any Languages Ready for API Evolution?

When I was describing my API design adventures in TheAPIBook, I could not realize that many of these problems would not even appear if we had better languages, or systems more suitable for the DistributedDevelopment.

I may be wrong, but I do not know about any language that would support modularity. And here I mean not compilation piece by piece, but also modularity in time. Because that is the kind of modularity that is needed quite often during development of APIs for our libraries.

At one point of time we release a version of a library and distribute it to others by publishing it on the website. Now people unknown to us, distributed all around the world download it and use it. As a result, the amount of applications built on top of such library is increasing, which implies also that the amount of bugs and feature requests is growing too. After a while the time to release new version of the library comes. However what if the first version used to have a class:

public abstract class View {
  public abstract String getDisplayName();
}

What if one of the feature requests demands to add an HTML title to each view. Can we change the view class to following form:

public abstract class View {
  public abstract String getDisplayName();
  public abstract String getHTMLTitle();
}

Indeed, this cannot be done. Existing subclasses of View would no longer compile, because the change is not source compatible. Also, even if someone links already compiled subclass with the new version of the library, the Java virtual machine will complain and throw some kind of linkage error, as definition of an abstract super class method is missing.

I would love to see a language or system that would fail the compilation whenever I want to modify my already released classes in a style that could prevent some of their users to continue to use them in previously working way. This would be the real modularity, which is ready for changes in time. So far it seems to me that the current languages do not deal with changes in time really well. Just like Andrei described in his Enums in APIs blog, it seems that our languages do not think about the process of API evolution much and include constructs that one needs to avoid to make DistributedDevelopment possible.

Releasing new version of libraries with modified APIs is really common and our software engineering practices cannot live without it, yet it seems that there is no language in the world that would make this easy and clueless. Or am I wrong?

Also lively discussed at Lambda the Ultimate.

--JaroslavTulach 06:50, 24 August 2008 (UTC)

[edit] Visual Aspects of an API

The usual consensus is that visual aspects that are presented just to the end user are not part of API of some application. This is usually well justified and correct, except in some situations...

--JaroslavTulach 11:40, 11 August 2008 (UTC)

[edit] Dependencies Are Important Type of API

New type of API has been discovered!

JaroslavTulach 07:05, 15 July 2008 (UTC)

[edit] Practical Design

[edit] JDK6 API for SQL Syntax Completion

Do you know that there is a standard Java API for extending any IDE with code completion? That you can easily, without writing any IDE plugin show list of SQL tables inside strings? Learn more, try out whether your favorite Java IDE comes with real support for Annotation Processors. If not, make a switch to the best IDE that does that!

--JaroslavTulach 18:56, 29 August 2010 (UTC)

[edit] LiveDB: Make Your Database Schema Part of Your Sources

I really hate when something is defined at two places. Things like that may easily get out of sync and where is the truth then? I am glad that my little LiveDB experiment shows one more field in Java where such duplication may no longer be necessary: with LiveDB you can access schema of your database live. Live not only during compilation, but also during developement from inside of any good IDE.

Get the LiveDB sources to learn more. Watch our LiveDB screen cast. Share your thoughts!

--JaroslavTulach 17:17, 30 July 2010 (UTC)

[edit] Equinox Compatibility Shaking

While trying to upgrade from version 3.5 to 3.5.2 I noticed some EquinoxCompatibility problems. Why can't an upgrade of a minor version of some library be just a plain drop in replacement? How can someone rely on a library which shakes its behavior like an amoeba?

--JaroslavTulach 09:34, 13 July 2010 (UTC)

[edit] Equinox is not Ready for Modular Environment!

Today I noticed one bootstrapping problem with Equinox which makes it completely unusable for execution in modular systems. Rather than fixing it I decided to write (thought) provoking blog about problems BootstrappingEquinox. I hope it will help everyone understand how bad the situation is and encourage creation of proper fix.

--JaroslavTulach 08:20, 7 May 2010 (UTC)

[edit] Unbearable Painfulness of Being Stateful

Do you know the feeling like this? Something leaves strong impression inside you. So strong that you want to speak up. Later you calm down. Then you get into similar situation again. This time you want to scream. Then you forget. At least you try. But the nightmare comes back again, and now you can't remain silent.

This happens to me particularly when using one specific NetBeans API. For a while I was just complaining to myself, but then I realized the cause of the problem. The API was properly reviewed (even by me) and looked OK, but as time shows, there is a hidden catch: It is too stateful! It is easy to write program that compiles against that API. It is much more harder to create a program that also executes without throwing runtime exceptions.

Have you ever had similar experience? Has it been also because of the API being too stateful? Compare your experience with mine.

--JaroslavTulach 14:29, 2 May 2010 (UTC)

[edit] The Fastest OSGi Container

Are you seeking for the world's fastest OSGi container? Then you are on the right blog - since yesterday the OSGi container with fastest start is provided by NetBeans!

--JaroslavTulach 12:15, 2 April 2010 (UTC)

[edit] Introduce Yourself to Your Mirror!

Are you talking to yourself when standing in front of a mirror? Are you properly introducing yourself to your mirror picture? No!? Well, you should be. Good communication protocols require people to introduce before the real chat starts.

To improve your design skills, I suggest you to do it even dealing with a man in the mirror!

--JaroslavTulach 03:38, 25 March 2010 (UTC)

[edit] Reach harmony. Play Single-tone!

A step by step cook book for properly using Injectable Singletons is now available. In case you ever wanted to expose your application state, the Injectable Singletons approach gives you sound, simple, testable and extensible way to do it. I don't expect a massive migration from DI to Injectable Singletons, but in some situations this pattern may be handy. If you find Injectable Singletons useful, share your experience with others.

--JaroslavTulach 20:12, 9 February 2010 (UTC)

[edit] Overcome Your Fear of Being Single(ton)!

Have you ever felt lonely like a singleton? I do from time to time. Especially when I get a feeling that I cannot break through and outreach people who I'd like to talk to.

Surprisingly this often happens when trying to talk to DI community. I cannot enumerate how many times I heard: "This is not DI!" "Singletons are wrong!" "Learn to use Spring and then come back!" Looks like I have a problem with DI guys. But that is not true, I like DI, I've (already) learned a lot about it! It is more that some DI proponents seem to have problem with us. It usually go like this: A Joe Developer after being hurt few times by coding without DI, learns about DI, finds it amusing, uses it successfully, things start to make sense. Then, rather then being happy that Joe's own projects are fine, Joe starts to evangelize the right way to code. What is not DI is wrong or at least old fashioned, and deserves a rewrite. It actually does not matter what it is, but if it is not using DI, it has to be bad.

The problem is that Joe never investigates what the other technology is, never tries to understand whether it is wrong or not. Joe has pre-made answers for everything. Joe's opinion is straighten inside of own community. The fact that the community is rapidly growing ensures Joe that this is the only way to deal with programming. Everyone else needs to convert, or be crucified. The faster, the better. Don't waste time trying to understand the others!

As a result not many DI fans outreach and give us a chance to speak up. Thus I am very glad that Witold Szczerba did it, and asked very interesting question with a lot of good reference material. As a result I could sort out my own thoughts and create a defense of singletons.

Don't be afraid of singletons! They are quite friendly if you know how to use them!

--JaroslavTulach 08:26, 25 January 2010 (UTC)

[edit] Tim Boudreau on Lookup

In response to a mailing list question Tim decided to explain everything you ever wanted to know about Lookup but were afraid to ask.

--JaroslavTulach 08:59, 20 January 2010 (UTC)

[edit] Video: Paradoxes of API Design

Do you want to learn something about API design while watching TV? Then you need to get my show from Blip TV!

--JaroslavTulach 11:28, 12 January 2010 (UTC)

[edit] The Little Manual of API Design

When googling around for new references to my book I found out a year old PDF from Trolltech. Nice condensed introduction to API design for C++ was written down by Qt developers: troll.no. There is not much new topics covered, compared to TheAPIBook, but some observations are ammusing. I especially like the little differences and strange similarity of the C and Java worlds.

The pdf may be nice example that when the time comes, the same things start to independently happen in different places at the same time. TheAPIBook went to publishing May 4, 2008. The little manual is dated Jun 19, 2008..

--JaroslavTulach 13:50, 28 November 2009 (UTC)

[edit] Avoid Visitors. Unless you really know them.

Visitor pattern is one of the well known OOP patterns. However using it in an API is dangerous. At least unless you have read chapter 18 of TheAPIBook or studied my sample code.

--JaroslavTulach 08:59, 24 November 2009 (UTC)

[edit] Podcast: AOP is not dead. If you know how to use it!

Recently I saw the future of AOP. I thought one should say goodbye to AspectJ and its clones and get ready for ease of use that makes AOP wide spread! After few comments I know that it is enough to learn more advanced capabilities of AspectJ. But don't forget to do so, such flavor of AOP is much better than plain writing of aspects.

--JaroslavTulach 12:56, 21 November 2009 (UTC)

[edit] Screencast: Module System for Java

Module system is single, most important missing feature of Java. It is essential for the vitality of the Java system to define and agree on shared standard. On shared common ground. Recently me and Geertjan created a recording where we discuss why it is important to have it. We also demonstrate on the NetBeans and Mylyn synergy how such system would simplify our lives. If you have half an hour, listen to our screencast and join us with comments.

--JaroslavTulach 09:07, 27 October 2009 (UTC)

[edit] The End of MVC as We Know it

Geertjan literally forced me to record a screencast about DCI with him today. We did rehearsal over lunch and beer (quite lively and interactive). Then he drag me into the recording room and we did it (less interactive, but more serious and important).

Join us to learn why MVC days are over and you should switch to a new paradigm ready for the 21st century!

--JaroslavTulach 20:52, 22 September 2009 (UTC)

[edit] @Synchronized

Synchronization is getting more and more important in applications and libraries written these days. However synchronization is hard. The primitives available in Java (or other languages), are ... well, are primitive. Higher level abstractions are available, but still they don't guarantee completely deadlock prone system. This has all been discussed in Chapter 11, Runtime Aspects of APIs.

Java Monitors just aren't what they supposed to be (read why). Thus I am glad to see that the project Lombok's @Synchronized seems to successfully replace the synchronized keyword with annotation (vivat annotations!).

In the name of cluelessness of your Java API users, don't forget to prefer private locks to synchronized methods. Or switch to the beautiful @Synchronized annotation.

--JaroslavTulach 08:51, 7 September 2009 (UTC)

[edit] XML, Schema, SAX. @Annotations!

Some say that code completion with annotations is not big improvement. XML can have code completion too if we give XML Schema with it. I disagree! Anyone to comment on that?

--JaroslavTulach 10:35, 31 August 2009 (UTC)

[edit] Extend Inextensible!

Interfaces are not extensible. Learn how to extend them!

--JaroslavTulach 11:31, 19 August 2009 (UTC)

[edit] Try to Steal my Object!

Recently my cousin was teasing my mind with a question whether there is a way to make anything private in Javascript. I may be wrong, but I think there is: Is there anyone who can steal and modify my internal impl object?

--JaroslavTulach 04:35, 5 August 2009 (UTC)

[edit] Plug into Your Compiler! Optimize Your Framework by Generating Compile Time Caches.

Learn how to generate CompileTimeCaches with a little help of source-only annotations and their AnnotationProcessors.

--JaroslavTulach 14:08, 25 July 2009 (UTC)

[edit] Victims of Conceptual Surface

Do you know how to eliminate classes with too many dependencies like java.beans.Beans? You need to Sneak in Simplicity!

--JaroslavTulach 16:32, 22 June 2009 (UTC)

[edit] Splitting applet and beans via CodeInjection

I have a basic infrastructure to split the JDK which could be useful in your project as well. Also I managed to successfully split java.beans and java.applet packages.

--JaroslavTulach 12:39, 17 June 2009 (UTC)

[edit] Help me modularize JDK

Creating modular JDK while keeping compatibility with the existing monolithic one may be tricky. Will you help me find right way to do it?

--JaroslavTulach 20:14, 14 June 2009 (UTC)

[edit] Everyone is equal. Except Power Users.

Learn to design Privileged API suitable for power users of your library. Don't forget to listen to podcast #3.

--JaroslavTulach 17:01, 25 May 2009 (UTC)

[edit] Double Injection. Loosely Coupled SpringFramework.

I have just finished the bridge between Spring and Lookup (originally written by AndreiBadea) and prepared a demo application to demonstrate what it can be useful for.

--JaroslavTulach 04:43, 28 April 2009 (UTC)

[edit] Clear Definition of Version

Interfaces are absolutely perfect tool to achieve ClearDefinitionOfVersion. A curious reader question made me write the ClearDefinitionOfVersion page - many thanks for your talkback.

--JaroslavTulach 19:55, 24 April 2009 (UTC)

[edit] Lookup is Free!

Time to pickup cherries! Nobody can know what happens to NetBeans after the Sun/Oracle acquisition. Better to be ready for everything and save the NetBeans API pieces that make sense outside of the project boundaries. One of them is Lookup. I am proud to announce that Lookup has new home now: lookup.apidesign.org. Welcome the refugee and let me know if there is a way I could improve the library.

--JaroslavTulach 05:54, 21 April 2009 (UTC)

[edit] D2D: Factory instances are more flexible than factory classes

As part of Designers To Designers section on this website I seem to have a unique chance to introduce Factory instances are more flexible than factory classes article by (yet) unknown designer. Enjoy, talk back.

--JaroslavTulach 08:40, 18 April 2009 (UTC)

[edit] Can there Be Implement Only Interface?

Here is my answer to question that I got by parren.

--JaroslavTulach 18:20, 12 April 2009 (UTC)

[edit] Application Context in Ruby

Recently I've noticed a lot of activity in the apidesign.org wiki. Perfect. Inspite it is more posts than I can handle.

However I am thankful for all your comments and I hope this wiki can become a place for exchange of ideas between people interested in API design. For example, Steve Shapero added a note about his will to seek for Application Context implementation in Ruby. I personally cannot be really useful, as my knowledge of the Ruby language is quite basic, but maybe some of you will join Steve's effort.

PS: Let us know how it went. You know, I feel that Ruby's duck-typing and API contracts may not be mutually strengthening...

--JaroslavTulach 19:30, 11 April 2009 (UTC)

[edit] Get Rid of Multi-Meaning Classes

In the latest example related to modifiers, I'll explain how to achieve even more clarity than advocated by EliminateFuzzyModifiers essay. Today we are going to eliminate multi-meaning classes!

--JaroslavTulach 16:42, 1 April 2009 (UTC)

[edit] Eliminate Fuzzy Modifiers!

Time for new post about modifiers. My recent take on access modifiers generated quite a bit of interest. I've received a bunch of comments and I am thankful for all of them! I've learned about approaches taken by different languages, I've started to think about my future, but more importantly Arno Nyhm asked me to:

please show not only a bad example for the Factorial

but also a good solution for this implementation.

At your wish Arno! Enjoy (almost) real world example how to EliminateFuzzyModifiers! And let me know what you think.

--JaroslavTulach 20:50, 27 March 2009 (UTC)

[edit] Time to Fix Java Access Modifiers!

I have an open letter to designers of Java language for JDK7: Can you please make Java modifiers API-friendly?

--JaroslavTulach 22:14, 25 March 2009 (UTC)

[edit] Co-exist in Peace! Accept Alter Ego.

APIs age and from time to time they get into so bad state that they need an alternative reimplementation. At that time one has to face a dilemma: Keep BackwardCompatibility or break it and improve the API? As AlternativeBehaviour page explains there is no contradiction between these two. One can deliver improvements while retaining BackwardCompatibility. All that is needed to teach the API to accept its Alter Ego.

--JaroslavTulach 16:56, 16 February 2009 (UTC)

[edit] Beware Exposing Yourself to Public!

Erwin Vervaet asked me to provide an explanatory example:

I have a question regarding chapter 11, section "Pitfalls of Java Monitors".

Could you please provide an example illustrating the problem, where

subclasses interfere with the parent class's monitors?

It took me a while to expose that example, but here finally is my newest page talking about Pitfalls of Java Monitors.

--JaroslavTulach 10:15, 12 February 2009 (UTC)

[edit] Try, catch, and don't give up!

When your call to a method generates an exception, what can you do? Print warning and give up? Yes, often. Unless the TryCatchRedo pattern is in use!

--JaroslavTulach 15:29, 2 February 2009 (UTC)

[edit] Accept Unacceptable!

When you maintain some code and you get a patch that you do not like, what can you do? Is the only option to refuse the change, or is there a better way? Of course, as this was just a rhetorical question, there is better solution: Just create a code slot!

--JaroslavTulach 21:31, 10 January 2009 (UTC)

[edit] Singletonize your own Factories!

I am reading my own book and I've just got to page that talks about a pattern called among the NetBeans team Singletonizer. TheAPIBook describes it with a small note, but as I think it is very useful, I've just created a dedicated page describing it in more detail, giving it more, well deserved, publicity.

--JaroslavTulach 16:29, 25 December 2008 (UTC)

[edit] Wizard is the best API

There is a nice discussion provoked by description of my manifest advantures. It reminds me once again how important tools are. As I wrote somewhere in TheAPIBook, I guess it is in Chapter 9, one of the best APIs is wizard. Good wizard can turn any API, regardless how bad, into perfectly shining, beautiful star. Good tools make everything easier.

--JaroslavTulach 13:49, 19 December 2008 (UTC)

[edit] Builder vs. Cumulative Factory

Is Builder better pattern than CumulativeFactory? As Radim and Paulo pointed out, it might be. However from my point of view, it is an extension to the previous one! Read more and help us decide...

--JaroslavTulach 13:02, 15 November 2008 (UTC)

[edit] Cumulative Factory API Design Pattern

Dear API writers, let me introduce you to cumulative factory API Design Pattern. Read more...

--JaroslavTulach 15:38, 9 November 2008 (UTC)

[edit] How Many People Have to Die leakages

Recently I've been warned that my sidebar in Chapter 4, Ever Changing Targets talks about events that are completely ununderstandable for international readers. That made me write a short essay about leakages of cultural contexts and the similarities with the API Design.

--JaroslavTulach 05:01, 21 October 2008 (UTC)

[edit] Exceptions in API

Casper Bang asked following question about exceptions in API after reading the TheAPIBook:

I was curious as to know how come, in a book strictly about API design in Java, you do not mention exceptions (particular checked exceptions) and the role they play in documenting assertions vs. hampering versionability. Did you simply think this to be too controversial an issue I wonder?

Good question! Inspiring. Here are my current answers: exceptions in API.

--JaroslavTulach 21:37, 14 September 2008 (UTC)

[edit] Have You Ever Wondered?

Many people want to know, before they start to read a book, whether it can help them solve some problems they have faced. That is very likely reason why many books start with have you ever wondered sections. The Practical API Design book does not contain such section itself, however that in no way means that there it is not helping to solve problems! You can bet that there is a lot of useful advices! The book is a lab journal describing adventures of NetBeans project and as such, it is almost completely stuffed with problem solutions. Here is short online version of Have You Ever Wondered to demonstrate that. Visit the page and check yourself what problems can TheAPIBook solve for you!

--JaroslavTulach 20:42, 17 August 2008 (UTC)

[edit] Request/Response Pattern Revisited

Here is few additional thoughts about Request/Response which did not make it into TheAPIBook's explanation of Request/Response pattern.

--JaroslavTulach 21:02, 25 June 2008 (UTC)

[edit] Daily Life Blog

[edit] The Differences Make the Difference!

The flow of questions about the difference between Netbinox and Equinox does not seem to run dry. That is why I reorganized the Netbinox page to also describe the technical differences between those two OSGi containers.

The primary difference is that Netbinox is way faster for launching desktop applications than its up stream project. This is the positive difference. However together with this side of the story, one also gets the other one. The behaviour responsible for the speed up is also most likely the one to the deviate from the original's functionality.

The behaviour of Netbinox is deeply covered by tests, however that still does not guarantee it is completely identical. But be assured compatibility remains the biggest Netbinox goal. If you want some details, read more!

--JaroslavTulach 08:49, 26 August 2010 (UTC)

[edit] Use Hg! Don't Learn to Sing!

An old friend of mine asked me about my experience with Mercurial. Probably he wants to migrate his team to some good distributed versioning system. As I can't sing I can only recommend that. In case you are in similar situation: Use Hg!

--JaroslavTulach 09:33, 12 August 2010 (UTC)

[edit] Heavier than Air Can't Fly!

How it comes that Netbinox is faster than plain Equinox? Read here....

--JaroslavTulach 18:24, 4 August 2010 (UTC)

[edit] Creating Derby database via Ant

What database you can use in unit tests? I have chosen Derby. How do you automate creation, population and removal of such database? Using Ant! Great vision, however easier to outline than really do. It took me few days to merge Derby with Ant. In case you have similar need, read my small how to.

--JaroslavTulach 07:18, 17 July 2010 (UTC)

[edit] Rescue Sync: Recover Damaged Disks

Do you want to know how Rsync, the rescue sync, can be useful for recovering broken photo and video collections?

--JaroslavTulach 12:35, 29 June 2010 (UTC)

[edit] Upgrading to NetBeans Platform 6.9

I've just upgraded to DVBCentral to NetBeans Platform 6.9 in 10 minutes. Upgrade too!

--JaroslavTulach 20:17, 24 June 2010 (UTC)

[edit] NetBeans 6.9 Press Release: The Fastest OSGi Container!

Time to publish performance press release to join the overall enthusiasm about the latest NetBeans release! Enjoy NetBeans Platform 6.9!

--JaroslavTulach 10:22, 20 June 2010 (UTC)

[edit] OpenJDK is not Ready for Virtualized Environments!

Ever tried to use virtualization server and run Java in it? I tried. It is hard. Very hard. So hard it makes me wonder whether anyone else succeeded to use OpenJDK in such environment?

--JaroslavTulach 14:21, 14 June 2010 (UTC)

[edit] Joining the Social Networks

For a while I tried to ignore existence of so called social sites like facebook, delicious, etc. But increased publicity is always needed, so I decided to make linking to apidesign.org web pages easier. Starting today, you shall find links to your favorite social sites on bottom of each page. Use them as you are used to.

Btw. that leads me to a question: Is there anyone reading my blog who adds more than fifty (hundred, thousand) page references per year? As I have already mentioned I am new to this social world and I don't know what to expect.

--JaroslavTulach 20:15, 30 May 2010 (UTC)

[edit] DocBook to OpenDocument conversion

Anyone interested in Docbook to OpenDocument conversion? I have one to share.

--JaroslavTulach 07:28, 28 May 2010 (UTC)

[edit] There Can't be Bugs in Already Released APIs!

My recent experience as an active maintainer of some APIs made me describe the attributes of a proper API Patch. Join me in defining what it means good API Patch and help me improve my NetBeans APIs.

--JaroslavTulach 08:05, 18 April 2010 (UTC)

[edit] EMF Fans, Get Assimilated!

Last week I convinced Geertjan to demonstrate use of Eclipse Modeling Framework (commonly shortened as EMF) on top of NetBeans Platform. Geertjan succeeded and thus there is a time to celebrate. As Antonio puts it:

Congratulations on this! This is a very important achievement from my 
point of view. It opens a path to using a whole bunch of external stuff 
into NetBeans RCP Applications, and makes NetBeans RCP one of the most sensible ways 
to handle OSGi modules in an ordered way.
Eclipse users of the world: get ready to be assimilated! ;-)
Cheers,
Antonio

--JaroslavTulach 10:29, 22 March 2010 (UTC)

[edit] Swinging OSGi Emerges

Dear fans of Felix, Equinox and NetBeans.

Recently we faced a little bit of instability. First of all we did significant refactorings of the OSGi and NetBeans integration code. We wanted to polish the integration with NetBeans Runtime Container and abstract away any dependencies on individual OSGi containers. We are done and right now everything seems to be stable. See the family of Netigso related build jobs at our hudson builder. The other reason for instability was crash of my Internet connection. This is fixed now as well. You can connect the the builder again.

There is more good news. First of all the Netigso project has become part of NetBeans and will be available in 6.9M1 (thus I disabled the special Netigso job on my own builder, it is no longer necessary).

Second, I have improved the Netbinox IDE. It is now more stable (especially the equinox integration) and also includes brand new splash screen.

Enjoy! Test. Report bugs.

--JaroslavTulach 07:05, 7 February 2010 (UTC)

[edit] The More Languages You Know

Here is a little story about an old saying: The more languages you know, the more you are a programmer!. Or am I wrong? Is the saying different?

--JaroslavTulach 22:19, 21 January 2010 (UTC)

[edit] AST Transformations

What I envy Groovy users is Groovy's support for AST transformations. This is basically the same thing that project Lombok does to Java, however it is not just a set of few hardcoded annotations, it is general purpose system that allows everyone to easily define such annotations and their compile time AnnotationProcessors (read Groovy AST Transformation by Example for simple introduction).

Will Java ever woke up from its last two/three years stagnation?

--JaroslavTulach 05:25, 11 January 2010 (UTC)

[edit] Welcome in NetBeans 6.8!

Let me (with a little bit of delay, as the release happened on Dec 10, 2009) describe the performance improvements we delivered as part of NetBeans 6.8. Please also note that we almost managed to provide what we originally promised half a year ago. That is not bad.

Also notice the power of working backwards methodology. Writing press release before starting the real work (as advocated in Teamwork chapter of TheAPIBook) provides almost perfect self perspective mirror. I guess it is time to write press release for NetBeans 6.9!

Happy new year and welcome to performance team!

--JaroslavTulach 07:21, 3 January 2010 (UTC)

[edit] Lookup is Free II

On Dec 20, 2009 I have integrated a separation of Lookup into NetBeans sources. Now the Lookup is really free. Not only there is a free fork, but the Lookup is really free in its original form. Enjoy!

--JaroslavTulach 07:20, 24 December 2009 (UTC)

[edit] Managing Dependencies on large projects

I have always known that managing dependencies is an interesting topic. Thus I was glad to reply to Craig Marshall's questions asked on Dec 9, 2009:

I would be interested to hear peoples experience around procedures for
managing and communicating changes around module dependencies, either in
the Netbeans RCP / IDE development itself or other projects sitting on
top of it.
What do people find works well between teams in a distributed
environment (Documentation, Diagrams, Wiki's, Meetings)?

Nice question, why not do shameless self promotion plug (if you don't commend yourself, who's going to?) and offer TheAPIBook? Thus I provided short answer: The important thing is to prevent unwanted changes. For that we have sigtest and golden files. Then we have the API review process to agree and approve intended changes. I have written a book (also) about this process.

Enough I thought. Self promotion stinks. But you would not believe what happened after that. Tom Wheeler sent a reply going even further:

I cannot recommend Jaroslav's API Design book enough for a very
thorough coverage of these topics.  IMHO, it's not just applicable to
NetBeans Platform or even Java developers -- this is essential reading
for anyone who wants to learn how to design robust APIs upon which
others can rely.

The only thing I will add is that in addition to the resources he
mentioned, you should also note that NetBeans' javadoc contains a list
of all API changes between any release and its predecessor.  You can
see an example of this by following the "Changes since previous
release" link on the main content frame here:

   http://bits.netbeans.org/dev/javadoc/

Perfect and that was not the end. Fabrizio Giudici added his:

+1

Thanks you guys and for everyone else: It is the gift time, make your friends blessed by giving them a copy of the Practical API Desing book.

--JaroslavTulach 20:04, 12 December 2009 (UTC)

[edit] Featuring NetBeans 6.9 - AutoUpdate Ant Task

Let me tell you something about new synergy between AutoUpdate and Ant.

NetBeans 6.8 is almost out of the door and it is the right time to think about improvements for NetBeans 6.9. One of the painful tasks everyone has to deal with is (headless) setup of NetBeans platform. The painful days are over! There is a new netbeans:AutoUpdateTask API for you.

With simple syntax and just with plain Ant one can prepare own, personal and tailored NetBeans platform. This is probably only useful for Ant users, fans of Maven will prefer to deal with its own repository, but still: netbeans:NBM format has been in use since the end of last century and it is good it is now easily reusable via Ant.

Read more about the netbeans:AutoUpdateTask. Will you find it useful?

--JaroslavTulach 13:42, 8 December 2009 (UTC)

[edit] Santa was here

First and foremost: Christmas time is getting closer. Do you know a lonely and sad programmer? Do you want to make your friend happier? The Practical API Design book is the best present. A pleasure for everyone!

In the other news: On evening of Dec 5, Santa visited us. At least I hope using the name Santa is the best translation. The official name is Saint Nicholas, but as the rumor has it, he was used as role model for English speaking countries Santa Claus:

Watch video on youtube.

He brought no books, just two devils, one angel and a lot of candies. He left the candies and took his stuff home together with our children's promise to be good for ever (in reality they managed to behave good at least for the one evening).

If you are still waiting for Santa's visit, ask him to bring you the practical book that shall not be missing in any library!

--JaroslavTulach 09:56, 7 December 2009 (UTC)

[edit] The Da Vinci Closures

Recently there was a lot of buzz around closures. Let me contribute to it with a proposal how to implement closures in an effective way. Let me also surround the technical topic by some The Da Vinci Code-like speculations.

--JaroslavTulach 11:34, 1 December 2009 (UTC)

[edit] Naked MVC

Few people added comments to my recently created page about MVC. Are naked objects MVC? What do you think? With the risk of starting a wikiwar, I'd like to invite you to join us and add new insights into the never-ending search for an ideal interpretation of MVC.

--JaroslavTulach 09:47, 10 November 2009 (UTC)

[edit] Want to become Agile?

Have you ever wanted to practice an Agile development in a group of more than twenty people? Did it work well? NetBeans team (few tens of people) designs the NetBeans interfaces in Agile way. Do you want to know how's that possible? Read more...

--JaroslavTulach 11:45, 9 November 2009 (UTC)

[edit] Can Swing be called MVC framework?

What do you know about MVC? Is Swing following the MVC paradigm or not? Let me take you through short, incomplete and mostly wrong history of MVC and decide yourself!

--JaroslavTulach 15:47, 4 November 2009 (UTC)

[edit] Ten Years

I am not sure if you know, but today, on Oct 20, 2009, is 10th anniversary of Sun's NetBeans acquisition. Read ten years old press release and enjoy while you can! Also don't forget to buy TheAPIBook, so you can learn and benefit from our ten year's experience (and I have more reasons to celebrate).

--JaroslavTulach 06:01, 20 October 2009 (UTC)

[edit] Can Equinox be called an OSGi framework?

Alex Blewitt commented on my recent Equinox experience saying that: Equinox is an OSGi framework, as it passes the OSGi TCK, without which it couldn't be called an OSGi framework. A little quiz now: Can or cannot the Equinox be called an OSGi framework? Cast your vote!

--JaroslavTulach 11:13, 12 October 2009 (UTC)

[edit] Is there any sense in producing non-GPL libraries?

We all know that open source rules. We also know that many open source project have problems with donations. Luckily there is a way out of the sponsoring misery. Looks like RMS was right!

--JaroslavTulach 11:42, 7 October 2009 (UTC)

[edit] Equinox is not an OSGi Container!

Give people a finger, they will ask for whole hand! I gave every OSGi lover Netigso (based on Felix) and guess what many said! We don't want Felix, we want equinox! What could I do? I started to look at Equinox last week and I have a discovery to reveal: Equinox is not an OSGi container! Read why...

--JaroslavTulach 20:03, 4 October 2009 (UTC)

[edit] Battle of Titans: DCI vs. Dependency Injection

Andreas asked an interesting question: Is in DCI still a need for dependency injection? What would be your answer? Same as mine?

--JaroslavTulach 11:47, 26 September 2009 (UTC)

[edit] Is Maven Ready for Desktop?

Is Maven matured enough to help us develop Java desktop applications? Hear my Maven complains and blessings. Help me lower my suffering.

--JaroslavTulach 19:26, 13 September 2009 (UTC)

[edit] Video Processing in Java. Good Tools Matter.

Today I generated my first movie. I really mean generated, not captured. I wrote my JPanel subclass and with help of various technologies I managed to convert it into .avi file. Read more about my First Amoeba Video and don't be afraid to share your experiences with video processing in Java.

--JaroslavTulach 16:55, 22 August 2009 (UTC)

[edit] Torrented Again!

From time to time I search the Internet to see whether there are some new reactions to my book. Yesterday I searched again and to my surprise I found a torrent of the Practical API Design book. Somebody had to think the text is so valuable that it shall be shared!

So now I am in the same group as musicians and movie stars, my work is being copied! Illegally and without any royalties, but still it makes me proud. Is there anything better for a book author than knowing that his book is read by someone?

For the first time in my life I could use the torrent client without violating anyone else rights. Of course one gets just electronic version and thus it cannot replace the feeling of holding real book in hands. Also it cannot be signed by the author. That is obviously essential drawback. That is why I still recommend to order via amazon and/or stopping by to get written dedication.

Enjoy API Design!

--JaroslavTulach 14:37, 16 August 2009 (UTC)

[edit] Scala can't be so bad!

My recent rant about the missing slickness of Scala's core libraries finally provoked a reaction. Thanks Landei for speaking up. I know there no black&white in the real world, but your explanation of Scala's "flexibility" could be extrapolated to a false (at least in my opinion) feeling that Scala is not yet ready for real production use.

--JaroslavTulach 08:30, 12 August 2009 (UTC)

[edit] Sigtest for C/C++

An anonymous coward just provided a link to signature testing tool for C and C++. Good to see the set of API tools to expand beyond the Java world.

--JaroslavTulach 19:18, 9 August 2009 (UTC)

[edit] Welcome to Performance Team!

Another NetBeans release cycle is in progress and it is time to write future press release (as advocated in Chapter 16, Convincing developers to document their API). Take a look so you know what to expect as soon as NetBeans 6.8 is out!

--JaroslavTulach 15:53, 16 July 2009 (UTC)

[edit] Speed Your Application Up

Here is description of a class loading cache that has potential to drastically speed up start of any application composed of many JAR files. See its benefits on your own and learn to use them in your applications!

--JaroslavTulach 14:35, 14 July 2009 (UTC)

[edit] Press Release: NetBeans 6.7

Are engineers capable to produce a press release? Possibly, however as explained in Chapter 14, it needs to be written before the coding starts. Read what we have written six months ago and celebrate with us NetBeans 6.7!

--JaroslavTulach 10:09, 7 July 2009 (UTC)

[edit] API Podcast #5: Can you win?

Here is another podcast recorded to explain importance of playing games while learning to design APIs. Ask yourself today: Can you win an API Fest with a change like this?

--JaroslavTulach 09:37, 2 July 2009 (UTC)

[edit] XML SAX and DOM 2

Few years ago our meta modeling gurus submitted a proposal for JavaOne BOF named XML SAX and DOM 2. They wanted to describe NetBeans MOF solution and show how good it is compared to standard XML tools. I always admired the name of the talk (as the JavaOne was dedicated to show the synergy between XML and Java it obviously was rejected) and I am glad I have a chance to use the title today too: I just managed to remove XML from Java.

--JaroslavTulach 09:56, 26 June 2009 (UTC)

[edit] Building the Modular Java SE

Modular Java SE has its own Hudson Builder - check the first artifacts: base.jar, applet.jar, corba.jar, deprecated7.jar...

--JaroslavTulach 21:23, 21 June 2009 (UTC)

[edit] Aliens vs. Predators. Bridge between OSGi and NetBeans.

Many said this was impossible. Many said this would be crazy. Many said it cannot work. However it does work like a charm. I am glad to announce that I have a well working OSGiAndNetBeans bridge and I am ready to build community around it.

--JaroslavTulach 10:35, 2 June 2009 (UTC)

[edit] API Podcast #4: Diamonds vs. Stars

Do you want to know why core Java people believe APIs are like diamonds? Enjoy this API Design Tips podcast at least as much as we enjoyed it while recording it with Geertjan!

--JaroslavTulach 20:43, 31 May 2009 (UTC)

[edit] Scala Libraries Rant

I've been asked by a colleague what I think about Scala. I think I like it, but...

--JaroslavTulach 15:04, 28 May 2009 (UTC)

[edit] API Podcast #2: Reentrancy

[edit] API PodCast #1

[edit] Mercurial vs. Subversion. Correctness vs. Simplicity.

I have dedicated one side note in the Practical API Design book to Mercurial_vs._Subversion comparison. Last week I received a comment from TheAPIBook's reader claiming that the Mercurial and Subversion behaves the same in this particular respect. So I needed to run an experiment. They are not same at all! One is correct, the second is simple to use. Which one is better?

--JaroslavTulach 16:29, 5 April 2009 (UTC)

[edit] Colors that You Like

Some of you asked for Black on White colors for this website. Now you can have them: Find Black/White symbol in the left navigation bar to make temporary switch or log in an choose your preferred skin in your preferences.

--JaroslavTulach 11:23, 4 April 2009 (UTC)

[edit] What's your big brother's name? AOP!?

Do you control complexity of your application? What tool do you use? Something homemade, something bought or something general like AOP?

--JaroslavTulach 10:03, 22 March 2009 (UTC)

[edit] sigtest 2.1 released!

The new version of the absolutely necessary tool for executing SignatureTests has just been released. Enjoy!

--JaroslavTulach 19:37, 17 March 2009 (UTC)

[edit] Extreme API Fest

Petr Šmíd just finished his API Fest game for HP Prague developers. I really enjoyed observing the players and I have to admit I learned few tricks myself. Read more about the HPAPIFest09!

--JaroslavTulach 20:43, 9 March 2009 (UTC)

[edit] The Definitive Guide to API Design

I have to mention that I've been pointed to another review of the Practical API Design book. Very nice read, I was pleased to hear the book was useful. But then, I got to the comments section. Well, that did not feel pleasant anymore. For a while I was searching for a rope and a tree to hung and lynch myself.

However after thinking about it for a bit more, I believe that I do not need to persecute myself for writing the book. I knew the book is not complete, I knew its selection of topics is subjective and related to my own experience (hence the word Practical in the title), yet the book is still more useful out than kept just in my head and notes.

Update from March 7, 2009:

and really do want the next "Principia". It should have been the

next "Design Patterns" book, something to really love. So admittedly

I had too high of an expectation.

The later comments made me feel a bit better and the one quoted above reminded me of a story related to the book's publication. My publisher's favorite title of the book was Definitive Guide to API Design. It took me quite a lot arguing and I even needed to meet Apress boss, Dominic, to change their mind. My book can be attributed with various adjectives, but it is not definitive at all. Take this note to correct your expectations. Don't expect definitive answers to everything related to API design. Expect that your horizons in the API world will be enlarged and many things will be more clearly recognizable. But many questions will remain.

I have to repeat the theme of the epilogue: The exploration of the API world is just starting. If you have something to say about API design and you are not afraid to contribute to a wiki, feel free to join the wiki.apidesign.org. If you have ideas about various APITypes or APIDesignPatterns or related topics don't let them be buried in Blogs, put them into wiki - wikis are like stars, they are forever. Almost.

--JaroslavTulach 20:12, 7 March 2009 (UTC)

[edit] Tell me your name! I'll tell you how good designer you can be!

Well, not really. But Good Names are important. Here is little video to prove that.

--JaroslavTulach 14:15, 26 January 2009 (UTC)

[edit] Painful Reading Days are Over!

If you ever suffered while reading files in Java, please accept my sympathy and enjoy the recently proposed NetBeans API improvements.

--JaroslavTulach 18:11, 23 January 2009 (UTC)

[edit] PF 2009: Get on Board!

Dear readers of my book and my blog, I've mentioned in Epilogue of TheAPIBook that I good tools can help anyone do better job. I backed my reasoning by a skiing parallel. Recently I found an old video to explain what I really meant. Thanks for your interest in API Design and I wish you good tools in 2009 to help you get on the board!

--JaroslavTulach 14:20, 29 December 2008 (UTC)

[edit] Did OSGi Comrades Make a Mistake?

Many systems store their configuration in some form of property files. However a lot of them is not doing that really properly. The results can then be quite painful. Just like when I recently played with OSGi manifest files. Read my story and feel my pain...

--JaroslavTulach 12:36, 16 December 2008 (UTC)

[edit] 2009: The Year of Annotations

As I noted recently, I see the year 2009 as the year of annotations. The NetBeans project is about to rely on them more heavily. Finally! We've been waiting for that for ages, but finally we can compile with JDK 1.6 JavaC and we can use compile time annotation processors. As a result we can replace our layer based registrations with annotations and benefit from compile type checking, code completion, from having the registrations in the same place as the code that is being registered, etc. Also we can offer our API users simple looking annotations and let associated annotation processors do more advanced and more effective processing. As a result the developers have simple API to deal with, while actual registration hidden behind can be as effective as possible, even at the cost of complexity, but without compromises to reliability (as the complexity is kept in the processing infrastructure, not exposed to API users).

The other project related to annotations that we are likely to incorporate during 2009 is our extended use of Annotations for Software Defect Detection. This is heavily based on the JSR 305, yet until it is stable we do not want to expose such unstable API to users of our stable APIs (more on that in Chapter 10, in section Beware of Using Other APIs). As such we are going to create our own annotations (still recognizable by FindBugs and co.). The hope is that our annotation will stay compatible even if the underlaying JSR 305 slightly changes. Please find our current patch and comment here or in the issue 137437.

Last project that deals with annotations is developed by our editor hints guru Jan Lahoda - its aim is to bring complex refactoring to masses! How? Why? We have observed that using @Deprecated annotation is good hint to help your API users recognize that some part of your API is obsolete and shall no longer be used, however that in no way helps users of your API with converting their code to new, non-deprecated style. We have a solution: Use Code Transformation Annotations! Dear [API] writers, let's adopt these annotations and use them in your API! They are completely standalone (read more), lightweight and we are ready to incorporate feedback of everyone interested in the project. Indeed, my plan is to bring these easy to use and flexible refactorings to NetBeans soon, hopefully for version 7.0.

So these are my three annotation related projects. I find them quite exciting and I cannot wait to see them being used. Annotations are here to simplify life of API users and developers. As soon as we have them, we will have full right to call the year 2009 the year of annotations!

--JaroslavTulach 09:06, 12 December 2008 (UTC)

[edit] See APIFest08 winners photos!

See the winners and sponsors of the game on the pictures taken by Jan Chalupa.

--JaroslavTulach 16:10, 31 October 2008 (UTC)

[edit] NetBeans 6.5 Performance Press Release

How can one announce to the world that something important happened? Via Press Release, of course! However, one question stays: who can write good press release? Engineers are generally seen as incapable of doing so, however as argued in Chapter 14, Paradoxes of API Design, there is a way to help them: Force them to write documentation or press release before they start to code!

This is the Press Release of the [NetBeans] performance team written six months ago. Now, when the release of [NetBeans] IDE 6.5 is near, it is time to publish it. Feel free to read what we planed and what we delivered!

--JaroslavTulach 14:47, 30 October 2008 (UTC)

[edit] Jan Žák and Petr Šmíd are winners of APIFest08

It is time to announce results of APIFest'08.

--JaroslavTulach 11:44, 26 October 2008 (UTC)

[edit] Petr Šmíd's Thanks

I would like to thank you very much for organizing the competition.

Unlike all other programming competitions which are focused on creating algorithms this one is unique, because it focuses on another type of problems which more reflects real challenges that programmers deals with.

I can personally say that I learned many lessons about API design and I think this is the case of everyone who joined this event.

That's why I can suggest everybody to join this event next time. It was well prepared and the idea of the competition is really great.

So thank You Jaroslav and all guys which are behind the event!

--Petr.smid 13:00, 29 October 2008 (UTC)

[edit] The Most Insightful Review of "Practical API Design"

The longest, most detailed and insightful review I have seen so far has been written by Tim Band for Lambda The Ultimate.

--JaroslavTulach 11:27, 24 October 2008 (UTC)

[edit] APIFest08 Judgment Day/Week Starts!

The judgment day is here! Dear APIFest08 participants, during the last rounds, you were concentrated on making your own solution perfect. However since today you will have to stop looking just at your own solution, you will need to start digging in solutions provided by others to find possible evolution mistakes. This is a new task, different to what you have done so far, but I hope you'll make it. Because only if you find mistakes in solutions provided by others you will be allowed to win TheAPIBook.

If your own solution is found backward compatible and it successfully passed the 4th round, you'll be awarded with 10 points. By default you all have those points. However you can be awarded with 1 point by showing compatibility problems in each solution provided by someone else, who advanced to 4th round. Of course, in case somebody finds such problem, the author of the solution looses own 10 points. As I wrote in the last post, I know that at least five solutions have some problems, so do not give up and seek for them! Your points are waiting! Also please note that the fact that I may know about a problem of your solutions does not mean other participants are going to find it. Don't give up and good luck!

First of all you need to setup your working environment:

# create the repository
hg clone http://source.apidesign.org/hg/apifest08/
# or update it
hg pull; hg update
# create directory named by you Joe Hacker would have:
mkdir taskx/jhacker

and now your hunt can start. Repeat following tasks as many times you wish. First of all somehow select the solution you want to find problem in. Usually I use a diff:

diff -ru task2/solution03 task3/solution03

Each difference is potential candidate for compatibility problem. It is just necessary to write code against the old API that does something different in the new version. If I notice some potential evolution problem, then I setup the against project and write a test into it to show the error:

# select the solution you want to break, let supposed it is #3:
hg copy taskx/jtulach/against-solutionXY/ taskx/jhacker/against-solution03
# now open some of the created files in your favorite editor:
netbeans --open taskx/jhacker/against-solution03/project.properties

Now adjust the content of the properties file:

# change definition of apitotest property to solution03:
apitotest=solution03
# you can also adjust the taskA and taskB variables to 
# reflect the days that you want to compete against
# for example if there is compatibility problem between
# task2 and task3, change them to:
taskA=${apifest}/task2
taskB=${apifest}/task3

Now you can open the project in the NetBeans IDE

netbeans --open taskx/jhacker/against-solution03/

or directly edit its jhacker/against-solution03/test/apifest/CurrencyTest.java file. The goal is to make this file compilable against api available in the version taskA. If you execute the project:

ant -f taskx/jhacker/against-solution03/build.xml run

or by pressing F6 in the NetBeans IDE, your test is compiled, executed against taskA and it has to succeed. If it does, the test is executed against taskB library. If it fails, you have demonstrated BackwardCompatibility problem and that is why the build succeeds. Make sure you open the Output Window to see the real resul! There is also the JUnit Result Window and it is not really helpful in the against project, but I do not know how to suppress its appearance. If the test succeeds with taskB library, the sources of your test are compiled once again against taskB library. This can fail, if there are source incompatibilities. Failure means your success, as you have demonstrated an incompatibility! To see result of these steps in action, look at my attack against solution02 (I can show it as it did not advanced into this final task and you cannot be awarded with points by finding problems in it). If you managed to attack one solution, perfect, you can repeat these steps for another one.

The rules for writing compatibility tests are similar to API Fest One - e.g. the less tricks you use the better. Where trick means more or less Java Permission. Do not try to use reflection that could obviously break each solution. Also do not use wildcard imports in source, that can easily break each solution as well. Do not put the code into the API package, that would allow you to use package private methods and would be unfair. Rules are simple: less tricks is better and I am the judge. Enjoy!

After you are done, please generate the diff using hg diff and submit your solutions by Sun, Oct 26, 2008, morning of CET to our mailing list. Possibly you can ZIP your sources and send them to us too. As soon as we process your submissions, I'll write an APIFest08 report and announce winners. Also I will prepare TheAPIBook for the winner.

--JaroslavTulach 06:03, 18 October 2008 (UTC)

[edit] APIFest08 Task 4 Necessary to Choose the Best API Designer

It is unbelievable! We are approaching task4 of APIFest08 and we still have eight participants who play with us! Moreover the competition is still not decided, as far as I can tell. Today I spent few hours looking for BackwardCompatibility problems in provided solutions and I still have not managed to break three of them! It is not that surprising as some of the competitors follow advices of TheAPIBook. For example I've seen APIDesignPatterns:ResponseReply being used. Guys, how can I find a quest for you if you know all the good tricks? Anyway this means we have to go on, as I have only two books to give to winners!

That is why let me ask call round4: Please integrate with dates. Keep history of conversions, allow queries in historical data, etc. Please see Task4Test.java with the actual quests.

Locate your solution among existing task4 directory. There shall already be Task4Test.java file along your Task1Test.java, Task2Test.java and Task3Test.java. Enhance your API, show its usage in the Task4Test.java. Remove the conditional if failing statements.

After you are done, please generate a diff. The best way is to use Mercurial:

# create the repository
hg clone http://source.apidesign.org/hg/apifest08/
# or update it
hg pull; hg update
# then do your modifications
# ...
# do not forget to add newly created files
hg add task4/solutionXY
# and finally produce a diff
hg diff

you can obtain the diff in other ways, potentially you can send us to our mailing list the whole ZIP file, but diffs are preferred.

Please submit your solutions by Thu, Oct 16, 2008, morning of CET. I guess this is the last coding round. On Saturday you will start hacking solutions provided by others!

--JaroslavTulach 22:17, 11 October 2008 (UTC)

[edit] Define "Friday Morning"

When I was defining the quest of APIFest08:Task3 I needed to set a deadline. However as the APIFest08 is not competition for millions of bucks, just for TheAPIBook, I did not feel I need to be exact enough and I defined the deadline as Fri, Oct 10, 2008, morning of CET. This is the reaction that I got from one of the participants:

I really like the precision you use in specifying the deadlines!
I will choose to interpret "Fri, Oct 10, 2008, morning of CET" as 
the time when  the first ray of the rising sun can be seen from 
the train I'll be taking to commute to Prague unless the window 
is too dirty, is that o.k.? :-)

Cute and OK. Of course only under the assumption that you do your best to clean or at least open your window in case it is too dirty and that you are not referring to a window of an underground train.

--JaroslavTulach 07:53, 8 October 2008 (UTC)

[edit] APIFest08 task3 is here

The task3 of APIFest08 is here to tease you more, dear participants. Btw. great work on the previous tasks! It is really hard for me to come up with a task that will be unimplementable for you. I guess you all defend BackwardCompatibility of your solutions pretty well.

Let see what will happen during the round3. I have prepared the Task3Test.java for you. Please enhance your API to allow your API users to write online convertor that updates its exchange rates all the time. Please find the details of your quest inside of the Task3Test.java file.

Locate your solution among existing task3 directory. There shall already be Task3Test.java file along your Task1Test.java and Task2Test.java. Enhance your API, show its usage in the Task3Test.java.

After you are done, please generate a diff. The best way is to use Mercurial:

# create the repository
hg clone http://source.apidesign.org/hg/apifest08/
# or update it
hg pull; hg update
# then do your modifications
# ...
# do not forget to add newly created files
hg add task3/solutionXY
# and finally produce a diff
hg diff

you can obtain the diff in other ways, potentially you can send us to our mailing list the whole ZIP file, but diffs are preferred.

Please submit your solutions by Fri, Oct 10, 2008, morning of CET, so we can process your submission before weekend and think about more sophisticated ways to tease you. Good luck!

--JaroslavTulach 09:27, 7 October 2008 (UTC)

[edit] New Code for Food Picture

The spirit of HtmlForFood story lives on! Geertjan did a NetBeans platform training recently and it seems he learned new skills, which include ability to debug and generate code:

--JaroslavTulach 14:58, 6 October 2008 (UTC)

[edit] APIFest08 task2 is here

The task2 of APIFest08 is here. We have fourteen solutions that advanced to second round. Some of them did use their chance to get up to speed in APIFest08:Task1.5, some of them did not. The latter ones will be in tougher position, as the second round is just about to start.

You task #2 is to allow one convertor to hold multiple rates of multiple currencies. Also, create an API to allow composition of convertors. Here is the Task2Test.java file with detailed description of the quest. Locate your solution among existing task2 directory, copy the Task2Test.java file along your Task1Test.java. Enhance your API, show its usage in the Task2Test.java.

After you are done, please generate a diff. The best way is to use Mercurial:

# create the repository
hg clone http://source.apidesign.org/hg/apifest08/
# or update it
hg pull; hg update
# copy the task 2 file
hg copy currency/test/org/apidesign/apifest08/test/Task2Test.java task2/solutionXY/test/org/apidesign/apifest08/test/Task2Test.java
# then do your modifications
# ...
# and finally produce a diff
hg diff

you can obtain the diff in other ways, potentially you can send us to our mailing list the whole ZIP file, but we want to have the right to process diffs first, as that is simpler for us.

Please submit your solutions by Sat, Oct 4, 2008. Good luck, and do not forget to keep BackwardCompatibility!

--JaroslavTulach 11:50, 1 October 2008 (UTC)

[edit] APIFest08's task one and half

Thanks you all, dear twelve brave men for participating in APIFest08! I was really glad to see your submissions after the task 1. I really like the variety between your individual solutions.

However, I also have to apologize. I did try, to correctly specify the task 1 goals, however, looking at some of your solutions, I failed. Some of your APIs do not satisfy all the use cases that I had in my mind. That is my fault, I should have expressed myself clearly. Anyway it puts us into bad situation. Now you are not at the same starting position for the real APIFest08 game. That is why I have to, like a starter seeing a problem before 100m run, call off the ready state, and ask you to prepare once more. That is why I am calling round one and half. Please adjust your your solution according to additional tasks, described in Task1Test.java. There is proper description of the behaviour of the factory methods and two more tests. Please implement this in your solutions.

Please do it by Tue, Sep 30, 2008, noon. You do not need to retain any backward compatibility yet, however restrain yourself from doing too big changes to your APIs, they are all good, just satisfy the additional use cases, please.

Please accept my apology, and good luck!

--JaroslavTulach 18:24, 28 September 2008 (UTC)

[edit] Ezekiel 25:17

"The path of the righteous man is beset on all sides by the inequities of the selfish and the tyranny of evil men..."

At certain moment, some ideas get "indexed". Such ideas get a single name, single label and it is enough to say just that name and the right rings are going to bell in heads of all listeners. You do not need to repeat the whole joke, it may be enough to say just the name of the main character in it. You may not repeat the whole story, it is enough to say "life is like a box of chocolate, you never know what you gonna get" and it is clear what is the story about. Or, just refer to "Ezekiel 25:17" and you can bet that most of your listeners will know what you are referring to. These sentences became "indexes" for their whole stories.

The trap that every author of a book shall be aware to not fall into is to become a generator of indexes for his own books. This is inevitable, at the end the author spend last few months reading again and again the same book. Reading own sentences over and over, changing words to make them better, more expressive, more sharp and exact. It is natural that for the author to see nothing more real than the book and its content. It is easy to fall in the trap of believing that this is so also for every other human being one meets.

As a result authors sometimes use sentences like "should you read the xyz book, you would know that...". Or refer to their work using "I have described uvw in Chapter 33, please read it". This is explainable, yet very annoying. I've faced that behavior once and I was quite up set and I knew I should restrain from doing the same after publishing TheAPIBook. I knew that, but I could not stop myself from doing that! It was so tempting to refer to chapter 11, Runtime Aspects of APIs instead of explaining that getting ready for reentrant calls is important. It was so easy and tempting, yet it was also quite annoying for people around me. At least that is my guess from seeing their unusual reactions to my speech or email in not so recent weeks.

Please take this as my public apology for using Jarda 15:13 or Jarda 7:3, etc. "indexes". I could always understand how it feels to get such self-reference. Sorry for that and I promise not to use it anymore.

PS: In case of need refer to this text as Jarda 24:9.

--JaroslavTulach 19:43, 24 September 2008 (UTC)

[edit] API Fest '08

The APIFest08, a game to practice Practical API Design skills, is just starting. It is a contest primarily designed for members of Czech JUG, but we want to make it as open as possible. Play with us and celebrate 10th anniversary of first public NetBeans release.

--JaroslavTulach 09:31, 23 September 2008 (UTC)

[edit] And the Winner of the HtmlForFoodCompetition is ...

Let me announce the winner of the HtmlForFoodCompetition.

--JaroslavTulach 20:25, 8 September 2008 (UTC)

[edit] First Public Review of Practical API Design Book

There is a review of TheAPIBook! Geertjan had just sent me a link to the first public review of the TheAPIBook. I was a bit nervous to open the page. I was not sure whether to get ready for absolute criticism or words expressing usefulness of TheAPIBook. I guess that a review which says this is without a doubt a book that you need to put on your bookshelf. This is the first book of its kind and the tips and tricks that it provides is timeless - a key attribute of any pragmatic software development book can only be seen in positive light. Thanks for the nice review, Mike.

Now on to the critical comments. Yes, I know the first part of the book, the theory, maybe seen as something delaying the real pleasure - the practical code samples. In some sense it does, however I just felt that given the wide audience of readers (just to quote the reviewer this book is really much more for anyone who writes code that anyone else consumes - and who doesn’t do that? This book is for any developer who is not brand new to software development), I felt the need to get everyone on the speed, clean up the terminology, make sure we understand each other. Maybe I was too careful, as RichUnger said: you do not need your readers to agree with you 100%, maybe 99% is enough. Well, I targeted for the 100%, and as a result, the book may be seen slow for those who are already on the same boat. Still, it has a lot of meat even for such readers, I guess.

The other interesting comment was about the subtitle: confessions. The comment is very likely true. I have to admit, especially after the confession I made at the end of Chapter 4, that I have never been to a confession. My understanding of that term is really vague. However, we needed the subtitle to stress, that the book is not opinion neutral, that it contains personal experiences, ideas, stories, etc. When Clay suggested to use confessions, I felt, yes, that is sort of what I am actually doing. Maybe this is not absolutely correct, but it helps set the right expectations up. At least I hope.

I really like Mike saying: After reading many chapters, I went right to my open source project, Architecture Rules, and either changed code or emailed developer mailing list to suggest changes to code to encourage a better, more malleable and extensible API. Yes, this is it! This is the reason why I wrote TheAPIBook. Software for 21st century needs to be modular, needs to be well evolved and I am glad that my book can contribute to that.

Thanks for such nice review and I am eagerly waiting to see more. Btw. if you ever feel you have a note to share about API Design, feel free to jump on the apidesign.org wiki.

--JaroslavTulach 19:42, 2 September 2008 (UTC)

[edit] Win the Practical API Design Book

As part of Chapter 1, The Art of Building Modern Software I wanted to demonstrate that the need for programmers is really big and that almost everyone who wants to get a job as a programmer may get it. For this I wanted to reuse a picture of a San Francisco homeless that is famous for wearing sign with "Will Code HTML for Food". However I could not do that, because the picture is of really low quality. That is why I needed a new re-take. We already have some, but still, I'd like us to start sharing! As sharing of pictures is sometimes easier than sharing of API Design ideas, please participate in a photo contest! Get a chance to win TheAPIBook by taking "Will Code HTML for Food" like picture and adding a reference to it to HtmlForFood by Aug 28, 2008! I am looking forward your submissions.

--JaroslavTulach 16:11, 14 August 2008 (UTC)

[edit] New LaF of apidesign.org

The websiste has new look and feel.

--JaroslavTulach 10:09, 4 August 2008 (UTC)

[edit] There is a Reason Why Every Book is Dedicated to Family

I've heard this sentence at the J1 this year and I cannot get it out of my mind. Yes, family plays a really big role in the life of a writer. So please let me thank to it as well to other friends.

--JaroslavTulach 19:00, 27 July 2008 (UTC)

[edit] Good Book Needs Good Reviewers

It is time to thank to all my reviewers as today I've found out that you can order my book on Amazon.com. Please look at my little ThanksReviewers to find out why to order my book. I believe that all reviewers really shape it to something worth reading. Thanks a lot.

--JaroslavTulach 19:44, 18 July 2008 (UTC)

[edit] Removing Fear of Writing Documentation

Heuréka! As I've just noted in a dedicated page describing chapter 16, Teamwork one GeertjanWielenga's fear has just been overcome!

--JaroslavTulach 16:05, 17 July 2008 (UTC)

[edit] Adventures with PHP and MediaWiki

During the last week, I was slightly playing with various enhancements to the content of the API Design wiki.

--JaroslavTulach 21:14, 6 July 2008 (UTC)

[edit] Book is never Written by a Single Person

The Practical API Design book has been sent for print over the last weekend. I take it as a good opportunity to say thanks to all the people who helped me write it. The first set of ThanksEveryone notes is now available and covers those who "manually" contributed. I still need to thank to all those support "units" around me - something left for next blog entry...

--JaroslavTulach 12:01, 23 June 2008 (UTC)

[edit] Entering the Blogosphere

I have created my blog, does it mean that I finally exist?

--JaroslavTulach 09:33, 15 June 2008 (UTC)

[edit] Jesse Glick

[edit] Question on classes and interfaces

Someone asked: I guess that, roughly, a client API should use abstract classes while a support/provider API should use interfaces?

To which I responded...

--JesseGlick 09:33, 15 July 2008 (UTC)

[edit] Andrei Badea

[edit] Enums in APIs

An user of an enum might want to ensure he has processed all its fields. This can be problematic when the user doesn't own the enum, such as in an API.

--AndreiBadea 14:18, 16 July 2008 (UTC)

[edit] Notes for blog writers

The Blogs support on this site is using WikiArticleFeeds extension configured to recognize following tags:

<startFeed/>
==== Blog entry ====
 
Some introductory text with a [[link]] to your article.
Followed by your signature:
 
--~~~~
<endFeed/>

There is also MediaWiki's GeSHi extension installed. So in case you need to provide code snippet, use the source tag:

<source lang="java">
...
</source>

In case you are writing a blog entry where you expect lively discussion and participation from others, do not forget to end your page with:

<comments/>

That tag pre-creates a new and easy way to submit comments to your blog page.