OlderBlogPosts

From APIDesign

Is C Better than C++? Scala Rules!

Recently I've noticed an interesting article describing why C is more effective than C++ and in general most of OOP languages. The article is well written and for a while I was nodding in an agreement. The claim that by using OOP and insisting on encapsulation one cannot implement linked list as effectively as in C is a very good one!

However later I realized that the take on OOP is really targeted to OOP languages of the past. In modern languages, like Scala, one can keep encapsulation and still be as effective as the old plain good C.

All you need is proper orchestration between the List container and its elements. Scala will then type-safely handle the rest for you!

--JaroslavTulach 05:11, 3 September 2012 (UTC)

Why I Became an API Designer?

Why did I decide to be an API Designer with a strong emphasis on BackwardCompatibility?

I've been working on the NetBeans project since middle of nineties. One day, I guess in a year 1999, a product manager stopped by and started to shout at me:"We need partners, we need people to code plugins for NetBeans. We need compatibility. Are we compatible or not?" I started to explain we are compatible - just a few methods and classes were renamed, deleted, but nobody was supposed to use them anyway. The shouting however got even worse: "That is not compatible! We need full backward compatibility! Keep it!"

Up until that moment we treated BackwardCompatibility from a practical point of view. We were ready to sacrifice it when we had a vague feeling it does not matter to keep it. However that one moment changed everything.

Since then I decided to treat compatibility seriously and keep 100% BackwardCompatibility. As I studied computer science at mathematics and physics faculty, I decided to apply as mathematical approach as I was able to find ways to really keep absolute compatibility. No excuses, no cheating, just 100% BackwardCompatibility. I guess NetBeans platform API compatibility history is a good proof showing we gained some knowledge in this respect.

To transfer that knowledge to my colleagues I invented an APIFest game (described in Chapter 17 of TheAPIBook). Playing such game really seems to improve the 100% backward compatibility skills. It comes with a bit academic approach, in real world one is usually OK with "99%" compatibility, but by taking things to extreme, the APIFest nicely shows the point.

Don't be afraid to ask us to prepare an APIFest game for you! Find out why BackwardCompatibility matters!

User comment by Daniel Latrémolière: Compatibility is highly important, but not broking compatibility sometimes can be complex (code difficult to read or problem for finding an asked method; by example). When an API need to be broken, then a good solution is broking API while insuring good binary compatibility by using a small compatibility layer for implementing old API on new API(s).

If the compatibility layer (no big idea in its code then no need of copyright) is released under an AS IS licence like BSD, the API user can use its code for refactoring easier its own code from old API to new API (with help of IDE). By example a non-modular API can be refactored in a non-modularized compatibility layer (for old users) calling two modularity-aware API (for new/updated users).

My reply: Thanks for leaving your comment. Yes, keeping the old APIs around may complicate time to market as newcomers may have hard time to find the way to do things right. Sometimes one wants to send old API to a blackhole - actually the Chapter 19, End Of Life Procedures of TheAPIBook contains description how one can keep BackwardCompatibility and still get rid of the old, deprectated APIs.

--JaroslavTulach 08:17, 30 August 2012 (UTC)

Is Invisible Method Signature Part of API?

Having a package private invisible abstract method in an abstract class effectively prevents anyone using such API to subclass it. This can be considered as good API design pattern, especially if such pattern is used since initial version of the API.

However it can also turn into a huge anti-pattern. Adding first package private abstract method into an abstract class is in fact an incompatible change. If the class used to be subclassable before, this prevents the subclassing and as such classes that used to compile may compile no more.

If the original version of a class contains one abstract method:

package api;
/** version 1.0 */
public abstract class AbstractClass {
    public abstract void subclassMeAndImplementMe();
}

and later somebody adds a new implementation detail:

package api;
/** version 2.0 */
public abstract class AbstractClass {
    public abstract void subclassMeAndImplementMe();
    // hidden, not public new method
    abstract void youWillNeverImplementMe();
}

then we are facing an incompatible change. Inspite of not changing the visible methods of the class at all!

The hidden catch is that tools like Sigtest are unlikely to catch this situation, as they don't care about package private methods! Sigtest only emits a warning:

Warning: public class api.AbstractClass cannot be extended because contains the following member:
  method abstract void api.AbstractClass.youWillNeverImplementMe()

However warning is not enough, this is an incompatible change and it should be reported as such. The error should be same as in case somebody makes the youWillNeverImplementMe method public abstract. In such situation sigtest properly reports error:

Class api.AbstractClass:
  "E5.2 - Adding abstract methods" : method public abstract void api.AbstractClass.youWillNeverImplementMe()

Some people complained about unnecessary complexity of various OOP access modifiers - and they were likely right, but this case is worse (from the point of an API designer). So far API authors needed to care only about public and protected elements (as described for example in ClarityOfAccessModifiers), but it seems that we need to paly attention also to non-visible ones - a change to an implementation detail may change the published APIs!

