You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by ah...@apache.org on 2022/04/06 16:41:25 UTC
[isis] 01/02: ISIS-2297: java-doc polishing
This is an automated email from the ASF dual-hosted git repository.
ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 954021536a63e3d190b3456cd857eecc0d2434ca
Author: Andi Huber <ah...@apache.org>
AuthorDate: Wed Apr 6 18:31:28 2022 +0200
ISIS-2297: java-doc polishing
---
.../org/apache/isis/commons/functional/Railway.java | 17 +++++++++--------
.../java/org/apache/isis/commons/functional/Try.java | 20 ++++++++++----------
2 files changed, 19 insertions(+), 18 deletions(-)
diff --git a/commons/src/main/java/org/apache/isis/commons/functional/Railway.java b/commons/src/main/java/org/apache/isis/commons/functional/Railway.java
index 72bf9078e0..60f5249ba1 100644
--- a/commons/src/main/java/org/apache/isis/commons/functional/Railway.java
+++ b/commons/src/main/java/org/apache/isis/commons/functional/Railway.java
@@ -32,7 +32,8 @@ import lombok.val;
/**
* The {@link Railway} type represents a value of one of two possible types (a disjoint union)
- * of {@link Success} or {@link Failure}.
+ * of {@link Success} or {@link Failure}, where chaining follows the <em>Railway Pattern</em>,
+ * that is, once failed, stays failed.
* <p>
* Factory methods {@link Railway#success(Object)} and {@link Railway#failure(Object)}
* correspond to the two possible values.
@@ -62,7 +63,7 @@ public interface Railway<F, S> {
/**
* Optionally returns the contained {@code value} based on presence,
- * that is, if its a {@link Success}.
+ * that is, if this is a {@link Success}.
*/
Optional<S> getSuccess();
default S getSuccessElseFail() { return getSuccess().orElseThrow(); }
@@ -76,7 +77,7 @@ public interface Railway<F, S> {
}
/**
* Optionally returns the contained {@code failure} based on presence,
- * that is, if its a {@link Failure}.
+ * that is, if this is a {@link Failure}.
*/
Optional<F> getFailure();
default F getFailureElseFail() { return getFailure().orElseThrow(); }
@@ -84,23 +85,23 @@ public interface Railway<F, S> {
// -- PEEKING
/**
- * Peeks into the contained {@code success} if its a {@link Success}.
+ * Peeks into the contained {@code success} if this is a {@link Success}.
*/
Railway<F, S> ifSuccess(final @NonNull Consumer<S> valueConsumer);
/**
- * Peeks into the contained {@code failure} if its a {@link Failure}.
+ * Peeks into the contained {@code failure} if this is a {@link Failure}.
*/
Railway<F, S> ifFailure(final @NonNull Consumer<F> failureConsumer);
// -- MAPPING
/**
- * Maps this {@link Railway} to another if its a {@link Success}.
+ * Maps this {@link Railway} to another if this is a {@link Success}.
* Otherwise if this is a {@link Failure} acts as identity operator.
*/
<R> Railway<F, R> mapSuccess(final @NonNull Function<S, R> successMapper);
/**
- * Maps this {@link Railway} to another if its a {@link Failure}.
+ * Maps this {@link Railway} to another if this is a {@link Failure}.
* Otherwise if this is a {@link Success} acts as identity operator.
*/
<R> Railway<R, S> mapFailure(final @NonNull Function<F, R> failureMapper);
@@ -118,7 +119,7 @@ public interface Railway<F, S> {
// -- CHAINING
/**
- * <h1>Railway Pattern</h1>
+ * <em>Railway Pattern</em>
* If this is a {@link Success}, returns a new {@link Railway} as produced by the
* chainingFunction, that receives the current success value as input.
* Otherwise if this is a {@link Failure} acts as identity operator and
diff --git a/commons/src/main/java/org/apache/isis/commons/functional/Try.java b/commons/src/main/java/org/apache/isis/commons/functional/Try.java
index f881dbe32e..020625edd1 100644
--- a/commons/src/main/java/org/apache/isis/commons/functional/Try.java
+++ b/commons/src/main/java/org/apache/isis/commons/functional/Try.java
@@ -81,23 +81,23 @@ public interface Try<T> {
/**
* Optionally returns the contained {@code value} based on presence,
- * that is, if its a {@link Success} and the value is not {@code null}.
+ * that is, if this is a {@link Success} and the value is not {@code null}.
*/
Optional<T> getValue();
/**
* Optionally returns the contained {@code failure} based on presence,
- * that is, if its a {@link Failure}.
+ * that is, if this is a {@link Failure}.
*/
Optional<Throwable> getFailure();
// -- PEEKING
/**
- * Peeks into the {@code value} if its a {@link Success}.
+ * Peeks into the {@code value} if this is a {@link Success}.
*/
Try<T> ifSuccess(final @NonNull Consumer<Optional<T>> valueConsumer);
/**
- * Peeks into the {@code failure} if its a {@link Failure}.
+ * Peeks into the {@code failure} if this is a {@link Failure}.
*/
Try<T> ifFailure(final @NonNull Consumer<Throwable> exceptionConsumer);
@@ -111,17 +111,17 @@ public interface Try<T> {
// -- MAPPING
/**
- * Maps this {@link Try} to another if its a {@link Success}.
- * Otherwise if its a {@link Failure} acts as identity operator.
+ * Maps this {@link Try} to another if this is a {@link Success}.
+ * Otherwise if this is a {@link Failure} acts as identity operator.
*/
<R> Try<R> mapSuccess(final @NonNull Function<T, R> successMapper);
/**
* Maps this {@link Try} to another if its a {@link Failure}.
- * Otherwise if its a {@link Success} acts as identity operator.
+ * Otherwise if this is a {@link Success} acts as identity operator.
*/
Try<T> mapFailure(final @NonNull UnaryOperator<Throwable> failureMapper);
/**
- * Maps this {@link Try} to {@link Failure} if its a {@link Success} with an empty {@code value}.
+ * Maps this {@link Try} to {@link Failure} if this is a {@link Success} with an empty {@code value}.
* Otherwise acts as identity operator.
*/
Try<T> mapEmptyToFailure();
@@ -148,12 +148,12 @@ public interface Try<T> {
// -- CONCATENATION
/**
- * If its a {@link Success}, maps it to another based on given {@link Callable}.
+ * If this is a {@link Success}, maps it to another based on given {@link Callable}.
* Otherwise if its a {@link Failure} acts as identity operator.
*/
<R> Try<R> thenCall(final @NonNull Callable<R> callable);
/**
- * If its a {@link Success}, maps it to another based on given {@link ThrowingRunnable}.
+ * If this is a {@link Success}, maps it to another based on given {@link ThrowingRunnable}.
* Otherwise if its a {@link Failure} acts as identity operator.
*/
Try<Void> thenRun(final @NonNull ThrowingRunnable runnable);