chore: pubsub docs for JVM (#2996)

fixes: #2887

backend/controller/pubsub/testdata/java/subscriber/src/main/java/xyz/block/ftl/java/test/subscriber/Subscriber.java

@@ -3,9 +3,6 @@
 import java.util.Map;
 import java.util.concurrent.atomic.AtomicInteger;
 
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.node.ObjectNode;
-
 import ftl.builtin.CatchRequest;
 import ftl.publisher.PubSubEvent;
 import ftl.publisher.TestTopicSubscription;
@@ -58,7 +55,7 @@ public void catchAny(CatchRequest<Object> req) {
         if (!"publisher.PubSubEvent".equals(req.getRequestType())) {
             throw new IllegalArgumentException(String.format("unexpected request type: %s", req.getRequestType()));
         }
-        if (!(req.getRequest()instanceof Map<?,?>)) {
+        if (!(req.getRequest() instanceof Map<?, ?>)) {
             throw new IllegalArgumentException(
                     String.format("expected request to be a Map: %s", req.getRequest().getClass().getName()));
         }

docs/content/docs/reference/externaltypes.md

@@ -28,7 +28,6 @@ To use an external type in your FTL module schema, declare a type alias over the
 {% code_selector() %}
 <!-- go -->
 
-
 ```go
 //ftl:typealias
 type FtlType external.OtherType

docs/content/docs/reference/pubsub.md

@@ -15,6 +15,9 @@ top = false
 
 FTL has first-class support for PubSub, modelled on the concepts of topics (where events are sent), subscriptions (a cursor over the topic), and subscribers (functions events are delivered to). Subscribers are, as you would expect, sinks. Each subscription is a cursor over the topic it is associated with. Each topic may have multiple subscriptions. Each subscription may have multiple subscribers, in which case events will be distributed among them.
 
+{% code_selector() %}
+<!-- go -->
+
 First, declare a new topic:
 
 ```go
@@ -42,5 +45,108 @@ Events can be published to a topic like so:
 Invoices.Publish(ctx, Invoice{...})
 ```
 
+<!-- kotlin -->
+
+First, declare a new topic :
+
+```kotlin
+@Export
+@TopicDefinition("invoices")
+internal interface InvoiceTopic : Topic<Invoice>
+```
+
+Events can be published to a topic by injecting it into an `@Verb` method:
+
+```kotlin
+@Verb
+fun publishInvoice(request: InvoiceRequest, topic: InvoiceTopic) {
+    topic.publish(Invoice(request.getInvoiceNo()))
+}
+```
+
+There are two ways to subscribe to a topic. The first is to declare a method with the `@Subscription` annotation, this is generally used when
+subscribing to a topic inside the same module:
+
+```kotlin
+@Subscription(topic = "invoices", name = "invoicesSubscription")
+fun consumeInvoice(event: Invoice) {
+    // ...
+}
+```
+
+This is ok, but it requires the use of string constants for the topic name, which can be error-prone. If you are subscribing to a topic from
+another module, FTL will generate a type-safe subscription meta annotation you can use to subscribe to the topic:
+
+```kotlin
+@Subscription(topic = "invoices", module = "publisher", name = "invoicesSubscription")
+annotation class InvoicesSubscription 
+```
+
+This annotation can then be used to subscribe to the topic:
+
+```kotlin
+@InvoicesSubscription
+fun consumeInvoice(event: Invoice) {
+    // ...
+}
+```
+
+Note that if you want multiple subscriptions or control over the subscription name you will need to use the `@Subscription` annotation.
+
+<!-- java -->
+
+First, declare a new topic:
+
+```java
+@Export
+@TopicDefinition("invoices")
+interface InvoiceTopic extends Topic<Invoice> {}
+```
+
+Events can be published to a topic by injecting it into an `@Verb` method:
+
+```java
+@Verb
+void publishInvoice(InvoiceRequest request, InvoiceTopic topic) throws Exception {
+    topic.publish(new Invoice(request.getInvoiceNo()));
+}
+```
+
+There are two ways to subscribe to a topic. The first is to declare a method with the `@Subscription` annotation, this is generally used when
+subscribing to a topic inside the same module:
+
+```java
+@Subscription(topic = "invoices", name = "invoicesSubscription")
+public void consumeInvoice(Invoice event) {
+    // ...
+}
+```
+
+This is ok, but it requires the use of string constants for the topic name, which can be error-prone. If you are subscribing to a topic from
+another module, FTL will generate a type-safe subscription meta annotation you can use to subscribe to the topic:
+
+```java
+@Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
+@Subscription(
+        topic = "invoices",
+        module = "publisher",
+        name = "invoicesSubscription"
+)
+public @interface InvoicesSubscription {
+}
+```
+
+This annotation can then be used to subscribe to the topic:
+
+```java
+@InvoicesSubscription
+public void consumeInvoice(Invoice event) {
+    // ...
+}
+```
+
+Note that if you want multiple subscriptions or control over the subscription name you will need to use the `@Subscription` annotation.
+
+{% end %}
 > **NOTE!**
 > PubSub topics cannot be published to from outside the module that declared them, they can only be subscribed to. That is, if a topic is declared in module `A`, module `B` cannot publish to it.

docs/content/docs/reference/verbs.md

@@ -43,7 +43,7 @@ To declare a Verb, write a normal Kotlin function with the following signature,
 
 ```kotlin
 @Verb
-fun F(Context, In): Out { }
+fun F(In): Out { }
 ```
 
 eg.
@@ -94,5 +94,13 @@ fun echo(req: EchoRequest, time: TimeClient): EchoResponse {
 
 val response = time.call()
 ```
+Verb clients are generated by FTL. If the callee verb belongs to the same module as the caller, you must manually define your
+own client:
 
+```kotlin
+@VerbClient(name="time")
+interface TimeClient {
+    fun call(): TimeResponse
+}
+```
 {% end %}