--Apidesign 12:13, 20 March 2012 (UTC)

API Design is JavaOne Rock Star

My presentation about API Design Paradoxes has been rewarded as one of the more interesting ones during JavaOne2011. There is no video at the JavaOne rock star page, but as I keep repeating the presentation again and again with almost the same content, you can view the Linz 2009 version or Ostrava's 2011 translation to Czech.

It was fun to talk about Paradoxes, but I guess it is time to come up with something new. I'll try to resubmit my talk about AnnotationProcessors next year. Hopefully the just gained Rock Star status will give that talk few plus points and raise its chances to be accepted.

--JaroslavTulach 08:58, 20 January 2012 (UTC)

Beware of Friends! They'll Change You!

In case you are doing something for friends only (as many of facebookers do), you are in a great danger. Blindly increasing list of your friends is not for free. Because (as soon as you change list of your friends) you change yourself, you will immediatelly become different from outside.

This, in an API terminology means, you need to produce new version of yourself. Thus, when you publicaly state you have a new friends, version yourself! Read about FriendDependencies to understand why!

--JaroslavTulach 15:20, 19 September 2011 (UTC)

JDK7 Breaks JUnit Tests

Without the intent to blame JDK7 for being finally available, I have a concern to share. After switching the NetBeans test runs to use JDK7, most of the test suites started to fail randomly!

In case you are considering to switch to JDK7 and you have existing JUnit tests, consider including the time for stabilization of the tests into your migration plan.

--JaroslavTulach 12:33, 22 August 2011 (UTC)

API Designers: Are You Planting Forests or Gardens?

Today I have an unusual chance to talk about gardening (or planting forests) when designing APIs. The key concept to grasp is the ability to mount various types of APIs together. Btw. do you know that there are more types of APIs, right? Learning how to mount them together is an important knowledge that will determine whether your API or SPI will turn into a beautiful garden or fall into disorder of unmaintained, dark forest. Visit today's essay to learn how to properly mount client APIs and provider APIs so they can strengthen each other.

--JaroslavTulach 13:03, 21 March 2011 (UTC)

Using Netbinox hooks

Do you want to use extension hooks to extend behavior of Netbinox the same way you used to extend Equinox? Before version 1.16.7 this used to be complicated, but as this little tutorial shows, now hooks can be registered easier than ever.

--JaroslavTulach 15:49, 29 January 2011 (UTC)

Beware of Using Enums

Have you ever thought that enum in JDK5 is good idea? Then welcome to the club. I used to think that as well. But it is not, when it comes to API design. Read why to understand its gotchas.

--JaroslavTulach 22:04, 12 January 2011 (UTC)

Visualize Lookup

There is a very nice visualization of Lookup and its family on the ImageJ web site. It is created by MindMap and I find it quite explanatory. In case you ever wanted to sort your thoughts about Lookup, this mind map] is definitelly going to help.

--JaroslavTulach 16:24, 10 January 2011 (UTC)

Access Facebook from a Desktop Application

Having trouble to access Facebook from your desktop application? I know how to help you out of your missery. Read the story and source code for my Feedbook desktop application - application that I use to re-publish my blogs from this site to my Facebook account.

--JaroslavTulach 19:46, 16 November 2010 (UTC)

One ClassLoader to Know Them All!

Modularizing monolithic application into individual pieces has various benefits. For example classes will be well isolated from each other. However there can also be pitfalls. For example classes can be too much isolated from each other and Class.forName can yield bunch of ClassNotFoundExceptions. What you need in such situation is a classloader that knows everything. Here is a little essay about problems you can face when building it.

--JaroslavTulach 10:35, 9 November 2010 (UTC)

Removing protected abstract Methods is no Longer Source Compatible

Rijk van Haaften noticed today that removing protected abstract methods (which used to be source compatible) is no longer compatible at all. I am adding his comment to errata for chapter 6. Please find Rijk's observation there.

--JaroslavTulach 07:44, 8 October 2010 (UTC)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

@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)

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)

Extend Inextensible!

Interfaces are not extensible. Learn how to extend them!

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

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

Can there Be Implement Only Interface?

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

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

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

Dependencies Between Jigsaw Modules Made Easy!

Those who observe my blog may remember that I have an obsession. I am trying to understand module versioning and dependencies between modules. Recently I was playing with JigsawServices:

module M1 {
  requires service S;
}

The above concept is essentially NP-Complete as one may have choices from multiple modules providing implementation of the service and selecting the right one is NP-hard as explained in this example.

But I think I have found an acceptable solution. Today I will have a presentation about it (here are the slides). Wish me luck!

--JaroslavTulach 13:56, 24 July 2012 (UTC)

JavaFX + Swing: Together at last!

