Getting Started

Basic Concepts

Flapi builds what is called a descriptor, which it then uses to build the Java code model and generate the classes and interfaces of a builder. A Descriptor is comprised of blocks and methods. A block contains methods. Each block can in turn nest other blocks inside of it. Blocks can be reused by using their name later in a addBlockReference(...) method, which connects the blocks logically without requiring redefining them.

A method or a block can also include a block chain. These are used to attach new or existing blocks to a method (or block constructor), providing a simple chaining mechanism. A block chain must be passed through before the block itself is reached, or the method returns to its parent block.

Methods have several ways of operating, based on their allowed invocations:

• any() - can be called any number of times
• atLeast(x) - must be called at least x number of times
• atMost(x) - can be called at most x number of times
• between(x,y) - must be called at least x times and at most y times.
• once() - alias for atMost(1)
• last() - can be called exactly once, and will cause the block to return

More about that last() method, every block must contain at least one of these. If not, an error will be thrown when the descriptor is built. This makes sense, as without a last() method your block would never be able to exit. Developers would be stuck in an infinite loop where all they could do was keep chaining more and more methods together!

Phew, that was a mouthful! Let's summarize:

• Descriptor ** is itself a block ** contains blocks and methods
• Block ** contains blocks and methods ** has a method which is its constructor within the parent context *** means that a block too can have invocation restrictions ** can be referenced in the addBlockReference(...) methods later without having to redefine
• Method ** can return to the same block, or return to the parent block *** can also register an invocation towards some maximum, which moves horizontally to a new interface ** can add block chains to create a sequence of blocks to pass through before completing (or continuing to the block in the case of a block constructor)