(Imported from Google Code)
DDMSence was designed for reading existing DDMS records or writing new ones. The immutability of the objects makes it difficult to work with a third use case: reading an existing record and then editing it.
Consider ways to support this use case while maintaining strict validity of objects.
Need to take a close look at the "uninitialized vs. empty" logic and reevaluate whether it makes sense for a commit() to return null. Especially in the GeospatialCoverage hierarchy, this could lead to fragile code.
Rev 339 adds GeospatialCoverage and updates all Builders to return null when empty (via an isEmpty() method on each Builder). This allows parent component builders to consistently handle empty child builders.
Summary of notes to date:
Every DDMS component has a Builder class which also implicitly handles the creation of child components. No special handling methods are added for List-based properties, because some lists can have duplicates. Instead, Builders search for empty entries in Lists and skips them instead of failing on them. This rule points out the major difference in the three methods of creating components:
1) From a XOM element: Takes XML already validated from the schema and loads it into the object model.
2) From the constructors: Build Resources from the bottom-up, getting immediate errors when something is wrong.
3) From the Builders: Build Resources from the bottom-up over time, getting errors at the very end, and ignoring components that are completely empty instead of erroring out.
This also means that it does not make sense to privatize the constructors at all. This will also preserve backwards compatibility to v1.4.x.
ExtensibleElement is handled as a straight String-to-XML formbean. ExtensibleAttributes uses XOM Attributes, which are already mutable.
Still To Do:
Add a Builder to the top-level Resource class.
Update Escort code to use Builders.
Update Escort tutorial to describe Builders vs. Constructors.
Update Essentials JavaConvertor code to use Builders
Rev 340 completes the components with Resource. I'll work on the unit tests for Resource tomorrow.
Need to look at the ton of repetitive boilerplate code in Resource and see if it makes sense to refactor (see also, Issue #60).
Rev 341 adds Resource unit tests and cleans up a lot of the Resource.Builder repetitive code by extracting an IBuilder interface for all of the top level components.
At this point, the core library is code complete, although additional bugs may reveal themselves as I start working on the tutorials and documentation.
Rev 344 updates documentation with a new Power Tip. After consideration, I opted to keep the Escort tutorial intact, because it is conceptually simpler for a new user. The new details about Builders can be found in a Power Tip.