10 posts

CDI gotcha Blog

Posted by ljnelson Jul 22, 2010

I learned this the hard way and wanted to make sure other people could benefit.

While putting together a Java EE 6 application, I had put together a @SessionScoped bean that inherited from an abstract superclass.  Both the super- and subclass have injection points.  The subclass uses @Inject; the superclass only uses @PersistenceContext.

Now, I had added the required META-INF/beans.xml file to the jar file housing the subclass, but never thought to add it to the superclass jar file, since of course when I wrote the superclass I wasn't thinking CDI at all (and actually as it happened when I wrote the abstract superclass it was in the Java EE 5 days), so why would I have packaged it into a bean archive?

But it turns out--somewhat unintuitively--that if you inherit from a class that has an injection point in it--even if the injection point is defined in terms of Java EE and not CDI--and if that abstract class comes from a jar that is not a bean archive, then dependency injection by the CDI provider will not be applied to its injection point until you make sure that its jar file contains a META-INF/beans.xml file.

A simpler way to put this is that for any given inheritance chain, all jars in the chain containing classes with injection points must be bean archives.

(On a totally unrelated subject, the documentation links in this post are to the horrific new documentation URLs that Oracle has seen fit to impose on the Java community landscape.  Add your voice to the general din calling for the old URLs to come back after checking out the Twitter E17476 hashtag.)

I wanted to describe an interesting problem I recently faced that involved the most excellent JAX-RS specification and its Jersey implementation.  The quick overview is that we wanted the output of our JAX-RS resource classes to be client-agnostic, but we also wanted the ability to insert a decorator of sorts in between the objects we were returning and the normal JAX-RS serialization/writing process, all without relying on any vendor-supplied extensions.  This turned out to push the capabilities of the JAX-RS specification quite hard, and I thought the experience was worth writing up.  Thanks to Paul Sandoz and Marc Hadley for making appropriate noises along the way.

The Client

Many of you may be familiar with SmartGWT.  This is a truly wonderful AJAX toolkit that provides a GWT wrapper around a robust, battle-hardened Javascript library called SmartClient.  One of its many strengths is its comprehensive support for data binding by way of DataSources.

One such DataSource is the RestDataSource, which is an extremely convenient way to talk to a preexisting back end service.  Its convenience comes at a minor price: to the extent that you use it out of the box, you are bound by its request and response formats.  These are not onerous formats to support, but they do smell like SmartClient, and to the extent you want to not couple your stuff to a given vendor's requirements you might not want to hardcode your output to meet these requirements.  (There are many ways to tweak SmartGWT so that it sends and expects data in ways that you control, but I won't be covering those here.)

The Server

In a project I'm working on, we had the requirement to offer up our API via JAX-RS-compliant web services (I don't want to say REST, because I really really really really don't want to go down that rathole; that's what rest-discuss is for).  We also wanted to not get into the serialization format wars--we wanted to define our resources such that they could be returned via XML or JSON, and according to whatever whims a given client might expect.

That meant (for us) that we wanted our resource class to return simple collections of objects, and leave both the XML (or JSON) serialization to JAX-RS, and--more interestingly--any wrapping or reorganizing behavior to JAX-RS as well.  That is, a given resource would not know that it was being called from a SmartGWT client, even though the SmartGWT client expects XML data in a particular format.

As it turns out, as I mentioned, the requirements imposed by the RestDataSource are pretty mild.  A SmartGWT RestDataSource can indicate, for a retrieval operation, whether it wants paging or not, and it can also specify the start index and the (exclusive) end index of the slice that it wants you to return.  Then it expects that you return a very particular XML payload; consult the RestDataSource documentation for all the details.

The Problems

So we had several problems:

  • How were we going to turn a request like foo/bar?_startRow=0&_endRow=3&_operationType=fetch into something not so SmartGWT-RestDataSource-ish, but preserve the semantics?
  • How were we going to take a Collection<? extends Foo>, as returned by one of our resource classes, and get it ultimately spat out in RestDataSource-friendly XML?

Handling the Request

 First, we focused on the "incoming" problem.

RestDataSource, if not otherwise configured, sends its "fetch" requests with at least three well-known request parameters:

    _startRow=some number
    _endRow=some number

The concepts here are good, but the "row"-ness doesn't really fit with the way we think about things, so we decided to normalize this into a URL format that we defined.  A request like:


