Thursday, March 28, 2013

For API Nerds: Interfaces and Inner Classes

This article is for API developers only. If you're writing an application, you may not care about APIs, because you probably don't have any. But if you're writing a library that others will use, public API comes into play.

API is like a pile of laundry: you can either spread the huge, reeking mess out all over your floor, or you can stuff it into a nice, clean hamper. While the first approach provides the convenience of being able to select each day's pre-soiled attire quickly, since it is arrayed out in front of you when you get out of bed, the second solution presents a clean interface to people that make the mistake of walking into your pathetic, slovenly life.

Good APIs prefer hampers.

I was implementing a new piece of API and functionality and wondered the following: Is there any reason to not put my implementation (which I did not want in the public API, and which would be the only implementation of said interface) inside the interface itself? It seems odd, perhaps, maybe even a bit tawdry, but is there anything wrong with it?

My motivation was simple: I'm adding this API and implementation into a package that already has many classes to wade through. Should I bother adding more noise to the list for an implementation detail of this single interface? Why not put it into the interface file, and just bundle up that implementation in a logical place, tightly bound to the interface that it implements?

So I did this, coming up with something like the following:

public interface A {
    void a();

    static class AImpl implements A {

        public void a() {
            // ...

Additionally, an existing class exposed a single method giving a reference to this interface:

public A getA() {
    return new AImpl();

This worked well - the users of the public getA() method got what they needed: an object of type A with its spectacular, if slightly under-documented, method a(). And I successfully hid the implementation class inside of this same file, as a package-private static class, saving my package the unbearable burden of yet another file.


Then I ran JavaDocs on my project and realized my mistake: my supposedly package-private implementation class was now part of the public API, showing up as the public class A.AImpl. What th-... I didn't say it was public! In fact, I explicitly made it package-private, so that the class exposing the new getA() method could instantiate an instance of that class. So what happened?

Interfaces happened. Interfaces do not use the same access rules as classes. Instead, all members of an interface are public by default. So while I used the correct (to my mind) syntax for package-private access, I was actually using the correct (to the mind of my interface) syntax for declaring that inner class public, and the JavaDocs did the rest.

Do I hear you yelling, "You could make it private!?" Or is that just the echo of my internal shouting when I first saw the problem? This is what I tried to do. This fails for (at least) two reasons. One is that I actually needed this class to be package-private (not private), so that I could instantiate it and override it from outside of this interface. An even better reason is that you cannot declare different access permissions than the default that the interface uses. In this case, that means that I cannot have a public interface with a private inner class. I could declare the entire interface to be private... but that defeats the whole thing I was going for by exposing the interface A as a public API.

There are other ways around this. For example, there is a mechanism we use in Android framework code, @hide, to solve the problem of having to expose API internally but not wanting it to be a part of the public API (a workaround for the language not having the ability to differentiate between internal and external access to library APIs). But at the point where I considered using this workaround, the awkwardness of putting the class inside of the interface just got to be too much.

In the end, I just pulled the class out and put it at the same level as A. It added another file to the package, but that really wasn't that big a deal anyway. And it was certainly better than the mess I was creating with my class-inside-interface approach.

The moral of the story is: API design is tricky. Consider not only the internal implementation details ("Can I make my life easier by implementing the solution in this particular way?"), but also (and wayyyyy more importantly), "Can I make the API, and therefore the lives of external developers, better by doing it in this other way?"

Here is a technical diagram, illustrating the problem and the original solution:

Friday, March 22, 2013

DevBytes: Layout Transitions

The LayoutTransition class (added in Android 3.0) enables easy fade/move/resize animations when items are added to or removed from a ViewGroup, usually with just one line of code. This video shows how this works and also shows the new ability added in JellyBean (Android 4.1) to animate other changes to the layout as well, not limited to items being added or removed.



Friday, March 15, 2013

DevBytes: PictureViewer

PictureViewer: How to use ViewPropertyAnimator to get a cross-fade effect as new bitmaps get installed in an ImageView.

TransitionDrawable is a handy and easy facility for cross-fading between two drawables. But if you want to cross-fade between an arbitrary set of images, you might want something more general-purpose. Here's one approach.



Friday, March 8, 2013

DevBytes: Request During Layout

Horrible things can result from calling requestLayout() during a layout pass. DON'T DO THIS.

The demo that I wrote to show why this is bad seems very contrived, but I have since run across application code that did nearly the exact same thing, explicitly calling requestLayout() during onLayout(). Ugh. Typically, the cases where this problem occurs are a tad more subtle than that.



Thursday, March 7, 2013

Crystal Methodology: The Future of Software Development Process Methodology Effectiveness

Most people that know me know that I can't say enough about process. In this presentation at Devoxx 2012, I tried to change that.

If the embed below isn't working for you, you can watch the talk on the site.