How to shutdown an ExecutorService

The new executor framework in Java 6 makes it dead easy to create components running in a background thread. Just create an executor, give it a java.util.Runnable and that's it. But how do you do a proper shutdown of a ExecutorService?

1. pExecutorService.shutdown();

2. try {

3.   if (!pExecutorService.awaitTermination(pTimeout, TimeUnit.SECONDS)) {

4.     pExecutorService.shutdownNow();

5.   }

6.   catch (final InterruptedException pCaught) {

7.     pExecutorService.shutdownNow();

8.    Thread.currentThread().interrupt();

9.    }

10. }

First we invoke the shutdown method on the executor service. After this point, no new runnables will be started.
The next step is to wait for already running tasks to complete. In this example we will allow the running tasks to complete within pTimeout seconds. If they don't complete within the given amount of seconds, we invoke shutdownNow(). This method will invoke interrupt on all still running threads.

As a good practice we also make sure to catch  InterrruptedException's and shutdown everything immediately.

What should you cache?

A good way of solving performance problems in an application is often to add caching at strategic layers of the application. But what should you cache?

For me, the single most important thing to cache is to everything that makes a network request.

Performing a network request will always have an overhead caused by the TCP/IP protocol, network latency, the network cards and the Ethernet cables. Even the slightest network hick up might cause huge performance issues in your application. A slow database will seriously decrease the performance of your application.

It is often not possible to cache everything that makes a network request, but not doing so should at least be a conscious decision and not just something you forgot to implement.

Public methods and package private classes

Given these two classes

class abstract AbstractClass {
   public void doSomething() {
    System.out.println("Hello world");
   }
}

public class ConcreteClass extends AbstractClass {
}

both in package org.mydomain. What will happen if I create a new instance of ConcreteClass in another package and try to invoke doSomething()? Will that work?

The answer to this question is it depends on the JDK. 


The Sun JDK allows you to access a public method in a package private class. However, OpenJDK will throw

java.lang.IllegalAccessException: Class MyClass can not access a member of class ConcreteClass with modifiers "public"

I'm not sure what the JDK specification says about this, but the moral is
Do not have public methods in package private classes.

Where does Node.js stand?

I recently became aware of Node.js and I'm trying to sort out where Node.js fits in the server side development picture. I found a few introductory videos from Ryan Dahl which sort of gave me the impression that Node might be the way of the future. So naturally the first thing I did from there was to Google "Node.js sucks". And of course, like anything that anyone thinks is good, somebody has to explain why that first guy was totally wrong. Whenever I hear the type of argument where one side says "X is the best possible," while the other side says "X is the worst possible," I always assume that X is very specialized – it's very good at doing something that people who like it need to do, but others don't. What I'm trying to put my finger on is just what exactly does Node.js specialize in?

So as I understand it Node.js has a few things that make it a lot different than traditional server-side development platforms. First off Node code is basically JavaScript. Client code running on the servers? That's weird. Also, I shouldn't have said servers (plural) because Node.js requires a dedicated HTTP server – just one server, and it's got to be HTTP. This is also weird. Node's got some clear advantages though. It's asynchronous and events-based, so theoretically Node applications should never block I/O. Non-blocking I/O might make Node.js a powerful new tool for dealing with giant message queues, but maybe it's got more working against it than just being weird.

I think the guys that say Node.js sucks sound kind of crazy, but they do have a point or three. First and foremost is that Node.js is single threaded; then the detractors have a problem with the similarities Node.js shares with JavaScript; and finally, they say that Node.js cannot possibly back their claim of being blockless.

Addressing the concern about JavaScript is tough for me. I'm not an expert with JavaScript and I don't really know its advantages and disadvantages over other languages. I have read detractors state that JavaScript is a slow language because it is scripted and not compiled. I have read JavaScript proponents explain that it's not the language that is either slower or faster, but the way the code is written, meaning that the skill of the coder supersedes the inherent qualities of the language. Both arguments have merit, and I don't feel qualified to pick a winner.

Most server-side developers are very used to running basically linear processes concurrently in separate threads. This method allows you to run multiple complicated processes at the same time, and if one process fails, the other threads can still remain intact. So having a single thread run one process at a time sounds like it would be really slow. I don't think this is the case with Node.js because it is asynchronous and event based, which is a very different model than one might be used to.

Instead of running one process, waiting for the client to respond and then starting another process, Node.js runs the processes it has the data to run as soon as possible in the order it receives them. Then when the response comes back that's a new process in the queue, and the application just keeps juggling these requests. The overall design is such that Node developers are forced to keep each process very short because – as the detractors are quick to point out – if any one process takes too long it will block the server's CPU which will in effect block the application.

So you can't do long complicated processes like calculating pi with Node.js. Apparently they have workarounds for spinning off really complicated processes if you really need to, but that seems to be outside of the scope of the original plan. I think that where Node shines is in routing a high volume of low-overhead requests. Which means to me that Node.js is great for light messaging applications with a high user volume.

Are there other uses I've missed? Are there other issues with asynchronous programming in a single thread? Is there some part of the big picture I'm not seeing? Am I just plain wrong about all of this? Leave me a comment and let me know what's what.

