Extending builders: PathBuilder

[Matthieu BROUILLARD]

Hello all,

For me the strength of builder is that the user of the builder might not
ask himself what the methods are doing, they have to be self explaining and
there should be no ambiguity when using them.
>From this then I would say that all the "final" methods in a builder should
return not the builder itself but the built object.
For example, if closePath() marks the end of the Path being built then just
return the built Path and not the builder.
For elements(), I have no strong arguments that either it should :

   - contribute by adding path elements in the current path (like Michael
   Paus suggests in the last comment of the issue)
   - be a full replacement of everything done before and then probably be a
   final builder method
   - be splitted in addElements(...) & replaceElements(...) which are more
   self explaining

Personnaly, I would prefer the first one as it seems more natural to me.

Another way also to clean the builders API in general can be to use some
more interfaces. PathBuilder as filled in the Jira allows 2 categories of
methods, the ones adding path elements and the ones modifying the graphical
properties of the path being built.
Saying that we could have it turned into:

PathBuilder implements PathPropertyBuilder {
    ...
    PathBuilder lineTo(int x, int y);
    PathBuilder addElements(PathElement ... elements);
    PathPropertyBuilder  replaceElements(PathElement ... elements);
    PathPropertyBuilder  closePath();
    ...
}

PathPropertyBuilder {
   ....
    strokeWidth(int width);
    strokeColor(Color c);
    ....
    Path build();
}


Perhaps my suggestions does not help you directly to take a decision, but
as you asked for opinions, I give mine :-)

Matthieu Brouillard