Thursday, July 28, 2016

Writing Effective Exception Descriptions


Writing exception descriptions are not really taught in programming classes but are vitally important in the field.  Namely if you need to refine your descriptions to find a problem it can lead to multiple pushes to a production environment before you actually fix the problem.  Depending on the issue this could waste valuable time.

Between reading about how to write good exception descriptions from various companies and my personal experience I've accumulated the following tips to share.  Note that most of the time exception text bubbles into your log files so some references to log files will be mentioned as well.

Be Layer-Centric

If you catch an exception and re-throw, describe the problem in the terms of the current (throwing) layer.  As an example, if you are writing TCP/IP library code and catch an IP exception, state your TCP problems.  If you are (ab)using TCP for Inter-Process Communication (IPC), state the process you are trying to reach.  I have mistakenly thought there was a networking error when a program couldn't connect to localhost before.

Not a Singleton?  Include your object ID

Imagine a case where there is a complex object with invariants.   With two instances of the class logging at the same it could easily appear to violate it's invariants or demonstrate impossible behavior.  Imagine your TCP class logging that it closed the connection and then that it read data successfully - this could be very confusing.  With object IDs you would log that client 1 closed the connection and client 2 read successfully - this makes much more sense.

Multi-threaded?  Include your Thread ID

Some times you need to trace the execution flow in a particular thread.  If you do not include your Thread IDs this is an impossible task to do via the logs.

Don't Trust Library Exceptions

Frequently exceptions generated by library, module or component code is not very descriptive.  Continuing with the networking examples I've had many HTTP exceptions with no more description than "Bad Request".  Note the lack of IP address, host name, or port.  Given that exceptions turn into logs that then can go into various applications (e.g. Splunk) I think the descriptions are generic due to security concerns.

Include Some Variables

Try to include one or two other things to help you track down a problem, knowing WHAT from following the recommendations above won't necessarily help you figure out WHY.

Make it easy

When you write your subclass consider including a String.format style constructor.  This would let you avoid having to do a String.format call on every exception you need to throw.  Alternatively you could make an ExecptionDescription builder that includes the object ID and Thread ID automatically.


In conclusion if you plan ahead and write descriptive exception messages that let you track the instance, the thread and some internal state you will be able to diagnose (possibly critical) issues much faster.

Tuesday, July 12, 2016

Overview of JSON Libraries and How to Choose a Library


It's good to be back.  The blog had an expected hiatus while I moved to a new city, also around Seattle.


Many of my posts are about overcoming unexpected difficulties when using some software library or module or another.  I decided to take a step back and try to select a quality module in the first place.  This is my analysis of the JSON libraries I was able to find and can count as a how-to to select a library in general.

The short result is that if a Library is in Maven, you can look at Maven Central to see how popular a library is and how frequently it is updated.  Then you can use one of the most used and updated libraries out there.  You can also consult StackOverflow.  Here are some examples.

The List

  • JSR 353 - We have javax.json-api and org.glassfish/javax.json.  Out of these two the
    This could be you!  Image from

    org.glassfish one has more users and more updates (version 1.0.4 vs 1.0), so it is the winner so far.
  • Fast-XML Json Parsing / Jackson has many more updates (version 2.8), is far more used and the updates are fresher.  That makes it the winner so far.
  • JSON-Simple is comparable to the JSR 353 libraries.  If not for the Jackson library you could choose based on how well prior Google libraries have worked vs Oracle libraries.
  • org.json falls between Jackson and the JSR 353 libraries with about 700 users and a release in Feb of 2016.
  • Google GSON has about 2000 users and was updated last month.  This puts it on par with Jackson.
  • quick-json has 0 users!  This would make it almost unqualified even if there were no alternatives.
  • JsonPath - Lastly, JsonPath has a couple of hundred users.


Now, you may be skeptical of the Wisdom of the Crowd (e.g. appeal to the people or groupthink) but more users means that there is a higher chance someone found the same problems that you have.  Even in this day and age Googling an error string can still produce 0 results.
Based off of this my project is using Jackson and hasn't had any problems with it for months.

Next Steps

Once you have your JSON library picked out, how do you manipulate it?  I've had good luck using, although in the options you have have it add annotations... which makes it a non-POJO technically...