I am proud to announce that the mutual JavaFX and Swing interoperability has been greatly simplified. No need for massive amount of asynchronous Runnables! Your Swing code can directly talk to JavaFX data structures and your JavaFX code can manipulate with Swing objects. This is a small change, but huge step forward for Swing+JavaFX interoperability!

A related quiz: When your code runs, can it find a difference between threads it is executed in? My guess is that it cannot!

--JaroslavTulach 10:35, 23 May 2012 (UTC)

An API Proximity. Are You Close Friend with Your API?

How close are you to the API that you use? Are you friends? Do you hate each other? Have you memorize the API? Can you debug it? Is your API a clueless blackbox for you? Are you a calling client? Do you implement and provide some of the API concepts? Do you think I am asking silly questions?

It seems that proximity is one of the best ways to classify libraries into categories. So far I managed to recognize Zero to Many, One to Many, Few to Many and Many to Many proximity categories. They seem to directly influence the APIDesignPatterns one should use when designing such libraries. As such, when you are about to design your library, think a bit about the proximity you want to have with your clients and providers.

Btw. Most of NetBeans libraries is using the Many to Many proximity. I'll be more than glad if you decide to stick with our most favourite proximity style as well.

--JaroslavTulach 19:56, 12 May 2012 (UTC)

RangeDependencies May not Be Root of All Evil! But OSGi's High Shot Missed the Sweet Spot.

Most recent work on understanding range dependencies in modular systems seems to reveal that all the flaws associated with RangeDependencies (e.g. resolving module dependencies being an NP-Complete problem) can in fact be eliminated by so called complete repositories. Looks like it is time when I should apologize to poor RangeDependencies - it is not your fault, it is the way people use you that is causing problems.

Should I also apologize to OSGi? No, it is probably too early. we need to wait until complete repositories are adopted by that system. Until that happens I can still claim that OSGi's high shot missed the sweet spot!

--JaroslavTulach 10:33, 9 January 2012 (UTC)

Defending OSGi

My recent post about OSGi deficiencies generated some interesting comments and observations which seem worth to be shared. Thanks Mirko for stopping by and leaving your long answer.

I should probably mention that my talk Experiences from Building the Fastest OSGi Container on the Planet has been accepted for March 2012 OSGiCon - thus dear OSGi fans, I may be available for face to face exchange of arguments.

--JaroslavTulach 08:50, 25 November 2011 (UTC)

OSGi is Just Weird

Last week I submitted a paper to OSGiCon 2012. I'd like it to be accepted as I'd like to meet the Mylyn guys there. To attract a bit of attention to it I've decided to be a bit controversial:

OSGi is flexible, but not logical. OSGi is not well thought out. OSGi is over designed. Read more to understand why.

In case the previous ramblings would not guarantee me the invitation for OSGiCon, I can also be nice and say: OSGi is good for interoperability. Can my paper be accepted now?

--JaroslavTulach 15:23, 13 November 2011 (UTC)

Less is More: Erasure of Generic Types in Java

People like to complain about erasure of the generic type information during runtime. Yes, the lack of introspection is unfortunate. Since JDK 1.1 people got used to inspecting and reflecting almost anything. The fact that information about generics is erased provokes them.

However not everything is so bad. The erasure of the type information has benefits. For example we all know that covariance and contravariance is not very useful when designing APIs in Java, right? However due to erasure of the proper type information, there are situations when one can rely on it.

The less type info due to erasure allows us to achieve more!

--JaroslavTulach 18:05, 19 October 2011 (UTC)

Intelligent design or Evolution?

Are you fan of intelligent design or evolution? None, or you don't care? If you are designing APIs, then you should! Because intelligent design plays a central role in life of software architects. Your attitude towards it predefines how good architect you can be!

--JaroslavTulach 11:55, 25 July 2011 (UTC)

Is Java an Object Oriented System?

Few years ago I was chatting about Smalltalk with Peter Ahé (originally JavaC maintainer). We laughed at ridiculous classical Smalltalk coding practices, but then realized that to some extent similar style was used when designing Java as well. Peter even said that Java is not object oriented language but yaady-yaady-da oriented language. I no longer remember what exactly Peter called Java, but maybe you can read our Smalltalk objections and help find me the right name.

You are welcomed to comment!

--JaroslavTulach 14:58, 15 July 2011 (UTC)

Is God A Computer Scientist?

Last week I finished reading of the Is God A Mathematician? book and I can't prevent myself from recommending it by all means! My own book about API design uses various parables with the history of discovering the laws of real world. I used one very nice Czech book as an inspiration for these philosophical parts and I was always very sad that I cannot give my readers a chance to read it, as it was not translated to English. The Is God A Mathematician? book is a very good substitute.

