'. '

Main Page

From APIDesign

Revision as of 19:39, 26 June 2008 by JaroslavTulach (Talk | contribs)
Jump to: navigation, search

Contents

Practical API Design

Confessions of a Java Framework Architect by JaroslavTulach

Image:Apidesign.jpg

Dear Reader, you can buy the Practical API Design book here. Or find it at SafariOnline.

Maybe you are standing in a book store, holding this book in your hand, and asking yourself: "Should I buy it?" Here is your answer: If you have ever written code and handed it to someone else to let them compile their code against yours, the answer is: "You are ready to enter the API design world and this book will help you explore it."

However, this book does not attempt to "teach API design in five easy lessons". It cannot be read in "only three days!". If you are looking for a quick handbook, probably this book is not for you. On the other hand, if you are interested in a deeper knowledge of API design, in knowing not only the how, but also the why, let me introduce myself to you before you put this book back on the shelf.

My name is Jaroslav Tulach and I am the founder and initial architect of NetBeans, which is not just a well known IDE, but also the first modular desktop application framework written in Java. This book is based on notes that I have collected over the last ten years, while designing and maintaining NetBeans APIs and transferring this knowledge to the rest of our developers. It is a journal from the heart of the NetBeans laboratory, describing our problems, our growing understanding of them, the solutions we have chosen and the conclusions we made after applying them. Although our knowledge has been gathered while working on NetBeans, it is general enough to be useful for most software projects.

Knowledge of proper API design is essential for the successful creation of 21st century software. Let this book be your guide while exploring the big wide world of API design.

Jaroslav Tulach

Sources

All the code snippets shown in the Practical API Design book are extracted from real projects. As such it is guaranteed they are correct, they compile and can even be executed, debugged and tested.

Moreover, it is often not enough to see just a few lines of code in middle of a page, readers are recommended to get the whole tree of sources, including their history and play with them for real. Preferably use Mercurial to clone the sources Hg repository:

$ hg clone http://source.apidesign.org/hg/apidesign/

Environment

In order to use the sample sources you may need:

  • At least JDK7 or [[JDK]8 - necessary for compilation and execution
  • At least Ant 1.8.1 - allows simple compilation and execution from command line
  • At least NetBeans IDE 6.9 - all projects are configured to smoothly open in NetBeans IDE

If you managed to successfully start NetBeans IDE, you probably have everything necessary installed on your computer.

Download

Those that prefer ZIP over Mercurial (for example to get also all necessary libraries with the sources) can download the latest published build from our continuous build server. Download the latest version of apidesign.zip, unzip it on your local computer. Start NetBeans IDE and open individual projects as needed.

Usage

It is always better to build the root project:

$ cd samples # in case of [[Mercurial]] checkout
$ ant build.xml # or from the IDE

before opening its sub-projects in the IDE. Failing to do so may cause the projects to show broken references (due to missing libraries that need to be downloaded first in the Mercurial case). Btw. in case you need to perform really clean build and download all libraries once again, you can

$ cd samples # in case of [[Mercurial]] checkout
$ rm -r libs/dist

Funny Stories

My Hudson server crashed in early months of 2014. I had to configure it from scratch. While doing so, I forgot to configure the job to produce apidesign.zip file with sources. Has anyone noticed? Nobody sent me an email! Just yesterday Jáchym, my co-worker, who I torture by forcing him to read TheAPIBook and become good API designer, stopped in my office and timidly asked: Where can I get the sources? There is no ZIP file!

For a while I tried to blame him for not using Mercurial, but after a while I realized the problem is on my side. As a result, the zip file with sources is back as of Aug 8, 2014. Will anyone use them? It would be nice as reading Practical API Design book without having whole sources at your hand is like trying to understand Swing just by reading its Javadoc.

Let me know (Jáchym, you have to) whether you found the sources useful.

<comments/>

Others

Buy

Personal tools
buy