use PECS principle in TreeTraverser

Currently, TreeTraverser<T> has a method Iterable<T> children(T root). Since for traversal, the returned Iterable is only used as a producer, the return type can be Iterable<? extends T> (and the using() static function can take a Function<T, ? extends Iterable<? extends T>>).

The use case is a tree model where at some level only leaf nodes exist, so there is for example a List<LeafNode> (where LeafNode extends T). With the current implementation, this has to be copied into a new list in order to compile (or using some ugly unsafe double-casting).

[HermanBovens]

@kevinb9n, Personally I feel that users who test with such fine granularity have to accept the extra brittleness, certainly for an API that is in beta. After all the fix is trivial (just change the variable type). Of course, they could also just pass a Java8 method reference to TreeTraverser.using(), and then test the method directly.

[HermanBovens]

Indeed, my uses cases were along the lines of the example that @perceptron8 has shown. Another possibility (besides having the wildcard in the superclass’s return type for getChildren()) is that the function to map parent to children uses instanceof and a (clean, safe) cast to distinguish between different types, some of which may return a specific type of children.

Regarding the use of Set vs Iterable: the fact that one needs to copy the children in case the model doesn’t return a Set is one thing that worries me a bit. The fact that one will need to copy them specifically into a LinkedHashSet (or similar Set implementation) in order to preserve the iteration order of the model, is another thing. Uses cases where the order is important: DOM traversal, UI component hierarchy, …