If you seek advice… then this Java library is for you! Result objects have all the answers you need. Start by “asking the ball” a Yes or No question, then turn it over and let the answers magically appear. Results can be either positive (“Success”) or negative (“Failure”). Great fun for software developers and adults alike. Colors and decorations may vary.

Getting Started

Instances of Result represent either the success or failure of an operation.

Result objects are immutable and type-safe. Operations that succeed produce results encapsulating a success value; operations that fail produce results with a failure value.

Treating failed operations as regular values allows for a functional approach to error handling – instead of throwing exceptions and using try-catch blocks. In terms of functional programming, Result is just a monadic container type.

The best way to think of Result is as a super-powered version of Optional. The only difference is that, whereas Optional may contain a value or be empty, Result contains either a success value or a failure value.

Adding Results to Your Build

The library requires JDK 1.8 or higher. Other than that, it has no external dependencies and it is very lightweight. Adding it to your build should be very easy.

Artifact coordinates:

• Group ID: com.leakyabstractions
• Artifact ID: result
• Version: 0.15.0.1

To add the dependency using Maven, use the following:

<dependency>
    <groupId>com.leakyabstractions</groupId>
    <artifactId>result</artifactId>
    <version>0.15.0.1</version>
</dependency>

To add the dependency using Gradle, if you are building an application that will use Result internally:

dependencies {
    implementation("com.leakyabstractions:result:0.15.0.1")
}

If you are building a library that will use Result type in its public API, you should use instead:

dependencies {
    api("com.leakyabstractions:result:0.15.0.1")
}

Creating Result Objects

• Results.success creates a new successful result containing the given value.
• Results.failure creates a new failed result containing the given value.
• Results.ofNullable creates a new result based on the given possibly-null value.
• Results.ofOptional creates a new result based on the given possibly-empty optional.
• Results.ofCallable creates a new result based on the given possibly-throwing task.

Basic Usage

Unwrapping Values

• hasSuccess checks if a result contains a success value.
• hasFailure checks if a result contains a failure value.
• getSuccess returns a result’s success value as a possibly-empty optional.
• getFailure returns a result’s failure value as a possibly-empty optional.
• orElse returns a result’s success value, or the given one.
• orElseMap returns a result’s success value, or maps its failure value.
• streamSuccess returns a result’s success value as a possibly-empty stream.
• streamFailure returns a result’s failure value as a possibly-empty stream.

Conditional Actions

• ifSuccess performs the given action with a successful result’s value.
• ifFailure performs the given action with a failed result’s value.
• ifSuccessOrElse performs either of the given actions with a result’s value.

Advanced Usage

Screening Results

• filter transforms a successful result into a failed one, based on the given condition.
• recover transforms a failed result into a successful one, based on the given condition.

Transforming Values

• mapSuccess transforms the value of a successful result.
• mapFailure transforms the value of a failed result.
• map transforms either the success or the failure value of a result.
• flatMapSuccess transforms a successful result into a different one.
• flatMapFailure transforms a failed result into a different one.
• flatMap transforms a result into a different one.

Additional Info

Releases

This library adheres to Pragmatic Versioning.

Artifacts are available in Maven Central.

Javadoc

Here you can find the full Javadoc documentation.

Benchmarks

You may want to visualize the latest benchmark report.

Looking for Support?

We’d love to help. Check out the support guidelines.

Contributions Welcome

If you’d like to contribute to this project, please start here.

Code of Conduct

This project is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Author

Copyright 2024 Guillermo Calvo.

License

This library is licensed under the Apache License, Version 2.0 (the “License”); you may not use it except in compliance with the License.

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.

Permitted:

• Commercial Use: You may use this library and derivatives for commercial purposes.
• Modification: You may modify this library.
• Distribution: You may distribute this library.
• Patent Use: This license provides an express grant of patent rights from contributors.
• Private Use: You may use and modify this library without distributing it.

Required:

• License and Copyright Notice: If you distribute this library you must include a copy of the license and copyright notice.
• State Changes: If you modify and distribute this library you must document changes made to this library.

Forbidden:

• Trademark use: This license does not grant any trademark rights.
• Liability: The library author cannot be held liable for damages.
• Warranty: This library is provided without any warranty.