The Last Responsible Moment

In Lean Software Development: An Agile Toolkit, Mary and Tom Poppendieck describe a counter-intuitive technique for making better decisions:

Concurrent software development means starting development when only partial requirements are known and developing in short iterations that provide the feedback that causes the system to emerge. Concurrent development makes it possible to delay commitment until the last responsible moment, that is, the moment at which failing to make a decision eliminates an important alternative. If commitments are delayed beyond the last responsible moment, then decisions are made by default, which is generally not a good approach to making decisions.

Paradoxically, it's possible to make better decisions by not deciding. I'm a world class procrastinator, so what's to stop me from reading this as carte blanche? Why do today what I can put off until tomorrow?
Making decisions at the Last Responsible Moment isn't procrastination; it's inspired laziness. It's a solid, fundamental risk avoidance strategy. Decisions made too early in a project are hugely risky. Early decisions often result in work that has to be thrown away. Even worse, those early decisions can have crippling and unavoidable consequences for the entire future of the project.
Early in a project, you should make as few binding decisions as you can get away with. This doesn't mean you stop working, of course-- you adapt to the highly variable nature of software development. Often, having the guts to say "I don't know" is your best decision. Immediately followed by "..but we're working on it."
Jeremy Miller participated in a TDD panel with Mary Poppendieck last year, and he logically connects the dots between the Last Responsible Moment and YAGNI:

The key is to make decisions as late as you can responsibly wait because that is the point at which you have the most information on which to base the decision. In software design it means you forgo creating generalized solutions or class structures until you know that they're justified or necessary.

I think there's a natural human tendency to build or buy things in anticipation of future needs, however unlikely. Isn't that the Boy Scout motto-- Be Prepared?

I think we should resist our natural tendency to prepare too far in advance. My workshop is chock full of unused tools I thought I might need. Why do I have this air compressor? When was the last time I used my wet/dry vac? Have I ever used that metric socket set? It's a complete waste of money and garage space. Plus all the time I spent agonizing over the selection of these tools I don't use. I've adopted the Last Responsible Moment approach for my workshop. I force myself to only buy tools that I've used before, or tools that I have a very specific need for on a project I'm about to start.
Be prepared. But for tomorrow, not next year. Deciding too late is dangerous, but deciding too early in the rapidly changing world of software development is arguably even more dangerous. Let the principle of Last Responsible Moment be your guide.

TechnicalDebt

You have a piece of functionality that you need to add to your system. You see two ways to do it, one is quick to do but is messy - you are sure that it will make further changes harder in the future. The other results in a cleaner design, but will take longer to put in place.
Technical Debt is a wonderful metaphor developed by Ward Cunningham to help us think about this problem. In this metaphor, doing things the quick and dirty way sets us up with a technical debt, which is similar to a financial debt. Like a financial debt, the technical debt incurs interest payments, which come in the form of the extra effort that we have to do in future development because of the quick and dirty design choice. We can choose to continue paying the interest, or we can pay down the principal by refactoring the quick and dirty design into the better design. Although it costs to pay down the principal, we gain by reduced interest payments in the future.

The metaphor also explains why it may be sensible to do the quick and dirty approach. Just as a business incurs some debt to take advantage of a market opportunity developers may incur technical debt to hit an important deadline. The all too common problem is that development organizations let their debt get out of control and spend most of their future development effort paying crippling interest payments.

The tricky thing about technical debt, of course, is that unlike money it's impossible to measure effectively. The interest payments hurt a team's productivity, but since we CannotMeasureProductivity, we can't really see the true effect of our technical debt.
One thing that is easily missed is that you only make money on your loan by delivering. Following the DesignStaminaHypothesis, you need to deliver before you reach the design payoff line to give you any chance of making a gain on your debt. Even below the line you have to trade-off the value you get from early delivery against the interest payments and principal pay-down that you'll incur.

Designing a good API

What is an API
An application programming interface (API) is a source code-based specification intended to be used as an interface by software components to communicate with each other. An API may include specifications for routines, data structures, object classes, and variables.
Why is a an API important
All developers have third party products they prefer to work with. Why do we prefer working with some products, but not other?
Often it comes down to the fact that some products are easier to work with than others. They have better documentation, more intiutive methods and just seem more professional than others. 
A bad API causes neverending support request and will in the end become a liability for a company.
What is a good API
A good API is

• Easy to learn
• Easy to use
• Hard to misuse
• Easy to read 
• Easy to maintain code that uses it
• Easy to extend

General principles when designing an API

• Do one thing and do it well
• Functionality should be easy to explain
• If it's hard to name, consider rethinking the design
• Keep it small
• An API should satisfy it's requirements
• When in doubt leave it out
• Implementation shouldn't impact API
• Implementation details
• Don't let implementation details leak into the API
• Minimize accessibility
• Make classes and members as private as possible
• Names should be self-explanatory
• Documentation mathers
• Document every class, interface, method, constructor, parameter and exception

Exception design

• Throw exceptions to indicate exceptional conditions
• Don't force clients to use exceptions for control flow
• Don't fail silently