Merge pull request #1364 from jponge/feat/workshop-examples

Import the Mutiny workshop examples into the main repository

.build/update-workshop-target-version.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+./mvnw -Pupdate-workshop-examples -f workshop-examples compile -DworkshopVersion=$1
+find workshop-examples -name '*.java' | xargs chmod +x

README.md

@@ -49,6 +49,12 @@ Mutiny is based on the [Reactive Streams protocol](https://www.reactive-streams.
 
 In addition, Mutiny offers converters to interact with other popular libraries and [Kotlin](https://kotlinlang.org/).
 
+## 👓 Mutiny workshop examples
+
+You can learn about Mutiny from the [documentation and website](https://smallrye.io/smallrye-mutiny).
+
+This repository also contains the [Mutiny workshop examples](workshop-examples) that cover the common concerns through self-contained executable [JBang](https://www.jbang.dev/) scripts.
+
 ## 📦 Build instructions
 
 Mutiny is built with Apache Maven, so all you need is:

documentation/docs/tutorials/mutiny-workshop.md

@@ -0,0 +1,17 @@
+---
+tags:
+- tutorial
+- beginner
+---
+
+# Go further with the Mutiny workshop!
+
+One great option to teach yourself Mutiny is to go through the [Mutiny workshop examples](https://github.com/smallrye/smallrye-mutiny/tree/main/workshop-examples).
+
+These self-contained [JBang](https://jbang.dev/) scripts cover the main parts of the Mutiny APIs.
+
+It's a fun and easy way to discover Mutiny!
+
+Check out [https://github.com/smallrye/smallrye-mutiny/tree/main/workshop-examples](https://github.com/smallrye/smallrye-mutiny/tree/main/workshop-examples) to learn more.
+
+![Running a workshop sample](running-workshop-sample.png){ width="400" }

documentation/mkdocs.yml

@@ -15,6 +15,7 @@ nav:
       - 'tutorials/transforming-items-asynchronously.md'
       - 'tutorials/handling-failures.md'
       - 'tutorials/retrying.md'
+      - 'tutorials/mutiny-workshop.md'
   - 'Guides':
       - 'guides/imperative-to-reactive.md'
       - 'guides/reactive-to-imperative.md'

pom.xml

@@ -73,6 +73,7 @@
         <module>kotlin</module>
         <module>bom</module>
         <module>math</module>
+        <module>workshop-examples</module>
     </modules>
 
     <properties>
@@ -115,6 +116,7 @@
         <dokka.version>1.7.20</dokka.version>
 
         <jandex-maven-plugin.version>1.2.3</jandex-maven-plugin.version>
+        <find-and-replace-maven-plugin.version>1.1.0</find-and-replace-maven-plugin.version>
     </properties>
 
     <dependencyManagement>
@@ -368,6 +370,11 @@
                         </execution>
                     </executions>
                 </plugin>
+                <plugin>
+                    <groupId>io.github.floverfelt</groupId>
+                    <artifactId>find-and-replace-maven-plugin</artifactId>
+                    <version>${find-and-replace-maven-plugin.version}</version>
+                </plugin>
             </plugins>
         </pluginManagement>
         <plugins>

workshop-examples/README.md

@@ -0,0 +1,29 @@
+# Mutiny workshop examples
+
+This project contains learning examples for Mutiny, covering a wide range of topics such as the basics, transformations, error recovery and more.
+
+## Structure
+
+The examples are found in `src/main/java` and use a non-conventional file naming strategy.
+
+For instance you will find the failure handling examples in `_04_failures` where `_04_Uni_Failure_Retry.java` holds one such example.
+
+This naming scheme is not usual for Java programs, but it makes for a great way to organize files 😄
+
+## Running the examples
+
+Each file is a self-contained class with a `main` method.
+
+A friendly option is to open the Maven project in your favorite IDE, then run the `main` method of each example of interest.
+
+The other option is to use [JBang](https://www.jbang.dev/) as each example is a valid JBang script:
+
+```shell
+jbang src/main/java/_05_backpressure/_03_Visual_Drop.java
+```
+
+What's more each file is Unix-executable, so you can also run as:
+
+```shell
+./src/main/java/_05_backpressure/_03_Visual_Drop.java
+```

workshop-examples/pom.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>io.smallrye.reactive</groupId>
+        <artifactId>mutiny-project</artifactId>
+        <version>999-SNAPSHOT</version>
+    </parent>
+
+    <name>SmallRye Mutiny - Workshop examples</name>
+    <description>Workshop examples</description>
+    <artifactId>mutiny-workshop-examples</artifactId>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.smallrye.reactive</groupId>
+            <artifactId>mutiny</artifactId>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <showDeprecation>true</showDeprecation>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+    <profiles>
+        <profile>
+            <id>update-workshop-examples</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>io.github.floverfelt</groupId>
+                        <artifactId>find-and-replace-maven-plugin</artifactId>
+                        <executions>
+                            <execution>
+                                <id>exec</id>
+                                <phase>process-sources</phase>
+                                <goals>
+                                    <goal>find-and-replace</goal>
+                                </goals>
+                                <configuration>
+                                    <replacementType>file-contents</replacementType>
+                                    <findRegex>//DEPS io.smallrye.reactive:mutiny:.*</findRegex>
+                                    <replaceValue>//DEPS io.smallrye.reactive:mutiny:${workshopVersion}</replaceValue>
+                                    <recursive>true</recursive>
+                                    <fileMask>.java</fileMask>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+
+</project>

workshop-examples/src/main/java/_01_basics/_01_Uni.java

@@ -0,0 +1,16 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//DEPS io.smallrye.reactive:mutiny:2.4.0
+package _01_basics;
+
+import io.smallrye.mutiny.Uni;
+
+public class _01_Uni {
+
+    public static void main(String[] args) {
+        System.out.println("⚡️ Hello world");
+
+        Uni<String> uni = Uni.createFrom().item("Hello, world!");
+
+        uni.subscribe().with(System.out::println);
+    }
+}

workshop-examples/src/main/java/_01_basics/_02_Uni_UniSubscriber.java

@@ -0,0 +1,33 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//DEPS io.smallrye.reactive:mutiny:2.4.0
+package _01_basics;
+
+import io.smallrye.mutiny.Uni;
+import io.smallrye.mutiny.subscription.UniSubscriber;
+import io.smallrye.mutiny.subscription.UniSubscription;
+
+public class _02_Uni_UniSubscriber {
+
+    public static void main(String[] args) {
+        System.out.println("⚡️ Hello world with UniSubscriber");
+
+        Uni<String> uni = Uni.createFrom().item("Hello, world!");
+
+        uni.subscribe().withSubscriber(new UniSubscriber<String>() {
+            @Override
+            public void onSubscribe(UniSubscription subscription) {
+                System.out.println("onSubscribe");
+            }
+
+            @Override
+            public void onItem(String item) {
+                System.out.println("onItem: " + item);
+            }
+
+            @Override
+            public void onFailure(Throwable failure) {
+                System.out.println("onFailure: " + failure.getMessage());
+            }
+        });
+    }
+}

workshop-examples/src/main/java/_01_basics/_03_Uni_From_Supplier.java

@@ -0,0 +1,22 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//DEPS io.smallrye.reactive:mutiny:2.4.0
+package _01_basics;
+
+import java.util.Random;
+
+import io.smallrye.mutiny.Uni;
+
+public class _03_Uni_From_Supplier {
+
+    public static void main(String[] args) {
+        System.out.println("️⚡️ Uni from supplier");
+
+        Random random = new Random();
+
+        Uni<Integer> uniFromSupplier = Uni.createFrom().item(random::nextInt);
+
+        for (var i = 0; i < 5; i++) {
+            uniFromSupplier.subscribe().with(System.out::println);
+        }
+    }
+}

workshop-examples/src/main/java/_01_basics/_04_Uni_From_Supplier_And_State.java

@@ -0,0 +1,20 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//DEPS io.smallrye.reactive:mutiny:2.4.0
+package _01_basics;
+
+import java.util.concurrent.atomic.AtomicInteger;
+
+import io.smallrye.mutiny.Uni;
+
+public class _04_Uni_From_Supplier_And_State {
+
+    public static void main(String[] args) {
+        System.out.println("️⚡️ Uni from supplier with state");
+
+        Uni<Integer> uniFromSupplierAndState = Uni.createFrom().item(AtomicInteger::new, i -> i.addAndGet(10));
+
+        for (var i = 0; i < 5; i++) {
+            uniFromSupplierAndState.subscribe().with(System.out::println);
+        }
+    }
+}

workshop-examples/src/main/java/_01_basics/_05_Uni_Deferred.java

@@ -0,0 +1,22 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//DEPS io.smallrye.reactive:mutiny:2.4.0
+package _01_basics;
+
+import java.util.concurrent.atomic.AtomicLong;
+
+import io.smallrye.mutiny.Uni;
+
+public class _05_Uni_Deferred {
+
+    public static void main(String[] args) {
+        System.out.println("️⚡️ Deferred Uni");
+
+        AtomicLong ids = new AtomicLong();
+
+        Uni<Long> deferredUni = Uni.createFrom().deferred(() -> Uni.createFrom().item(ids::incrementAndGet));
+
+        for (var i = 0; i < 5; i++) {
+            deferredUni.subscribe().with(System.out::println);
+        }
+    }
+}

workshop-examples/src/main/java/_01_basics/_06_Uni_From_Emitter.java

@@ -0,0 +1,29 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//DEPS io.smallrye.reactive:mutiny:2.4.0
+package _01_basics;
+
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ForkJoinPool;
+
+import io.smallrye.mutiny.Uni;
+
+public class _06_Uni_From_Emitter {
+
+    public static void main(String[] args) throws InterruptedException {
+        System.out.println("⚡️ Uni from emitter");
+
+        ForkJoinPool forkJoinPool = ForkJoinPool.commonPool();
+        CountDownLatch emitterLatch = new CountDownLatch(1);
+
+        Uni<String> uniFromEmitter = Uni.createFrom().emitter(emitter -> {
+            forkJoinPool.submit(() -> {
+                emitter.complete("Hello");
+                emitterLatch.countDown();
+            });
+        });
+
+        uniFromEmitter.subscribe().with(System.out::println);
+
+        emitterLatch.await();
+    }
+}

workshop-examples/src/main/java/_01_basics/_07_Unit_From_Emitter_And_State.java

@@ -0,0 +1,21 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//DEPS io.smallrye.reactive:mutiny:2.4.0
+package _01_basics;
+
+import java.util.concurrent.atomic.AtomicInteger;
+
+import io.smallrye.mutiny.Uni;
+
+public class _07_Unit_From_Emitter_And_State {
+
+    public static void main(String[] args) {
+        System.out.println("⚡️ Uni from emitter and state");
+
+        Uni<Integer> uniFromEmitterAndState = Uni.createFrom()
+                .emitter(AtomicInteger::new, (i, e) -> e.complete(i.addAndGet(10)));
+
+        for (var i = 0; i < 5; i++) {
+            uniFromEmitterAndState.subscribe().with(System.out::println);
+        }
+    }
+}

workshop-examples/src/main/java/_01_basics/_08_Uni_From_Failure.java

@@ -0,0 +1,20 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//DEPS io.smallrye.reactive:mutiny:2.4.0
+package _01_basics;
+
+import java.io.IOException;
+
+import io.smallrye.mutiny.Uni;
+
+public class _08_Uni_From_Failure {
+
+    public static void main(String[] args) {
+        System.out.println("⚡️ Uni from failure");
+
+        Uni.createFrom().failure(new IOException("Boom"))
+                .subscribe().with(System.out::println, failure -> System.out.println(failure.getMessage()));
+
+        Uni.createFrom().failure(() -> new IOException("Badaboom"))
+                .subscribe().with(System.out::println, failure -> System.out.println(failure.getMessage()));
+    }
+}

workshop-examples/src/main/java/_01_basics/_09_Uni_From_CompletionStage.java

@@ -0,0 +1,26 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//DEPS io.smallrye.reactive:mutiny:2.4.0
+package _01_basics;
+
+import static java.util.concurrent.CompletableFuture.delayedExecutor;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.TimeUnit;
+
+import io.smallrye.mutiny.Uni;
+
+public class _09_Uni_From_CompletionStage {
+
+    public static void main(String[] args) throws InterruptedException {
+        System.out.println("⚡️ Uni from CompletionStage");
+
+        var cs = CompletableFuture
+                .supplyAsync(() -> "Hello!", delayedExecutor(1, TimeUnit.SECONDS))
+                .thenApply(String::toUpperCase);
+
+        Uni.createFrom().completionStage(cs)
+                .subscribe().with(System.out::println, failure -> System.out.println(failure.getMessage()));
+
+        Thread.sleep(2000);
+    }
+}