Tag Archives: api design

SBinary backends

I’m thinking about changing the scope of some of the code for SBinary.

Specifically, you remember that part where I said “SBinary is only for serializing objects and manipulating binary data, and it’s going to remain super minimal and specialised and this will never ever change!!”? I’m thinking of changing that. :-)

The reason for this change of heart is that I’m realising how incredibly generic the constructions you put together for SBinary are. You’re basically creating a walker for deconstructing and reconstructing your entire object graph. That’s pretty damn powerful. In particular I was thinking about how to modify formats to permit sharing (another post on that will be forthcoming) and suddenly thought “haaang on a minute. I’ve written this code before”. It looks suspiciously identical to some Java code I wrote a while back for generic cloning of object graphs*. A simple rebinding of the backend to use a queue of objects rather than input and output streams would give a pretty efficient deep clone mechanism. I’ve also been thinking of creating a JCR backend which mostly works the same as the binary data (indeed, most data would probably be stored as binary blobs in the JCR), but allows for references to other nodes (and would use this for data sharing).

At the very least, this will result in ditching the explicit dependency on java.io. It will still be used extensively in the back end, but this is only visible in the API for the parts that actually need to interact with it. (most likely approach – have an Input and Output opaque type to replace DataInput and DataOutput. These will just be wrappers around the java.io types, but this won’t be visible at first)

If I do do something like this, it would still be with making binary data the priority, and there would definitely be a specialised binary frontend which should be just as convenient as the current API. If it ever looks like feature creep is threatening to destroy that I’ll separate out projects and/or cut out the idea entirely.

* In the unlikely event that anyone who worked on that project actually reads this blog, they will probably shudder in horror at the mention of that code. It was very fragile with regards to changes in the rest of the code. But that wasn’t actually an issue with the cloning – it was an issue with the post-clone processing. The graph was of database mapped objects and it needed to be partially linearised in order to insert it back into the database due to constraint issues, and this never really worked right.

This entry was posted in programming and tagged , , , on by .

Good APIs

At least in the Java world[1], good APIs are very rare. The vast majority of the APIs I’ve used in Java are at best mediocre, and I’ve run into some real stinkers (No fingerpointing here, but a lot of them are even in the standard library!).

Part of this is the fault of the language. Java code… tends to be ugly. It’s not a language which lends itself to really flexible syntax, and so you have to work really hard to produce powerful abstractions which are actually nice to use.

The only APIs I’ve encountered so far which have really made me sit up and go “Wow, that’s well designed” are Google Guice and Joda time. They have well thought out class hierarchies, good object oriented style[2], sensible use of fluent interfaces / method chaining and just generally well thought out interfaces and names.

They’re not perfect by any means, but they show promise that it really is possible to write good APIs for Java.

Anyone else know of other similarly well designed libraries?

[1] And, unfortunately, I lack much in the way of non-trivially large development in other languages. The Parsec API is nice, ‘though it gives me a headache sometimes. Haskell libraries in general look rather pretty, though I suspect that’s more a function of the language than the API design. I’m not really experienced enough in it to judge good API design.

[2] I’m not an OO fanatic. It has advantages and disadvantages, and sometimes you just want to use a different approach (I rather like FP for example). But one thing I’ve observed is that if you do it right, OO can have the effect of producing some astonishingly readable code. I don’t know either well/at all really, but this style of design seems much more common in Ruby, smalltalk, etc.

This entry was posted in programming and tagged , , , on by .