Skip to content

Commit

Permalink
Merge pull request #729 from smallrye/feature/CheckReturnValue-annota…
Browse files Browse the repository at this point in the history 
…tion

CheckReturnValue annotation for static analysis tools
  • Loading branch information
@cescoffier
cescoffier authored Oct 14, 2021
2 parents 5d77fbf + 7556f2c commit 0adb114
Show file tree
Hide file tree
Showing 77 changed files with 626 additions and 7 deletions.
8 changes: 7 additions & 1 deletion implementation/revapi.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,13 @@
"criticality" : "highlight",
"minSeverity" : "POTENTIALLY_BREAKING",
"minCriticality" : "documented",
"differences" : [ ]
"differences" : [
{
"code": "java.annotation.added",
"annotation": "@io.smallrye.common.annotation.CheckReturnValue",
"justification": "This is a marker interface for static code analysis tools"
}
]
}
}, {
"extension" : "revapi.reporter.json",
Expand Down
41 changes: 41 additions & 0 deletions implementation/src/main/java/io/smallrye/mutiny/Multi.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,14 @@
import org.reactivestreams.Subscriber;
import org.reactivestreams.Subscription;

import io.smallrye.common.annotation.CheckReturnValue;
import io.smallrye.mutiny.groups.*;
import io.smallrye.mutiny.infrastructure.Infrastructure;

@SuppressWarnings({ "ReactiveStreamsPublisherImplementation" })
public interface Multi<T> extends Publisher<T> {

@CheckReturnValue
static MultiCreate createFrom() {
return MultiCreate.INSTANCE;
}
Expand All @@ -28,6 +30,7 @@ static MultiCreate createFrom() {
*
* @return the object to configure the creation process.
*/
@CheckReturnValue
static MultiCreateBy createBy() {
return MultiCreateBy.INSTANCE;
}
Expand All @@ -37,13 +40,15 @@ static MultiCreateBy createBy() {
*
* @return the object to configure the subscriber
*/
@CheckReturnValue
MultiSubscribe<T> subscribe();

/**
* Configures the behavior when an {@code item} event is received from the this {@link Multi}
*
* @return the object to configure the behavior.
*/
@CheckReturnValue
MultiOnItem<T> onItem();

/**
Expand All @@ -65,6 +70,7 @@ static MultiCreateBy createBy() {
* @param <O> the outcome type
* @return the outcome of the function.
*/
@CheckReturnValue
default <O> O stage(Function<Multi<T>, O> stage) {
return nonNull(stage, "stage").apply(this);
}
Expand All @@ -87,6 +93,7 @@ default <O> O stage(Function<Multi<T>, O> stage) {
*
* @return the produced {@link Uni}
*/
@CheckReturnValue
Uni<T> toUni();

/**
Expand All @@ -95,6 +102,7 @@ default <O> O stage(Function<Multi<T>, O> stage) {
*
* @return a MultiOnFailure on which you can specify the on failure action
*/
@CheckReturnValue
MultiOnFailure<T> onFailure();

/**
Expand All @@ -110,6 +118,7 @@ default <O> O stage(Function<Multi<T>, O> stage) {
* @param predicate the predicate, {@code null} means applied to all failures
* @return a MultiOnFailure configured with the given predicate on which you can specify the on failure action
*/
@CheckReturnValue
MultiOnFailure<T> onFailure(Predicate<? super Throwable> predicate);

/**
Expand All @@ -130,6 +139,7 @@ default <O> O stage(Function<Multi<T>, O> stage) {
* @deprecated use {@link #onSubscription()} instead
*/
@Deprecated
@CheckReturnValue
MultiOnSubscribe<T> onSubscribe();

/**
Expand All @@ -148,6 +158,7 @@ default <O> O stage(Function<Multi<T>, O> stage) {
*
* @return the object to configure the action to execution on subscription.
*/
@CheckReturnValue
MultiOnSubscribe<T> onSubscription();

/**
Expand All @@ -163,6 +174,7 @@ default <O> O stage(Function<Multi<T>, O> stage) {
* @param typeOfFailure the class of exception, must not be {@code null}
* @return a MultiOnFailure configured with the given predicate on which you can specify the on failure action
*/
@CheckReturnValue
MultiOnFailure<T> onFailure(Class<? extends Throwable> typeOfFailure);

/**
Expand All @@ -171,6 +183,7 @@ default <O> O stage(Function<Multi<T>, O> stage) {
*
* @return a multi replaying the events from the upstream.
*/
@CheckReturnValue
Multi<T> cache();

/**
Expand All @@ -190,6 +203,7 @@ default <O> O stage(Function<Multi<T>, O> stage) {
* @deprecated Use {@link #collect()} instead
*/
@Deprecated
@CheckReturnValue
default MultiCollect<T> collectItems() {
return collect();
}
Expand All @@ -209,6 +223,7 @@ default MultiCollect<T> collectItems() {
*
* @return the object to configure the collection process.
*/
@CheckReturnValue
MultiCollect<T> collect();

/**
Expand All @@ -218,6 +233,7 @@ default MultiCollect<T> collectItems() {
*
* @return the object to configure the grouping.
*/
@CheckReturnValue
MultiGroup<T> group();

/**
Expand All @@ -229,6 +245,7 @@ default MultiCollect<T> collectItems() {
* @deprecated Use {@link #group()} instead
*/
@Deprecated
@CheckReturnValue
default MultiGroup<T> groupItems() {
return group();
}
Expand All @@ -245,6 +262,7 @@ default MultiGroup<T> groupItems() {
* @param executor the executor to use, must not be {@code null}
* @return a new {@link Multi}
*/
@CheckReturnValue
Multi<T> emitOn(Executor executor);

/**
Expand All @@ -255,13 +273,15 @@ default MultiGroup<T> groupItems() {
* @param executor the executor to use, must not be {@code null}
* @return a new {@link Multi}
*/
@CheckReturnValue
Multi<T> runSubscriptionOn(Executor executor);

/**
* Allows configuring the actions or continuation to execute when this {@link Multi} fires the completion event.
*
* @return the object to configure the action.
*/
@CheckReturnValue
MultiOnCompletion<T> onCompletion();

/**
Expand All @@ -271,20 +291,23 @@ default MultiGroup<T> groupItems() {
* @deprecated Use {@link #select()} and {@link #skip()}instead
*/
@Deprecated
@CheckReturnValue
MultiTransform<T> transform();

/**
* Selects items from this {@link Multi}.
*
* @return the object to configure the selection.
*/
@CheckReturnValue
MultiSelect<T> select();

/**
* Skips items from this {@link Multi}.
*
* @return the object to configure the skip.
*/
@CheckReturnValue
MultiSkip<T> skip();

/**
Expand All @@ -293,6 +316,7 @@ default MultiGroup<T> groupItems() {
*
* @return the object to configure the overflow strategy
*/
@CheckReturnValue
MultiOverflow<T> onOverflow();

/**
Expand All @@ -301,6 +325,7 @@ default MultiGroup<T> groupItems() {
*
* @return the object to configure the broadcast
*/
@CheckReturnValue
MultiBroadcast<T> broadcast();

/**
Expand All @@ -319,6 +344,7 @@ default MultiGroup<T> groupItems() {
* @return the object to convert an {@link Multi} instance
* @see MultiConvert
*/
@CheckReturnValue
MultiConvert<T> convert();

/**
Expand All @@ -331,6 +357,7 @@ default MultiGroup<T> groupItems() {
* @param predicate a predicate, must not be {@code null}
* @return the new {@link Multi}
*/
@CheckReturnValue
default Multi<T> filter(Predicate<? super T> predicate) {
return select().where(predicate);
}
Expand All @@ -347,6 +374,7 @@ default Multi<T> filter(Predicate<? super T> predicate) {
* @param <O> the type of item produced by the mapper function
* @return the new {@link Multi}
*/
@CheckReturnValue
default <O> Multi<O> map(Function<? super T, ? extends O> mapper) {
return onItem().transform(mapper);
}
Expand All @@ -369,6 +397,7 @@ default <O> Multi<O> map(Function<? super T, ? extends O> mapper) {
* @param <O> the type of item emitted by the {@link Publisher} produced by the {@code mapper}
* @return the produced {@link Multi}
*/
@CheckReturnValue
default <O> Multi<O> flatMap(Function<? super T, ? extends Publisher<? extends O>> mapper) {
return onItem().transformToMultiAndMerge(mapper);
}
Expand All @@ -389,6 +418,7 @@ default <O> Multi<O> flatMap(Function<? super T, ? extends Publisher<? extends O
* @param action the function taking the item and returning a {@link Uni}, must not be {@code null}
* @return the new {@link Multi}
*/
@CheckReturnValue
default Multi<T> call(Function<? super T, Uni<?>> action) {
return onItem().call(action);
}
Expand All @@ -409,6 +439,7 @@ default Multi<T> call(Function<? super T, Uni<?>> action) {
* @param action the function taking the item and returning a {@link Uni}, must not be {@code null}
* @return the new {@link Multi}
*/
@CheckReturnValue
default Multi<T> call(Supplier<Uni<?>> action) {
return onItem().call(action);
}
Expand All @@ -425,6 +456,7 @@ default Multi<T> call(Supplier<Uni<?>> action) {
* @param callback the callback, must not be {@code null}
* @return the new {@link Multi}
*/
@CheckReturnValue
default Multi<T> invoke(Consumer<? super T> callback) {
return onItem().invoke(nonNull(callback, "callback"));
}
Expand All @@ -439,6 +471,7 @@ default Multi<T> invoke(Consumer<? super T> callback) {
* @param callback the callback, must not be {@code null}
* @return the new {@link Multi}
*/
@CheckReturnValue
default Multi<T> invoke(Runnable callback) {
return onItem().invoke(callback);
}
Expand All @@ -462,6 +495,7 @@ default Multi<T> invoke(Runnable callback) {
* @param <O> the type of item emitted by the {@link Publisher} produced by the {@code mapper}
* @return the produced {@link Multi}
*/
@CheckReturnValue
default <O> Multi<O> concatMap(Function<? super T, ? extends Publisher<? extends O>> mapper) {
return onItem().transformToMultiAndConcatenate(mapper);
}
Expand All @@ -471,20 +505,23 @@ default <O> Multi<O> concatMap(Function<? super T, ? extends Publisher<? extends
*
* @return the object to configure the termination actions
*/
@CheckReturnValue
MultiOnTerminate<T> onTermination();

/**
* Configures actions when the subscriber cancels the subscription.
*
* @return the object to configure the cancellation actions
*/
@CheckReturnValue
MultiOnCancel<T> onCancellation();

/**
* Configures actions when items are being requested.
*
* @return the object to configure the actions
*/
@CheckReturnValue
MultiOnRequest<T> onRequest();

/**
Expand All @@ -495,6 +532,7 @@ default <O> Multi<O> concatMap(Function<? super T, ? extends Publisher<? extends
* @param <R> the output type
* @return the new {@link Multi}
*/
@CheckReturnValue
default <R> Multi<R> plug(Function<Multi<T>, Multi<R>> operatorProvider) {
Function<Multi<T>, Multi<R>> provider = nonNull(operatorProvider, "operatorProvider");
return Infrastructure.onMultiCreation(nonNull(provider.apply(this), "multi"));
Expand All @@ -515,6 +553,7 @@ default <R> Multi<R> plug(Function<Multi<T>, Multi<R>> operatorProvider) {
*
* @return the new multi.
*/
@CheckReturnValue
Multi<T> toHotStream();

/**
Expand All @@ -527,6 +566,7 @@ default <R> Multi<R> plug(Function<Multi<T>, Multi<R>> operatorProvider) {
* @return a new {@link Multi}
* @see Infrastructure#setOperatorLogger(Infrastructure.OperatorLogger)
*/
@CheckReturnValue
Multi<T> log(String identifier);

/**
Expand All @@ -540,5 +580,6 @@ default <R> Multi<R> plug(Function<Multi<T>, Multi<R>> operatorProvider) {
* @see Multi#log(String)
* @see Infrastructure#setOperatorLogger(Infrastructure.OperatorLogger)
*/
@CheckReturnValue
Multi<T> log();
}
Loading

0 comments on commit 0adb114

Please sign in to comment.