Declaring graphs - gkresic/commons-fields GitHub Wiki

For declaring "field graph" (set of fields describing attributes of some object together with all its sub-objects, their sub-objects etc.) commons-fields uses FieldGraph - simple immutable implementation of "hierarchical" Set interface coupled with some useful builder patterns.

In its most simple use case, FieldGraph can be constructed much like regular EnumSet:

FieldGraph<Foo.Field> SimpleGraph = FieldGraph.of(Foo.Field.number, Foo.Field.list);

Note that this way of appending field which describes sub-object, will result in sub-object with only id set:

FieldGraph<Foo.Field> RefGraph = FieldGraph.of(Foo.Field.bar);

Such objects can be described as "references" and can be later expanded with additional attributes. More on entity expansion later.

There are also other EnumSet-like methods like noneOf, allOf, complementOf etc.

For building field hierarchy, FieldGraph.Builder should be used:

FieldGraph<Foo.Field> FullGraph = FieldGraph.Builder.of(Foo.Field.class)
   .add(Foo.Field.number)
   .add(Foo.Field.list)
   .add(Foo.Field.bar, FieldGraph.Builder.of(Bar.Field.class)
       .add(Bar.Field.one)
       .add(Bar.Field.two)
       .add(Bar.Field.three)
       .build()
   )
   .build()
;

Note that FieldGraph.Builder.add supports appending complete sub-graphs in form of other FieldGraphs which will merge appended graph to already initialized one:

FieldGraph<Foo.Field> MergedGraph = FieldGraph.Builder.of(Foo.Field.class)
   .add(Foo.Field.number)
   .add(Foo.Field.list)
   .add(FooEditor.Graph)  // merges complete graph
   .build()
;

Use this pattern when you are sure that objects you resolve will be used by another component for which you in advance know which field graph it requires (and thus, spare that component from performing subsequent object expansion).

As already said, FieldGraph implements the standard Set interface for accessing first-level fields. To access sub-graph for a field that has it, use getGraph method:

FieldGraph<Bar.Field> SubGraph = FullGraph.getGraph(Foo.Field.bar, Bar.Field.class);

FieldGraph can be (de)serialized to/from string using toString() and of(String, Class). String representations use comma as field delimiter and curly braces for declaring sub-graphs:

number,list,bar{one,two,three}