API design style I've never seen before - would you use it?

Question

I was Googling for examples of a "Bean Comparator" and came across this strange API design I've never seen before (is it just me?). I'm curious if you have seen it before and what you think about it?
[http://cojen.sourceforge.net/apidocs/org/cojen/util/BeanComparator.html]
The basic problem is to create a Comparator that can sort on multiple fields within a given class.
First, a more traditional(?) API design might be something like:
Constructor Summary:
     BeanComparator(Class theClass);
Method Summary:
     addSortField(String fieldName, boolean isAscending, boolean isSortNullHigh);
     addSortField(String fieldName); // convenience method with default ascending and sortNullHigh
So you could create a BeanComparator that sorts on multiple fields by using:
BeanComparator bc = new BeanComparator(SomeClass.class);
bc.addSortField("field1");
bc.addSortField("field2", false, true);
bc.addSortField("field3", true, false);Finally, without listing the API, the equivalent code for the "strange API design" would be:
Comparator c = BeanComparator.forClass(SomeClass.class)
     .orderBy("field1")
     .orderBy("field2")
     .reverse();
     .orderBy("field3")
     .nullLow();So in this case:
a) there is no explicit "add" method to add a new sort field. The "orderBy" is an implicit add.
b) the reverse() and nullLow() methods only apply to the current orderBy field.
c) the creation of the class is "sequential" in nature as each method needs to be invoked in the proper order
In some ways this seems to simplify the API because you don't need lots of convenience methods or your don't need to use the full method and then restate the default values.
Also you can add new sort options to the API without affecting any existing methods.
What do you think of this type of API design?
Have you ever used it before?
Would you consider using this design and in what situations would you consider it?

Answer 1

What part is bothering you exactly? Its not that it bothers me, its just that it is "different" and I was wondering if it is an acceptable design of a class and when you would use it, since I don't think I've seen any examples in the JDK.
Usually the order of method invocation is not important. You can do:
component.setFont()
component.setBackground()or
component.setBackground()
component.setFont()However
orderBy()
orderBy()
reverse()is not the same as
orderBy()
reverse()
orderBy()So the API implies a "building" approach where you need to know you are building the components of the class in a certain order.
Again, its not bad, its just different (to me) so I was wondering if it is common and when you would use it.
The fact that the methods return the object itself...No, I've seen that pattern before and find it handy.
Your example (addSortField) also depends on the order in which the methods are called.Yes, but this is normal for most APIs. For example adding items to a Vector, or components to a panel.
In this case the orderBy() method implies a change of state because the next set of methods may or may not modify the state of the field being ordered.
Again, I said I thought that this potentialy does simplify the API, but I have not seen it used before.
I don't see the design as much of a problem. Me either.