Description John Cortell 2010-09-29 18:40:24 EDT

In the EDC API, a frame object is described using a property bag (a Map<String,Object>). E.g.,

 // EDC adopter must implement this
  protected abstract List<Map<String, Object>> computeStackFrames();

If this method would at least describe in javadoc what sort of properties are expected in the bag, then the situation wouldn't be so bad; the EDC adopter would at least know what to provide. But it doesn't. And of course, the property bag is passed around quite a bit. So, to duplicate that documentation in all those places is clearly not a good approach. For this reason, I dislike this sort of API. A slight variation can keep the flexibility intended by the API but make it much more intuitive to use:

  protected abstract List<EdcStackFrame> computeStackFrames();

   /**
    * A stack frame described as one or more of the following 
    * properties, plus any additional custom properties.
    * 
    * <ul>
    * <li>{@link StackFrameDMC#LEVEL_INDEX}
    * <li>{@link StackFrameDMC#ROOT_FRAME}
    * ...
    * </ul>
    */
   public class EdcStackFrame  {
      public Map<String, Object> props;
   }

Clearly, this would be API breaking stuff, but I think we're still at a point where adoption is low and this sort of improvement is not only doable but necessary in order to make the framework more usable. 

This improved pattern may be applied to other aspects of EDC. I see other things being passed around as opaque property bags (threads, breakpoints). Any such adjustments will be done via dedicated bugs reports. This one only addresses EDC stack frames.