Re: [cdt-dev] EDC objects described via property bags

[<ken.ryall@xxxxxxxxx>]

Title: Re: [cdt-dev] EDC objects described via property bags

+1. I think this would be a nice improvement for all the reasons you mention.

---

From: ext John Cortell <rat042@xxxxxxxxxxxxx>
Reply-To: "CDT General developers list." <cdt-dev@xxxxxxxxxxx>
Date: Wed, 29 Sep 2010 20:37:57 +0200
To: "CDT General developers list." <cdt-dev@xxxxxxxxxxx>
Subject: [cdt-dev] EDC objects described via property bags

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;
   }

Any objections to using this pattern throughout EDC? 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?

John