If you want deeper insight into the "battle" between rationalism and empiricism, Is God A Mathematician? is a perfect book to start with. It does not cover everything that I'd like to be covered, but never mind, it is still quite a good book. Plus I have enumerated the omissions on my review page, including few notes about computer science.

--JaroslavTulach 20:16, 7 June 2011 (UTC)

Disassemble Your Types!

AssemblableTypes are your friend while modularizing your APIs. With their help you can make sure you disassemble your monolithic system into flexible and independent parts that smoothly assemble together when used by your API users.

--JaroslavTulach 17:08, 14 May 2011 (UTC)

Beginner's Guide to Modularity for DI Fans

Do you use Dependency Injection and are you curious about concepts of modularity? Then you can use this little guide explaining how certain concepts in Dependency Injection map to concepts in modular world.

--JaroslavTulach 16:49, 9 February 2011 (UTC)

Transactional Memory

TransactionalMemory is an attempt to bring the power of databases to general purpose programming languages. wikipedia:Transactional Memory should be the ultimate source of information, however it seems that much better understanding of TransactionalMemory can be obtained by reading follwing practitioner's report. Joe Duffy's text is worth reading - it shows why weak TransactionalMemory cannot work. In the process of showing that it describes the gory details that remain unnoticed in the general overview at wikipedia:Transactional Memory.

As far as I can tell Joe's write up is one of the best texts on internet I have read in months. It is deep, detailed, informative, entertaining and contains pieces of wisdom you don't want to miss. Like the "these kinds of moments make me a believer in formal computer science" acknowledgement.

A more meta-level thought: Joe's text shows why it is important to properly document failures. Why it is important to describe roads that lead nowhere. As Jára Cimrman says: Should not we value the person who tried to blow a cigarette smoke into watter to find out that this process does not produce gold? Thanks Joe for showing us that (weak) TransactionalMemory does not help to build reliable programming environment.

--JaroslavTulach 11:33, 2 December 2010 (UTC)

Excel in Designing DSLs for Excel People

Do you unit test your Excel formulas? Is that even possible? My new post is not going to teach excel users new tricks, but it may help you to excel in designing domain specific languages. Either external or embedded (into Java or Excel ;-).

--JaroslavTulach 21:53, 27 October 2010 (UTC)

"Five" Principles of Modularity

Here is quite nice summary describing the content of our yesterday presentation about Patterns for Modularity written by Roger Rached. I really enjoyed the talk and I'd like to thank everyone for stopping by.

--JaroslavTulach 01:09, 23 September 2010 (UTC)

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)

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) .

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)

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)

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)

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)

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)

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)

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)

What is a chance?

What is a chance?

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

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

Close Proximity of API-less APIs

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

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

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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 BackwardCompatibility. 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)

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)

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)

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)

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)

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)

Dependencies Are Important Type of API

New type of API has been discovered!

JaroslavTulach 07:05, 15 July 2008 (UTC)

Twitter Client

I've just finished Twttr Client demo. Written in very compact Java with the help of AnnotationProcessors. Runs in Java pluginless browser thanks to Bck2Brwsr VM. DOM tree is updated by Knockout.js.

Feel the power!

--JaroslavTulach 13:04, 10 April 2013 (UTC)

Bck2Brwsr 0.5: Better Knockout.js Bindings, More Compact Code & Co.

