Helpers

When Flapi generates your API, it creates what is effectively skeleton around which you can implement the required functionality. Each block results in the creation of a Helper interface, which defines a sort of callback mechanism for each of the methods in the block. As methods are called on the builders, they are called on the helpers. This means, for example, that as the builders transition between blocks their underlying objects can be created and maintained.

As an example, consider this block which contains three methods, one of which starts a new block via a reference:

.startBlock("SomeBlock", "block()").any()
    .addMethod("one()").last()
    .addMethod("two(int value)").any()
    .addMethod("nothing()").last()
.endBlock()

When the descriptor that contains this block is generated into source code, an interface will be generated called SomeBlockHelper. The interface will have three methods: one(), two(int value) and nothing().

Implementing the Helpers

Flapi only creates the interfaces for the helpers. The next step is to implement these in such a way as to support the behavior of your builder. It is possible to create any number of implementations based on the helper interfaces, supporting various behaviors using the same builder interfaces.

When instantiating a new builder via the builder's *Generator class, you must provide the helper interface. As well, from within your helpers you must assist in instantiating any other helpers needed, and store them in the AtomicReference method parameters provided.

For terminal methods returning a type, you will have to provide the value via the return value of the helper method. Any other logic and behavior in your descriptors is entirely up to you. Flapi only cares that it has the object instances it needs when descending into new blocks, and that it has the return values from your helper when exiting the builder.

If you decide to modify your descriptor later, the *Helper interfaces will be updated. Your implementations will therefore have to change as well , but the existing work, the logic behind your builder, is entirely preserved. Upgrades are a snap!