Business Flows

A combination of the Try monad and the Either monad, to help tame complex business flows

Example Usage 1 (thanks @tjheslin1)

Example Usage 2 (thanks @hanfak)

Frequently asked questions

What is it?

A small Java 8 library that can help you to model a 3-part (happy/sad/exception) business flow. No more try-catch blocks if you don't want to use them!

When should I use it?

If you have a flow that fits into the "two track" model, as spoken about by Scott W in his Railyway Oriented Programming model, which this library owes a lot to. This library has 3 tracks instead of 2; the third is supposed to be reserved for "stuff that is never supposed to happen" in the form of uncaught exceptions.

When should I not use it?

There is no point in using this if your flows are "all or nothing". If there are no expected sad paths and all failures are exceptional circumstances, then this is not a good fit. The Try monad is a better fit. You could use e.g. better-java-monads instead.

How to get it?

<dependency>
    <groupId>io.github.theangrydev</groupId>
    <artifactId>business-flows</artifactId>
    <version>10.3.0</version>
</dependency>

Releases

The versioning scheme follows Semantic Versioning 2.0.0, to help you identify non backwards-compatible changes when you are upgrading.

10.3.0

• Added BusinessFlow.isTechnicalFailure method to complement the existing isHappy and isSad methods
• Added BusinessFlow.getTechnicalFailure method to complement the existing getHappy and getSad methods

10.2.0

• Starting to document the API with some new annotations @ApiFeature, which describes ApiFeatureStability for a version in the ApiVersionHistory. These features are EXPERIMENTAL and may be removed at any time

10.1.1 to 10.1.12

• Experimenting with the release process and generating documentation, no functional changes

10.1.0

• HappyPath.happyPathAttempt now accepts any BusinessFlow, not just a HappyPath, which is useful when you have a collaborator that returns a BusinessFlow that is not a HappyPath view (closes #13)

10.0.0

• This release picks up where 8.3.0 left off, just reverting the version 9.0.0 and 9.1.0 changes

9.0.0 and 9.1.0

• These releases were a failed attempt to remove the HappyPath.happyAttempt method that takes an Attempt<Happy> parameter (see #12)

8.3.0

• Add methods consume and consumeOrThrow to end a flow by performing some action that ends in a void (closes #8)

8.2.0

• Add methods to help with multiple return style: isHappy, isSad, getHappy and getSad (closes #10)

8.1.1

• throwItAsARuntimeException and throwIt should not be void (closes #5)

8.0.0

• Removed the Bias parameter from BusinessFlow to make it more viable to use as an unbiased return type, instead of having to wildcard the types as <Happy, Sad, ?>. This is a breaking change.
• Made the then methods accept ? extends BusinessFlow.

7.6.0

• Exposed some methods on PotentialFailure to make it easier to test when it is the return type of a method. This involved extracting a WithOptional interface that is used by PotentialFailure and BusinessFlow.

7.5.0

• Added helper method HappyPath.actions that turns an array of ActionThatMightFail into a list. This is a workaround for the fact that interfaces can't have @SafeVarargs and so some methods accept a list when they would ideally accept varargs

7.4.0

• Added HappyPath.attemptAll convenience method that is equivalent to multiple chained attempt calls

7.3.0

• Added method TechnicalFailure.throwItAsRuntimeException that will throw a RuntimeException if the business case is a technical failure

7.2.0

• Added method TechnicalFailure.throwIt that will throw an Exception if the business case is a technical failure

7.0.0

• Changed Validator so that it produces just one failure not a list of failures
• FieldValidator now adapts just one Validator not a list of them to match the Validator change
• Renamed ValidationPath methods from validate* to validateAll* to make it clear that they run all the validators not just until the first failure

6.2.0

• TechnicalFailureCase.toString now includes the stack trace

6.1.0

• Added method BusinessCase.toPotentialFalure that turns a BusinessCase into a PotentialFailure

6.0.0

• ValidationPath now has a SadAggregate type parameter that defaults to List<Sad> and can be used to map validation errors into an aggregate. ValidationPath now has a SadAggregate type parameter that defaults to List and can be used to map validation errors into an aggregate. There are corresponding validateInto methods in ValidationPath that allow specifying a Mapping to a SadAggregate and validate methods that default to List<Sad>. This change is not backwards compatible

5.1.2

• Helper methods for FieldValidator to cope with the case that a common field name should be passed to validators so they can use the name in the validation message

5.0.0

• Validation revamp. Helper FieldValidator for field validation, a new Validator type, PotentialFailure.failures helper method and ValidationPath helper methods. This change is not backwards compatible

4.0.3

• Updated javadoc and license headers

4.0.1

• Inline methods to make debugging easier (closes #1)
• Removed varargs methods from ValidationPath. This change is not backwards compatible
• Removed andThen methods from Attempt and Mapping. This change is not backwards compatible

3.1.1

• Optimized overrides for ifHappy etc (closes #2)

3.1.0

• Allow ? extends ActionThatMightFail<Happy, Sad> in the ValidationPath

3.0.2

• Made PotentialFailure.toHappyPath package private since it is only supposed to be used internally

3.0.1

• License headers updated

3.0.0

• Using a new class PotentialFailure to represent the result of an ActionThatMightFail instead of an Optional. This change is not backwards compatible

2.7.1

• Updated javadoc

2.7.0

• If a technical failure occurs while joining to happy or sad, it is joined to a technical failure instead

2.6.0

• Unchecked version of join with only happy and sad joiners has taken the join name. The checked version is called joinOrThrow now

2.5.0

• Recovery methods no longer need to be e.g. exception -> sad, they can choose to ignore the parameter and just supply a value, e.g. () -> sad

2.4.0

• Added HappyPath.happyPathAttempt to cover the case where the entry point to a flow is a method that could e.g. return either HappyPath.happyPath or SadPath.sadPath and may also throw an uncaught exception

2.3.0

• Made all the static factory methods for HappyPath, SadPath and TechnicalFailure public so that it is possible to do e.g. HappyPath.sadPath(sad) to get a happy biased view of a sad path without having to do SadPath.sadPath(sad).ifHappy()

2.2.0

• Updated javadoc

2.1.0

• HappyAttempt now has an exception to technical failure factory method and an exception to sad path factory method

2.0.0

• Switched order from <Sad, Happy> to <Happy, Sad> because it is more intuitive to users. This change is not backwards compatible

1.1.0

• Added another join method in which you can omit the technical failure mapping and allow it to be thrown as an Exception
• Reduced visibility of methods that should have been private

1.0.1

• Changed orElseThrow so that it throws X extends Exception rather than X extends Throwable
• Changed get failure message wording

1.0.0

• Initial stab at Business Flows