• Bck2Brwsr 0.5 has better support for MVVC via Knockout.js - see the calculator demo version 0.5
  • Binds String and primitive types
  • Bind array types (exposed as List
  • Basic binding of complex classes
• Separate module for Maven archetype called org.apidesign.bck2brwsr:bck2brwsr-archetype-html-sample (and thus instructions for getting Bck2BrwsrViaCLI has changed)
• Improved speed of Bck2Brwsr virtual machine via better control flow
• Can use Closure compiler to generate more compact code
  • FULL mode: For batch compilation of everything for now (example pom.xml that uses the j2js goal)
  • MINIMAL mode: Strips spaces. Works in dynamic mode (part of the default Maven archetype)
• One incompatible change: AnnotationProcessor for the @Page annotation no longer capitalizes field names found in the HTML page. This was meaningful when the fields were static constants. Now (when they are plain instance fields) it makes little sense.

--JaroslavTulach 13:43, 26 March 2013 (UTC)

Missing goto in JavaScript and Java?

Are you missing goto in your favourite language? Here are two ways to use efficient and flexible code flow with as many gotos as needed.

Good programmers can code Fortran in any language!

--JaroslavTulach 09:36, 13 March 2013 (UTC)

Try Java in Your Browser!

Bck2Brwsr 0.4 has been published and uploaded to java.net Maven repository. Give it a try!

--JaroslavTulach 23:26, 7 March 2013 (UTC)

Three Steps to See Java Back in Browser

There is a simple, three steps way to generate sample Bck2Brwsr project and run it in your browser. Will you spend few minutes to see completely secure Java running everywhere?

--JaroslavTulach 18:12, 13 February 2013 (UTC)

Java Code in Chrome is Now 10 Times Faster!

Today Ľubomír finished first phase of his register based rewrite of Bck2Brwsr virtual machine. The results are amazing. Our matrix multiplication benchmark got ten times faster! See the graphs and congratulate Ľubomír together with me!

--JaroslavTulach 12:31, 14 December 2012 (UTC)

I am OpenJDK Contributor

I am pleased to announce that my patch for OpenJDK has been accepted. Now I feel like a proud OpenJDK contributor.

--JaroslavTulach 11:43, 10 December 2012 (UTC)

Lookup is an Ubuntu Package!

I've just noticed that Lookup library is now a separate package for Ubuntu. When installing VisualVM, on Kubuntu 12.10 the following package is installed as well: libnb-org-openide-util-lookup-java (7.0.1+dfsg1-5ubuntu2).

I knew Lookup is needed for any NetBeans platform based application, but it used to be packaged as part of NetBeans Platform package. Looks like somebody started to re-use the Lookup as an independent library and needed a separate package - good!

--JaroslavTulach 05:08, 6 December 2012 (UTC)

Bck2Brwsr

I had little time for blogging since JavaOne and today I can explain why. During long nights and lonely weekends I was working on Bck2Brwsr project - yet another way to execute Java in a browser. Today I am proud to announce second milestone demo. All you need now is a small bck2brwsr.js bootstrap and a JAR file - suddenly your Java code appears in a browser.

I'd like to thank jtulach, my cousin, for helping with some more advanced tricks with JavaScript. Especially the stub class function which gets replaced by real class implementation on its first invocation is a trick I might be searching for for ages...

--JaroslavTulach 16:49, 28 November 2012 (UTC)

How Much Time It Takes to Fix a Single Line?

How much time it takes to fix a single line in the NetBeans IDE? What is your guess? Make it now and then compare it with my own experience.

--JaroslavTulach 19:01, 23 November 2012 (UTC)

Time to Fly for JavaOne2012

JavaOne2012 is about to start on Monday and I am about to go to Prague airport and fly to San Francisco. It will be a busy week - I had submitted five proposals assuming at least half of them would be rejected, but I underestimated the influence of being a JavaOne rockstar (due to JavaOne2011 talk about API Design Paradoxes). As a result I have four sessions and one hands on lab. Plus many duties on the booth. Wish me luck and if in Bay area, stop by.

--JaroslavTulach 01:54, 29 September 2012 (UTC)

Lukáš Jungmann's TestNG

Some of you may remember our TestNG efforts. During the last nine months and with great delight I could witness Lukáš's changes to be accepted by the Cédric into the TestNG project. I could see Lukáš's modules getting part of soon to be released NetBeans IDE 7.2. Most recently I was also present at Lukáš's bachelor thesis acceptance review and saw his work being adored by his review committee. Congratulation for getting the A mark for your work, Lukáši! And thanks for making (not only) NetBeans better!

--JaroslavTulach 14:58, 21 June 2012 (UTC)

DXR3 driver: The Fun of being a Linux Developer!

New perspective about Linux API development gained by updating DXR3 kernel driver to run on most recent kernels.

--JaroslavTulach 20:02, 7 June 2012 (UTC)

Useful advice: Close Derby Connection from Ant

Thanks Phil, I am glad my note was useful. I'll publish your comment on my blog to make sure it gets indexed by search engines.

--JaroslavTulach 07:15, 18 May 2012 (UTC)

It is nice to know that a page written two years ago was useful...

--JaroslavTulach 07:17, 18 May 2012 (UTC)

Podcast, Slides and Screencast

Description of my OSGiCon experiences is now available as a podcast Media:APITip-OSGiCon.mp3. Together with the screencast (illustrating point of my OSGiCon presentation) and slides it brings you the ultimate Netbinox experience to help you speed up start of your OSGi applications!

--JaroslavTulach 11:22, 16 April 2012 (UTC)

Ask me about Netbinox at OSGiCon!

My session at OSGiCon about the fastest OSGi container on the planet has been scheduled. On Mar 28 @ 14:15 in Reston Suites B I reveal the fascinating story behind creation of Netbinox. Stop by, or ask me about Netbinox anytime during OSGiCon!

--JaroslavTulach 14:59, 25 March 2012 (UTC)

The Migration Guide from JUnit4 to TestNG

We are proud to announce that our improvements to TestNG (written by Lukáš Jungmann) have been accepted for the next version of TestNG by Cédric Beust. These enhancements will help the NetBeans project to start switching to TestNG incrementally.

The NetBeans code base contains a lot of existing JUnit3 and JUnit4 tests and we cannot rewrite them all at once. Thus Lukáš improved TestNG to support an automated mixed mode execution. That way we can slowly start writing new TestNG tests (and rewrite some of the existing) while being sure that thousands of our current tests continue to run along the new generation ones.

We believe that this feature will be useful for other teams as well. In case you are interested, check out our migration guide.

--JaroslavTulach 09:43, 24 February 2012 (UTC)

Bode on API Design

Bode Miller is the most famous American sportsman (at least in Austria). His bibliography explains that he is not only an excellent skier, but his ideas are fundamental for proper API design! Find three reasons why...

--JaroslavTulach 14:08, 7 February 2012 (UTC)

JDeveloper Makes NetBeans 7.1 Look and Feel Better!

Last year's April I wrote a future press release describing all the things we wanted to do to NetBeans window system. This week is the right time to look back and verify whether we succeeded or not. Inspecting the differences in our original plans and our current state I am not afraid to say we are going to be in pretty good shape once NetBeans 7.1 FCS is out.

Yes, the release is slightly delayed - originally we wanted to release in November. However looking from a technical side, we delivered what we promised - visual layout editor, Savable, loosely coupled MultiViewElement.Registration, tons of enhancements in user gestures and in flexibility of applying non-standard look and feels (see the Window System 7.1 Press Release for details).

I'd like to thank Stanislav Aubrecht for doing most of the UI related work, for dealing with HIEs, graphical designers and for delivering such perfect improvements.

I am glad our colleagues from JDeveloper are pushing us hard with their requirements. Clearly, trying to improve NetBeans Platform to match JDeveloper needs makes NetBeans IDE a better product! There is still a lot of work ahead of us to re-use what we have done for NetBeans 7.1 in JDeveloper, but you don't have to wait:

Get your copy of NetBeans 7.1 as soon as you can! You won't be sorry. It is the most flexible release in terms of user experience we produced in many years! Thanks in advance for trying NetBeans.

--JaroslavTulach 14:26, 5 January 2012 (UTC)

Shuffle Your Amarok Playlist

I am using Amarok to manage my music collection. I was happy with Amarok1, but since its rewrite to Amarok2 I missed a shuffle operation. Last week I finally convinced myself to spend a bit of time and wrote an extension to Amarok to do the shuffling (in JavaScript). In case you are an Amarok user find more information about my project here.

--JaroslavTulach 07:36, 6 December 2011 (UTC)

JavaOne2011 is Over

JavaOne2011 is over and I am back at home. Originally I was very disappointed as my talk about AnnotationProcessors was not accepted. I hoped it belongs to JavaOne as it clearly shows how to move Java forward. I guess I submit it next year again.

Anyway I enjoyed my talk about paradoxes. The room for two hundred guests seemed full and the questions revealed huge interest in the topic. Using paradoxes really concentrates on the point. It shows what we usually expect (based on our in house software development knowledge) and what we will not get when dealing with APIs. I wish I could write a book about paradoxes!

We had to handle the talk about Featureous without John Langton, but we did our best to represent the success story of modularizing John's application. I talked mostly about my own experience of modularizing NetBeans open apis by hand. I wish I had a tool to help me at those stone age times!

Third talk about modularity patterns was very refreshing. Me, Zoran and Toni are proud we managed to get into argument on stage! Arguments are usually refreshing for the audience and wake everyone up. When speakers don't agree with each other, the interest grows. We did our best to disagree! Thanks to everyone who decided to visit our talk - we enjoyed your support! We are working on next part of the module pattern series for next JavaOne.

--JaroslavTulach 20:45, 9 October 2011 (UTC)

Netbinox is Free!

Originally I licensed the Netbinox (e.g. the fastest OSGi container on the planet) project under GPL. This payed off, as I knew (most of) my customers. Almost everyone who wanted to use the Netbinox needed to send me an email and ask. Either to verify usage of GPL is OK, or to ask for a different license. Only due to viral nature of GPL I was contacted by members of the Equinox team to find out whether I want to donate the NetbinoxPerformance to Equinox.

However since Netbinox is now used by JDeveloper and is also used by the Mylyn modules inside NetBeans 7.1, it does not make sense to keep it under GPL. It is more natural to give it the classical, liberal open source NetBeans license (CDDL or GPLwithClassPathException). Since NetBeans 7.1 you can use Netbinox together with NetBeans Platform without any licensing limitations.

I will loose track of those who use Netbinox, but I hope to see more and more Netbinox based applications for real. Because: why would you use Equinox when Netbinox is fully compatible and much faster?

--JaroslavTulach 08:20, 1 September 2011 (UTC)

Incompatible Me!

Are you compatible with yourself? that is the kind of question you have to ask when you live in environment assembled by means of incremental deployment. Because when an incremental deployment is in place, it is not enough that your code compiles at given time, it is important to verify that it also assembles fine with all previous versions! Hear the story about incremental deployment problems NetBeans 7.0.1 had.

--JaroslavTulach 18:30, 12 August 2011 (UTC)

JDeveloper and NetBeans

A new version of JDeveloper has been released last week. Curious people already noticed that the JDeveloper installation contains netbeans subdirectory. Yes, it does.

Here is my description of the history and explantion why I believe we are heading the right direction.

--JaroslavTulach 08:52, 14 June 2011 (UTC)

Making NetBeans Better in Munich!

I am planning my trip to Munich's NetBeans Day that will happen on June 18, 2011 right now.

I will have a code dump (e.g. a lot of code produced on a stage) presentation about advanced usage of AnnotationProcessors. The presentation is based on our NetBeans experience and tooling, but the knowledge that you gain is going to be widely applicable when designing any Java APIs. Register and let's meet in Munich to talk not only about annotation processing, but also about API design and what's new and planned in NetBeans.

See you in two weeks!

--JaroslavTulach 14:51, 2 June 2011 (UTC)

Food in Geecon 2011 - Krakow

GeeCON at Krakow is great! I've just had another Paradoxes of API Design presentation at Geecon at Krakow. This time I had to talk for three hours. Quite a long talk for an occasional speaker like me. I knew I would need a sugar to handle that. That is why I stood in front of the entrance with HtmlForFood sign and hoped to receive some. And I did receive one candy, one apple and one mandarin. Thanks a lot for the food donation!

As a pay back for this kind of support I decided to donate one copy of TheAPIBook to the audience. Thus I am starting yet another HtmlForFood contest. Dear Geecon 2011 participants, write your signs, take photos, end them to food@apidesign.org!

The copy of TheAPIBook will be given to the most hungry winner on Friday, May 13, 2011. Now I need to find the winner.

--JaroslavTulach 09:08, 13 May 2011 (UTC)

Window System Enhancements for 7.1

There was a lot of planning meetings in Prague office recently and as such I have had no time to blog. Let me fix that now.

Being reminded about importance of working backwards I gladly present future window system press release. It outlines the enhancements that will have been implemented for NetBeans 7.1. I hope we'll manage to code them all and I hope you'll like the netbeans:WinSys71PressReleaseresult.

--JaroslavTulach 09:25, 6 May 2011 (UTC)

Paradoxes of API Design Video předabováno do češtiny

I have the pleasure to announce that the video from Ostrava JUG is now available. I spoke Czech, so this is of interests of only limited audience (the rest please see the original), ale pro ty, kteří česky umí může být tato novější verze zábavnější. Každopádně je zábavnější pro mne, neboť jsem si výlet do Ostravy užil. A děkuji za klobouk, který jsem tam zapomněl. Už je zpátky...

--JaroslavTulach 09:30, 13 April 2011 (UTC)

Chinese Translation

I am receiving quaterly reports about sold copies of my book. A year ago I noticed a payment for some translation. I did not know the target language, but I expected some europian one. Wrong! This is cover of TheAPIBook translated to Chinese:

I cannot read much, but it looks like some parts of the cover are familiar. This book must be about API design!

--JaroslavTulach 20:01, 8 April 2011 (UTC)

Mirror NetBeans Update Center Catalog

Here is a note about my latest practical achievement. I have created an ant script to clone content of any NetBeans catalog.xml(.gz) available online. It reads the list of available modules, allows you to choose the ones to mirror (using a regexp on cluster or module names), downloads them (skips the download when an NBM file with same or newer version is already available locally) and generates new updates.xml file to represent your local repository.

Enjoy Mirror.xml script!

--JaroslavTulach 10:53, 25 March 2011 (UTC)

API Quiz at Ostrava JUG on March 2nd, 2011

Ostrava JUG presentation tried to tease the listeners with one API quiz. Visit the Ostrava's summary to tease yourself as well.

--JaroslavTulach 12:28, 7 March 2011 (UTC)

Live Matisse

Here is a screencast showing how true hotswap will simplify life and boost productivity of desktop application developers.

--JaroslavTulach 08:09, 21 February 2011 (UTC)

Real Hotswap is not Only About Classes

I received few very good comments after blogging about the true hotswap for JDK. Thus I need to slightly correct my original opinion. Not only we need true hotswap, but we need real hotswap! Dealing with updates of classes is just a first step. We need tools like Javeleon to integrate well with all other aspects a framework needs to offer to make the hotswap feel real.

--JaroslavTulach 08:04, 18 February 2011 (UTC)

Netbinox is Built Around Unmodified Equinox Now

Those who follow my work on Netbinox may be pleased that since Feb 12, 2011, the Netbinox version 1.16.8 bundles unmodified version of org.eclipse.equinox.jar. The functionality remains unchanged but your legal organization may accept this new setup more happily.

--JaroslavTulach 15:19, 14 February 2011 (UTC)

Renewing TheAPIBook's domain

Yesterday I managed to prolong the apidesign.org domain for next three years. I can see there are some followers out there, and anyway I need a place to dump my mind to. Thanks for reading my posts and happy New Year 2011!

--JaroslavTulach 10:26, 5 January 2011 (UTC)

True Hotswap - Gift for Every (Java) Developer!

Are you using Hotswap when developing your programs? No, in such case read why you should start using it immediately! Do you know hotswap is present in every JDK? Do you consider it too limited? Then read about recent enhancements that give you true hotswap for your JDK!

You can also read my short, and mostly incomplete classification of various hotswaping techniques, or just click here to learn how to download and install enhanced hotswapable JDK. I am blessing the power of hotswap since the moment I installed it. Do it too and enjoy your newly gained coding productivity!

--JaroslavTulach 07:57, 26 December 2010 (UTC)

Instantiate Abstract Classes

Do you know that Chuck Norris can instantiate abstract classes? Do you want to be able to do so too?

--JaroslavTulach 09:23, 13 December 2010 (UTC)

Error occurred during initialization of VM

Have you ever faced errors during initializaiton of your OpenJDK virtual machine? Something like:

$ java
Error occurred during initialization of VM
Could not reserve enough space for object heap
Could not create the Java virtual machine.

If so, you may be interested in reading this post. I think I know how to eliminate the problems by relying on one type of API associated with the OpenJDK installation layout.

--JaroslavTulach 09:11, 28 November 2010 (UTC)

The Importance of Being Online

Voice of customer: If I didn't come across the PDF, I probably wouldn't have ever discovered your book and forked over the $60 for the hardcopy. :-) Obviously, there is a value in being online. --JaroslavTulach 08:47, 3 November 2010 (UTC)