would be canonically represented to our resource classes instead as:


To do this, we employed a simple javax.servlet.Filter that used a RequestDispatcher to forward the incoming request to the new URL.  (Note that we did not eliminate the query parameters--they are still there, but our classes never look for them, just as our classes might not look for other query parameters that other client toolkits might define.)

Describing this Filter is probably a subject for another blog entry--suffice it to say this was not hard to write, and I'm not going to cover its implementation here.

Handling the Response

Next, we focused on the "outgoing" problem.

Assuming we have a resource class that returns something, like this:

public class GorpResource {

  public Collection<? extends Gorp> getGorpPaged(@PathParam("pagingControl") PagingControl control) {
    // we'll fill this in in a bit

...how do we turn a Collection<? extends Gorp> into RestDataSource-compliant XML?

RestDataSource XML, it turns out, requires a very specific format.  It looks like this:

  <status>0</status>         <!-- your response status; haven't explored the legal values -->
  <startRow>0</startRow>     <!-- the zero based index that was handed to you -->
  <endRow>10</endRow>        <!-- the exclusive index of the data you were able to return
  <totalRows>400</totalRows> <!-- an estimate of the total size of the domain that your query COULD have returned -->
    <!-- your data goes here in any format you want -->

(It also turns out this isn't exhaustively documented anywhere; it now is in the SmartGWT forums.)

The answer lies with the MessageBodyWriter class.


A MessageBodyWriter is a part of JAX-RS whose implementations are responsible for serializing a resource class's return value into a format that the client can deal with.  Normally a MessageBodyWriter is supposed to be tied closely to its output format.  It's expected, in other words, that if you want to write one of these things, you're doing so because you want to stream your payload in a particular text format, say, or you want to wrestle control away from the JAXB-driven default that JAX-RS ships with.

In our case, we actually didn't want to do this.  We simply wanted to wrap the Collection<? extends Gorp> up inside a wrapper object that would define the RestDataSource "header" and "footer" elements that I hope are evident from the sample text above.  Then in a perfect world we would take that wrapper object, our Collection<? extends Gorp> safe inside it, and hand it back to JAX-RS as though it had been returned directly from the resource class in the first place.  JAX-RS would serialize this wrapper object as it normally would, regardless of how else it had been configured, and everything would come up roses.

It takes a lot of manure to bring up roses.  So I began shoveling.

First, I defined a RestDataSource container object that I labeled--inspiringly--RestDataSourceResponse.  I've reproduced the interesting parts below:

@XmlRootElement(name = "response")
@XmlType(propOrder = { "status", "startRow", "endRow", "totalRows", "data" })
class RestDataSourceResponse implements Serializable {
  private static int defaultPageSize;
  private final int status;
  private final long startRow;
  private final long endRow;
  private final long totalRows;
  @XmlElementWrapper(name = "data")
  private final Collection<?> data;

If I could manage to set this class's data element to our Collection<? extends Gorp>, then serializing this thing would cause SmartGWT XML to go out over the wire.

Next up, I defined a MessageBodyWriter that made use of just about every JAX-RS way of injecting things under the sun.

A bit of background.  When JAX-RS was born, dependency injection was not a new concept but had not been baked into Java EE 6 yet (see JSR 299 for all those gory details).  So JAX-RS has its own way of doing a limited degree of dependency injection.  Oversimplifying on purpose, in general you can put @Context on an instance variable somewhere, and provided it's The Right Sort Of Thing it will be injected for you.

One such Thing that I was going to need in my MessageBodyWriter was an instance of Providers, because that's how you get existing MessageBodyWriters that JAX-RS already knows about.  So high up in my MBW is an instance variable like this:

private Providers providers;

So, now armed with a way to root around in JAX-RS's innards, I had to figure out exactly what an MBW is supposed to do.

Implementing the MessageBodyWriter Contract

The first thing to note is that a MessageBodyWriter takes a type parameter.  The idea here is that you're usually going to create a MessageBodyWriter that knows how to serialize a Gorp instance, for example, and nothing else, so you're going to create a subclass of it called GorpWriter, let's say, and it's going to extends MessageBodyWriter<Gorp>:

public class GorpWriter extends MessageBodyWriter<Gorp> {

But that's not what we had to do, because we wanted to handle everything.  So our MessageBodyWriter implementation had to extend MessageBodyWriter<Object>:

public class RestDataSourceAdapter extends MessageBodyWriter<Object> {

(What's the @Provider annotation?  This is JAX-RS's way of indicating that a given class implements an interface.  By marking a class as a @Provider, you're saying that it is eligible for dependency injection, or, in this case, return from Providers#getMessageBodyWriter().)


The first thing a MessageBodyWriter has to do is to see if it can write a particular thing that is handed to it.  This is handled by its implementation of the isWriteable method.  Briefly, you're handed a return value from some resource class somewhere, along with some--but not all--of the context ultimately available to you from the request, and you get to figure out whether you can handle the thing or not.

In our case, we had to translate.  We had to translate the given object into a RestDataSourceResponse (by wrapping it), and then delegate the question to the innards of JAX-RS:

public boolean isWriteable(final Class<?> type, final Type genericType, final Annotation[] annotations, final MediaType mediaType) {
  boolean returnValue = false;
  if (type != null && !(RestDataSourceResponse.class.isAssignableFrom(type))) {
    final MessageBodyWriter<RestDataSourceResponse> delegate = this.providers.getMessageBodyWriter(RestDataSourceResponse.class, RestDataSourceResponse.class, annotations, mediaType);
    returnValue = delegate != null && delegate.isWriteable(RestDataSourceResponse.class, RestDataSourceResponse.class, annotations, mediaType);
  return returnValue;

The signature here is worth investigating.  The type argument looks to my eyes (after experimentation) like it is the actual class of the returned object from the resource class.  The genericType argument looks to be the declared return type.  Anyway, both are available to you to help you make your decision about whether you want to write instances of these types or not.

The first thing to notice here is that we check to make sure that the type in question is not RestDataSourceResponse.class.  We want to let JAX-RS's normal innards handle the writing of such things itself.

In the case that we are talking about any other class, we ask JAX-RS for a MessageBodyWriter that knows how to deal with RestDataSourceResponses.  If we haven't done anything else fancy with JAX-RS, this will be some default Jersey-supplied JAXB writer of some kind; we just care that it's non-null.  When we get such a delegate, we ask him if he is capable of writing instances of RestDataSourceResponse, which we'll be producing in our writeTo() method (detailed later).


Next up is the getSize() method.  Here a MessageBodyWriter is being asked to compute the size, in bytes, of the payload headed back to the browser.  The specification implies, but does not state directly, that by the time this method is called you can assume that your isWriteable() method has been called and has returned true.

You can punt on this method if you like, and return -1L, but I wanted to be accurate.  To be accurate, I had to take the incoming object whose size is to be calculated, surreptitiously wrap it in a RestDataSourceResponse object, and then hand that back into the innards of JAX-RS so that it can do the size calculation:

public long getSize(final Object object, final Class<?> type, final Type genericType, final Annotation[] annotations, final MediaType mediaType) {
  long returnValue = -1L;
  final MessageBodyWriter<RestDataSourceResponse> delegate = this.providers.getMessageBodyWriter(RestDataSourceResponse.class, RestDataSourceResponse.class, annotations, mediaType);
  if (delegate != null) {
    // CreateResponse basically wraps the incoming object in a 
    // new RestDataSourceResponse
    final RestDataSourceResponse response = this.createResponse(object);
    assert response != null;
    returnValue = delegate.getSize(response, RestDataSourceResponse.class, RestDataSourceResponse.class, annotations, mediaType);
  return returnValue;

This delegation pattern should be quite familiar.  We are, once again, asking JAX-RS to do the dirty work, pretending that the resource has actually returned a RestDataSourceResponse instead of whatever it actually returned.

Now for the fun part.


A MessageBodyWriter has a writeTo() method that actually does the writing of the object.  As you might expect, we're going to implement this by following the same delegation strategy we did for the prior two methods.  But there's an added twist, which is that we need to somehow augment the JAXBContext that's going to tell JAXB how to serialize our response...but I'm getting ahead of myself.

Here's the writeTo method, implemented naively, which, at its heart looks similar to the other two.  I've omitted error checking and logging to keep this short; you would be nuts to do the same:

public void writeTo(final Object object,
                    final Class<?> type,
                    final Type genericType,
                    final Annotation[] annotations,
                    final MediaType mediaType,
                    final MultivaluedMap<String, Object> httpHeaders,
                    final OutputStream entityStream)
  throws IOException, WebApplicationException {
  assert type.isInstance(object);
  final MessageBodyWriter<RestDataSourceResponse> realWriter = this.providers.getMessageBodyWriter(RestDataSourceResponse.class, RestDataSourceResponse.class, annotations, mediaType);
  final RestDataSourceResponse response = this.createResponse(object);
  realWriter.writeTo(response, RestDataSourceResponse.class, RestDataSourceResponse.class, annotations, mediaType, httpHeaders, entityStream);

Now I say "naively", because although this skeleton is correct, JAX-RS is not going to be able to write our response.  Why not?

Welcome to the JAXB Jungle

We are going to detour out of JAX-RS land and into the thorny, tangled jungle of JAXB, which I fear might be thoroughly understood by only the mighty Kohsuke Kawaguchi.

As it turns out, in the project I was working on that drove this blog entry, we make liberal use of interfaces for a whole host of reasons--some good, some bad.  JAXB really really really really really really doesn't like interfaces, and so when you start wanting to have them turned into XML, you run into a whole heap of trouble.  The aforementioned Mr. Kawaguchi has produced the Unofficial JAXB Guide, which seems to be the only source of information on how to get JAXB to deal with interfaces, and, as you can see, it's not trivial.

Additionally, in our writeTo() method above, if we forward all control off to the "real" JAX-RS-provided MessageBodyWriter--the one that will use JAXB by default to do XML serialization--then the JAXB environment within which it runs will contain only the RestDataSourceResponse class (as well as some other boilerplate ones, like java.util.Date and the like).  Notably, it will know nothing about classes referred to by our RestDataSourceResponse, such as, for example, the class of its wrapped object (our Collection<? extends Gorp>).  Gee, it sure would be nice if the "real" MessageBodyWriter would use a JAXBContext built by us that knows all about the type(s) we just wrapped.

What to do?

Getting a JAXBContext: Implementing ContextResolver<JAXBContext>

It turns out that Jersey's implementation of the JAX-RS specification allows us to supply our own JAXBContext that knows about all sorts of types.  To offer it up, we need to provide a ContextResolver<JAXBContext> implementation, known as a "context provider", and that context provider had best be stuffed with every last concrete type we can think of at the time that we go to write our response.

When such a ContextResolver exists, Jersey's innards will grab it and use it to provide a JAXBContext for its internal operations.  Perfect!

So first, we amend our MessageBodyWriter signature so that it also implements ContextResolver<JAXBContext>:

public class RestDataSourceAdapter extends MessageBodyWriter<Object> implements ContextResolver<JAXBContext> {

Conveniently enough, we're already a @Provider, so apart from implementing the getContext() method, we're all set.

Let's think for a moment what we would have to do to get a JAXBContext out of this thing.

We know we'll need to invoke the newInstance(Class...) method.  And we know we're going to need RestDataSourceResponse.class, and the classes reachable from its payload, and--

Of course, we don't have any of that inside the getContext() method.  So before we even get started we're going to have to go back to writeTo() and somehow make that information available outside of it in a thread-safe manner.

Supplying JAXBContext With Classes: Enter Instance-level ThreadLocals

What we want is a container that we can use to grab type information from writeTo() that is also available to our getContext() implementation.  But many threads may be in play.  So we need a thread-safe construct for storing all of these classes that we're going to need to build a new JAXBContext instance.

Near the top of our MBW, therefore, we do this:

private final ThreadLocal<Set<Class<?>>> types;

(It occurs to me, actually, as I write this, that this probably should be a ThreadLocal<BlockingQueue<Set<Class<?>>>>.  But that's just too many angle brackets, don't you think?  http://weblogs.java.net/sites/all/modules/fckeditor/fckeditor/editor/images/smiley/msn/regular_smile.gif  Stay tuned to this blog in case I get burned by this.)

And then, in our writeTo method, we do this:

final Set<Class<?>> typeSet = new HashSet<Class<?>>();
this.processTypes(typeSet, mediaType, type, RestDataSourceResponse.class, genericType, object.getClass());
final RestDataSourceResponse response = this.createResponse(object);
assert response != null;
final Collection<?> data = response.getData();
if (data != null) {
  this.processTypes(typeSet, mediaType, data.getClass());

We'll look at the processTypes() method in a moment.  The gist is that we're grabbing all the type information we possibly can (without doing something silly like introspecting classes), and we're setting it into our instance-level ThreadLocal type set.  Then, later, our getContext() method can use that variable to discover all the types it's going to need.

(The ThreadLocal has to be an instance variable and not a static field because we're interested in the thread that is working on this particular instance of MessageBodyWriter-and-ContextResolver, not any old thread that happens to be working with any old instance.)

Now let's look at processTypes to see exactly what kind of concrete type information we can suck out of the arguments to the writeTo() method without getting too ridiculous.  The gist here is that we take in a Set of Class instances, which we use to keep track of types we've already gathered up, a couple of other boilerplate parameters, and then a variable list of Types that need to be mined for more Class instances.  We recursively plow through this pile until we're all done, and at the end of it all the Set that was passed in will contain all the class information we can possibly infer about the stuff that came back from our resource class's return value:

private final void processTypes(final Set<Class<?>> typeSet, final MediaType mediaType, final Type... types) {
  if (typeSet == null || types == null || types.length <= 0) {
  for (final Type type : types) {
    if (type == null || typeSet.contains(type)) {

    } else if (type instanceof ParameterizedType) {
      final ParameterizedType ptype = (ParameterizedType)type;
      // Recursive calls
      this.processTypes(typeSet, mediaType, ptype.getRawType());
      this.processTypes(typeSet, mediaType, ptype.getOwnerType());
      this.processTypes(typeSet, mediaType, ptype.getActualTypeArguments());

    } else if (type instanceof GenericArrayType) {
      final GenericArrayType gat = (GenericArrayType)type;
      // Recursive call
      this.processTypes(typeSet, mediaType, gat.getGenericComponentType());

    } else if (type instanceof WildcardType) {
      final WildcardType wt = (WildcardType)type;
      // Recursive calls
      this.processTypes(typeSet, mediaType, wt.getLowerBounds());
      this.processTypes(typeSet, mediaType, wt.getUpperBounds());

    } else if (type instanceof TypeVariable) {
      final TypeVariable<?> tv = (TypeVariable<?>)type;
      // Recursive call
      this.processTypes(typeSet, mediaType, tv.getBounds());
      final GenericDeclaration gd = tv.getGenericDeclaration();
      if (gd != null) {
        if (gd instanceof Class) {
          // Recursive call
          this.processTypes(typeSet, mediaType, (Class<?>)gd);
        // Recursive call
        this.processTypes(typeSet, mediaType, gd.getTypeParameters());

    } else if (type instanceof Class) {
      final Class<?> c = (Class<?>)type;
      if (Modifier.isAbstract(c.getModifiers()) || c.isInterface()) {
        /*                  * We'll talk about this in a moment.         */       } else {
    } else {
      throw new UnsupportedOperationException("I don't know how to work with a Type of type " + type.getClass());

I probably overdid this method, since I'm not sure--and none of the Javadoc says one way or the other--what kinds of Types can be supplied to writeTo.

So again, this method recursively calls itself until it finds a concrete Class type, whereupon it adds it to the set.

What about abstract types and interfaces?  Recall that these types are going to be used to build a JAXBContext, and JAXB doesn't like interfaces or abstract classes.

As it turns out, we can use the same ContextResolver magic here to allow other registered ContextResolvers to provide us with concrete classes when they are supplied with interfaces.  This is sort of like dynamically implementing an @XmlSeeAlso annotation.  So the "we'll talk about this" comment above can be replaced with:

final ContextResolver<Class> concreteClassProvider = this.providers.getContextResolver(Class.class, mediaType);
if (concreteClassProvider != null) {
  final Class<?> concreteClass = concreteClassProvider.getContext(c);
  if (concreteClass != null && !Modifier.isAbstract(concreteClass.getModifiers()) && !concreteClass.isInterface()) {

...and now if there are any ContextResolver<Class> implementations lying around on the classpath, they'll be called and will have the opportunity to offer up a concrete class that implements the supplied abstract class or interface.

Putting it All Together

Back to our own ContextResolver<JAXBContext> implementation.  OK, so we've got a place where a bunch of type information is stashed away.  Now all we have to do is use it.  Here's the naive implementation:

public JAXBContext getContext(final Class<?> ignored) {
  JAXBContext returnValue = null;
  final Set<Class<?>> types = this.types.get();
  if (types != null && !types.isEmpty()) {
    try {
      returnValue = JAXBContext.newInstance(types.toArray(new Class<?>[types.size()]));
    } catch (final JAXBException jaxbException) {
      // Here's where you'd log the error.  You WILL log the error, right?
    } finally {
  return returnValue;

JAX-RS's innards will call this method during the JAX-RS-supplied-and-implemented rendering of our RestDataSourceResponse object.  It will probably pass in something like RestDataSourceResponse.class, but, to be frank, by this point we know more about types than even JAX-RS itself does, so we essentially just ignore the incoming parameter in favor of getting our Set of Classes instead.  Once we get our paws on these Classes, we use them to create a new JAXBContext instance, which we then return into the bowels of JAX-RS somewhere, blissfully unaware of how it's going to be used.

If anything goes wrong here, we return null, which is permitted (and encouraged) by the contract to indicate that we're just not a very useful ContextResolver<Class> after all.


Here's the five second version.  This blog entry has shown you how to:

  • take the return value of a resource class
  • stash away JAXB-related type information from it
  • wrap it in a reasonably arbitrary wrapper
  • ask JAX-RS to serialize the wrapper object
  • offer up a new JAXBContext customized for the particular kind of wrapper object

...all without relying on anything other than the JAX-RS specification.

I hope you found this useful.  Thanks for reading, and thanks to Paul Szndoz and Marc Hadley for a great, flexible specification and implementation.



Nimbus and Opacity Blog

Posted by ljnelson Jul 30, 2008

This one tripped me up, and I thought I'd post it here.  I have a case where I need to pour text into a JTextField, but have that JTextField look like a JLabel.  So as I type in one field, I need this "gray" second field to update, live, before the user's eyes.  I also need the ability for the user to cut-and-paste values out of it.  This sort of thing is reasonably common in properties panels and the like.

Now, normally all you have to do is something like this:

final JTextComponent previewComponent = new JTextField();
...and you have what looks like a JLabel but what behaves like a JTextField.

Well, except under Nimbus, where the setOpaque(false) seems to have no effect.  Turns out you need to also set the background color to a transparent color as well.  Fortunately, this combination of behaviors seems to work under all the other look and feels (looks and feels?):

previewComponent.setBackground(new Color(0, 0, 0, 0));

I hope this helps other Swing folks out.


Useful Swing Thing #1 Blog

Posted by ljnelson Dec 17, 2007
See if this little scenario sounds familiar.
You're rolling along on some application somewhere, and you've decided to put some information in a Properties file somewhere.  You realize that you're beginning to encode a lot of information in a property setting, so much so that you realize that really what you're doing is building up a rather complicated Object.  You feel like you've done this before.
Or this one:
You're working on a Swing application, and you need to validate the input from the user.  Great, you say, I'll use a JFormattedTextField, and then I'll...I'll...I'll...read the...documentation...which features lots of...hmm...factories...and AbstractFormatters...and still more formats and navigation thingees and...I think I'll go get some coffee.
Or this one:
You're halfway through developing a complicated and enterprisey validation framework and you stop abruptly, realizing that there has to be a better way!
Starting with this blog entry I'd like to cover the many, many different ways to edit, format and build up different kinds of Objects that are provided by the Java platform.

Why should you think about turning Objects into Strings?  Or Strings into Objects?  Or all the other ways that a user might send input to you?

For me, the answer is that whether you're developing on the desktop or on the Web, you are constantly accepting free-form user input in the form of text.  In some cases, you have control over this text, and in other cases you do not, but in all cases you often need to turn that text into things like dates, colors, fonts, java.net.URIs, custom domain objects and the like.  Wouldn't it be nice to come up with a standard set of tools that would manage this kind of conversion for you in a pluggable manner?  Wouldn't it be even better if most of that heavy lifting were done for you by the base platform?  Well, it is.

In this entry, I'll cover java.beans.PropertyEditor

Hello, first of all.  It's an honor to be part of the java.net weblogging community.

A discussion concerning component reuse brought me back to my philosophy major days in college.  Who knew British empiricism could help you with object design?

The discussion was (is) about, loosely, how best to design an object or a component for reuse.  You want to get the hypothetical object down to what's important across domains, to trim away the fat, but, as a competing concern, to make it rich enough that people won't have to reinvent the wheel.  Slimming down your object also provides incentive for someone else to use it, provided you don't slim it down so far that it's impractical.

What is this "fat" we're talking about?  In general, it's concerns or aspects or facets of the real-world thing that our object is modeling.  There are many facets about a hypothetical and reusable Person object (and the set of all persons that it models), for example, that could be included, ranging from names to measurements to relationships with others.  Which of these groups of attributes is necessary for a Person to be a Person?  Which is superfluous?  What is the Person apart from these groups of attributes?

John Locke examined these issues in An Essay Concerning Human Understanding.  Ruthlessly paraphrased, and butchered somewhat for this weblog's purposes, he argues that when you hear someone mention a person, you frame a "complication or collection" of "simple ideas" in your mind that "go constantly together", such as height, weight, general shape, etc.  In Locke's view we humans in the normal unexamined course of our lives don't imagine these ideas simply existing on their own, so we subconsciously posit the existence of a "substratum" that they bind to, although strictly speaking we never entirely know what we're talking about.  Locke calls this substratum substance, and, believe it or not, it's one way of thinking about object reuse, whether it exists or not.

A couple of choice quotes from Locke on this whole subject:

If any one should be asked, what is the subject wherein colour or weight inheres, he would have nothing to say, but the solid extended parts; and if he were demanded, what is it that solidity and extension adhere in, he would...  [answer] SOMETHING, HE KNEW NOT WHAT.
...[O]ur...ideas of substances...have always the confused idea of something to which they belong...and therefore when we speak of any sort of substance, we say it is a thing having such or such qualities; as body is a thing that is extended, figured, and capable of motion; spirit, a thing capable of thinking; and so hardness, friability, and power to draw iron, we say, are qualities to be found in a loadstone. These...intimate that the substance is supposed always SOMETHING BESIDES the extension, figure, solidity, motion, thinking, or other observable ideas, though we know not what it is.

Let's apply Locke to object design and see where it leads.  Suppose he's right: a person is simply a collection of related attributes or facets that adhere to some substratum.  Let's model this explicitly.

Backing up for a second for contrast, the normal way you would design a domain-independent Person object, assuming for the moment you could, would be to pick some attributes that you thought were sufficiently general and important to be included in this superclass (and here's where you run into problems).  Here, for the sake of brevity, is my silly offering:

public class Person {
  // My selection for an attribute that is important enough to
  // be included in this reusable class.  Yours could be different.
  // Of course that means we'll probably end up not reusing each other's
  // classes.  Hmm.
  private String name;

  public Person() {

  public String getName() {
    return this.name;

  public void setName(final String name) {
    this.name = name;

  // etc.


Of course, picking what those attributes are is what makes reusable object design so tough.

Locke, if he were an object designer, would be a rebel.  He would probably start with the attributes--the collections of simple ideas--and graft them on to some simple "substance" object that would be deliberately designed to be more or less inscrutable.  As it turns out, this is a much better way to achieve object reuse across domains.  Maybe an extreme version of his code would look something like this:

public interface IKnowNotWhat {
  // If only we knew what it was!

public class Person implements IKnowNotWhat {

  public Person() {


public abstract class CollectionOfSimpleIdeas {
  protected final IKnowNotWhat substance;

  public CollectionOfSimpleIdeas(final IKnowNotWhat substance) {
    this.substance = substance;
    if (substance == null) {
      throw new BritishEmpiricismMisunderstoodException();

  public IKnowNotWhat getSubstance() {
    return substance;


public class PersonNames extends CollectionOfSimpleIdeas {
  private String familiarName;

  public PersonNames(final IKnowNotWhat substance) {

  public String getFamiliarName() {
    return this.familiarName;

  public void setFamiliarName(final String familiarName) {
    this.familiarName = familiarName;

  // etc.


public class PersonMeasurements extends CollectionOfSimpleIdeas {
  private int heightInInches;

  public PersonMeasurements(final IKnowNotWhat substance) {

  public int getHeight() {
    return this.heightInInches;

  public void setHeight(final int height) {
    this.heightInInches = height;

  // etc.


The key insight here is that people aren't interested in a reusable Person object at all.  They are interested in different combinations of facets that all concern a person in a particular domain. A financial services programmer doesn't care about a person's weight, but that might be very important to the programmer of an insurance system.  Explicitly modeling a person this way--inside out--lets each domain of attributes stand alone, but also lets them play nicely together when bound together.  What's important is that the attributes are reused, not the substratum.

All of this philosophy has made my brain hurt.  I'm going to go get some lunch (although I know not what).

Filter Blog

By date: