Flapi - A fluent API generator for Java

v2.0

What is it?

Flapi is a code generation library for creating fluent API's in Java. Fluent builders allow developers to more easily interact with your code, using a syntax more akin to natural language. See these articles for more information.

Flapi turns this:

Descriptor builder = Flapi.builder()
	.setPackage("unquietcode.tools.flapi.examples.email.builder")
	.setStartingMethodName("composeEmail")
	.setDescriptorName("Email")

	.addMethod("subject(String subject)").atMost(1)
	.addMethod("addRecipient(String emailAddress)").atLeast(1)
	.addMethod("sender(String emailAddress)").exactly(1)
	.addMethod("body(String text)").atMost(1)
	.addMethod("send()").last(EmailMessage.class)
.build();

...or this:

interface EmailHelper {

	@AtMost(1) void subject(String subject);
	@AtLeast(1) void addRecipient(String emailAddress);
	@Exactly(1) void sender(String emailAddress);
	@Any void addCC(String emailAddress);
	@Any void addBCC(String emailAddress);
	@AtMost(1) void body(String text);
	@Any void addAttachment(File file);
	@Last EmailMessage send();
}

Flapi.create(EmailHelper.class)
	.setPackage("unquietcode.tools.flapi.examples.email.builder")
	.setStartingMethodName("compose")
.build();

...into this:

composeEmail()
    .sender("HAL9000@gmail.com")
    .addRecipient("dave@unquietcode.com")
    .subject("Just what do you think you're doing, Dave?")
    .body("I know that you and Frank were planning to disconnect me, " +
          "and I'm afraid that's something I cannot allow to happen...")
.send();

Getting Started

If you are using Maven (or Gradle, or Ivy) include the following dependency in your build script:

Maven

<dependency>
  <groupId>com.unquietcode.tools.flapi</groupId>
  <artifactId>flapi</artifactId>
  <version>2.0</version>
  <scope>test</scope>
</dependency>

Gradle

dependencies {
  testCompile 'com.unquietcode.tools.flapi:flapi:2.0'
}

In a test define your Descriptor object and output the generated source code. (The Pizza Builder example is a simple descriptor you can start with.) You can also make use of the Gradle plugin, or the Maven plugin, to perform the code generation.

Version 2.x of the project is built against JDK 8, while still exposing a JDK 7 compatible API, and using JDK 8 as the default target for code generation (selectable down to JDK 5). Version 1.x is built against JDK 7, and has a JDK 6 compatible API.

(PSA: If you are still using JDK 7 or lower, please do something about that soon.)

Additional Resources

Documentation
Please visit the documentation page for a tour of Flapi's features and how to use them. (generated using the very nice tool docker)
Examples
Many helpful examples are included on the wiki, corresponding to examples and tests in the src/test directory.
Upgrade Guide
If you started using Flapi before version 1.0, check out this guide to see how to upgrade.
Blog Post
The original blog post describing Flapi.

What's the project's status?

Version 1.0 and 2.0 have been released, marking a huge milestone in the stability of the code. If you started using Flapi before this version, check out the Upgrade Guide to see how to upgrade, since some deprecated features have been removed. See the Release Notes for the full release notes.

Going forward, the 1.x line will only receive important fixes and updates, with all new development firmly rooted in 2.x / JDK 8.

Problems?

Use the issue tracker to report problems encountered or new feature requests.

Contributing

Feel free to fork the project and fiddle around! Submit pull requests to improve the code.
Create issues to help support the project. Ask questions. (Say hello.)

Bitcoin

If you like this software and find it useful, then please consider supporting my efforts through a donation via BitCoin or other means.

Special thanks to Concurrent, Inc. for their feedback and support as a user of Flapi, which they use in their Fluid library for Cascading.

License

Flapi is licensed under the Apache Software License (ASL) 2.0

Thanks!

Peace, love, and code.

UnquietCode/Flapi