Giving Up on Linux Packaging

This post is for Linux and NetBeans users. Do you use NetBeans package on your Linux? Do you want to continue doing so? In such case we need your help!

--JaroslavTulach 13:45, 22 October 2010 (UTC)

London: Smells Bad. Feels Good.

I'm just finishing my visit to London to propagate the NetBeans Platform. Few open questions are left in my head and also I'd like to make one suggestion: By my next return, can someone improve the air?

--JaroslavTulach 20:28, 15 October 2010 (UTC)

Java One 2010

Tomorrow I'll get on a plane and I'll travel to California to visit and talk at JavaOne2010. In case you'll be there, join me and friends at some of the presentations we are going to give.

--JaroslavTulach 15:50, 13 September 2010 (UTC)

Throw Away Your Bug Tracking System

Time to close our Bugzilla! Dear members of NetBeans community, I'd like to announce that I plan to close all open issues in our bugzilla (that I don't like) as won'tfix for serious reasons. Are you OK and ready for that?

--JaroslavTulach 09:40, 7 September 2010 (UTC)

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)

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)

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)

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)

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)

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)

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)

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)

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.

<comments/>

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

DocBook to OpenDocument conversion

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

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

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)

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)

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)

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)

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)

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)

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)

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)

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?

<comments/>

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

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!

