Java and Reactor examples for [Non]BlockingExecutor annotations

Author: Nikita Katkov

java8/src/main/java/org/jetbrains/annotations/BlockingExecutor.java

@@ -22,13 +22,13 @@
  * Indicates that the annotated executor (e.g. coroutine dispatcher, scheduler, etc.)
  * allows blocking methods execution.
  *
- * If a given context does not allow blocking calls, {@link NonBlockingExecutor} should be used.
+ * If a given executor does not allow blocking calls, {@link NonBlockingExecutor} should be used.
  *
- * Example:
+ * Example 1 (Kotlin coroutines):
  * <pre>
  * {@code
- *  class ExampleService {
- *      @BlockingContext
+ *  class BlockingExampleService {
+ *      @BlockingExecutor
  *      val dispatcher: CoroutineContext
  *          get() { ... }
  *
@@ -42,6 +42,27 @@
  *  }
  * }
  * </pre>
+ *
+ * Example 2 (Java with Reactor framework):
+ * <pre>
+ * {@code
+ * class BlockingExampleService {
+ *     private static final @BlockingExecutor Scheduler blockingScheduler =
+ *             Schedulers.newBoundedElastic(4, 10, "executor");
+ *
+ *     public Flux<String> foo(Flux<String> urls) {
+ *         return urls.publishOn(blockingScheduler)
+ *                 .map(url -> blockingBuzz(url));  // no IDE warning
+ *     }
+ *
+ *     @Blocking
+ *     private String blockingBuzz(String url) { ... }
+ * }
+ * }
+ * </pre>
+ *
+ * @see Blocking
+ * @see NonBlocking
  */
 @Documented
 @Retention(RetentionPolicy.CLASS)

java8/src/main/java/org/jetbrains/annotations/NonBlockingExecutor.java

@@ -22,13 +22,13 @@
  * Indicates that the annotated executor (e.g. coroutine dispatcher, scheduler, etc.)
  * does not allow blocking methods execution.
  *
- * If a given context allows blocking calls, {@link BlockingExecutor} should be used.
+ * If a given executor allows blocking calls, {@link BlockingExecutor} should be used.
  *
- * Example:
+ * Example 1 (Kotlin coroutines):
  * <pre>
  * {@code
- *  class ExampleService {
- *      @NonBlockingContext
+ *  class NonBlockingExampleService {
+ *      @NonBlockingExecutor
  *      val dispatcher: CoroutineContext
  *          get() { ... }
  *
@@ -42,6 +42,28 @@
  *  }
  * }
  * </pre>
+ *
+ * <br>
+ * Example 2 (Java with Reactor framework):
+ * <pre>
+ * {@code
+ *  class NonBlockingExampleService {
+ *      private static final @NonBlockingExecutor Scheduler operationsScheduler =
+ *              Schedulers.newParallel("parallel");
+ *
+ *      public Flux<String> foo(Flux<String> urls) {
+ *          return urls.publishOn(operationsScheduler)
+ *                  .filter(url -> blockingBuzz(url) != null);  // IDE warning: `Possibly blocking call in non-blocking context`
+ *      }
+ *
+ *      @Blocking
+ *      private String blockingBuzz(String url) { ... }
+ *  }
+ * }
+ * </pre>
+ *
+ *  @see Blocking
+ *  @see NonBlocking
  */
 @Documented
 @Retention(RetentionPolicy.CLASS)