<comments/>

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

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)

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)

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)

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)

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).

<comments/>

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

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)

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)

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)

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)

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)

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)

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!

Now I am in the same group as musicians and movie stars, my work is being copied! Without royalties, but it still makes me proud. Is there anything better for a book author than knowing that his book is read by someone? As one reader attracted by the online version puts it: Look at the upside. If I didn't come across the PDF, I probably wouldn't have ever discovered your book and forked over the $60 for the hardcopy. :-)

In case you get the same feeling after scanning through the torrent version, don't hesitate to order via amazon and/or stopping by to get written dedication.

Enjoy API Design!

<comments/>

Comments So Far

I've got a legally-obtained printed copy. I hope this means I can get you to sign it when I see you again!

--Tomwheeler 17:31, 16 August 2009 (UTC)

Indeed! Don't you want to see more from Prague, Tom ;-?

--JaroslavTulach 06:45, 17 August 2009 (UTC)

It's a common practice of mine:

1) search torrents for an argument of interest 2) download all 3) evaluate all 4) buy the hard copy (or the digital one) of the valuable ones.

I hate buying dummy books (or books for dummies;). I also hate pirating...

Obviously, I have the hard copy of Practical API Design on my desk, but I ordered it bypassing the usual workflow - no fear about the value, here!

Sergio

It is hard to keep appropriate level of humility after reading such comment. Thanks, Sergio.

--JaroslavTulach 12:18, 3 November 2010 (UTC)

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

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

API Podcast #2: Reentrancy

API PodCast #1

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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!

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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.

<comments/>

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

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)

And the Winner of the HtmlForFoodCompetition is ...

Let me announce the winner of the HtmlForFoodCompetition.

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

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)

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)

New LaF of apidesign.org

The websiste has new look and feel.

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

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)

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)

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)

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)

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)

Entering the Blogosphere

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

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