Developer guide: show what the protocol generators actually emit

docs/demos/common/src/main/java/com/example/hello/GreeterCallSite.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.example.hello;
+
+import com.codename1.components.ToastBar;
+import java.util.Arrays;
+
+/// Call site for the `@GrpcClient` interface `cn1:generate-grpc` emits.
+/// Included by the developer guide's `generate-grpc` appendix.
+class GreeterCallSite {
+
+    // tag::appendix-goal-generate-grpc-java-002[]
+    void sayHello(String bearerToken) {
+        GreeterGrpc greeter = GreeterGrpc.of("https://grpc.example.com");
+        HelloRequest request = new HelloRequest("Ada", Arrays.asList("ada", "countess"), Mood.HAPPY);
+
+        greeter.sayHello(request, bearerToken, response -> {
+            if (response.isOk() && response.getResponseData() != null) {
+                ToastBar.showInfoMessage(response.getResponseData().message());
+            } else if (response.isOk()) {
+                ToastBar.showErrorMessage("The server returned an empty reply");
+            } else {
+                // getResponseCode() is the gRPC status, not the HTTP one --
+                // a gRPC-Web call can carry a failure under HTTP 200.
+                ToastBar.showErrorMessage("gRPC status " + response.getResponseCode()
+                        + ": " + response.getResponseErrorMessage());
+            }
+        });
+    }
+    // end::appendix-goal-generate-grpc-java-002[]
+}

docs/demos/common/src/main/java/com/example/hello/GreeterGrpc.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+// Generated by cn1:generate-grpc.
+package com.example.hello;
+
+import com.codename1.annotations.grpc.GrpcClient;
+import com.codename1.annotations.grpc.Rpc;
+import com.codename1.annotations.rest.Header;
+import com.codename1.io.grpc.GrpcClients;
+import com.codename1.io.grpc.GrpcResponse;
+import com.codename1.util.OnComplete;
+
+// tag::appendix-goal-generate-grpc-java-001[]
+@GrpcClient("helloworld.Greeter")
+public interface GreeterGrpc {
+
+    @Rpc("SayHello")
+    void sayHello(com.example.hello.HelloRequest request, @Header("Authorization") String bearerToken, OnComplete<GrpcResponse<com.example.hello.HelloReply>> callback);
+
+    static GreeterGrpc of(String baseUrl) {
+        return GrpcClients.create(GreeterGrpc.class, baseUrl);
+    }
+}
+// end::appendix-goal-generate-grpc-java-001[]

docs/demos/common/src/main/java/com/example/hello/HelloReply.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+// Generated by cn1:generate-grpc.
+package com.example.hello;
+
+import com.codename1.annotations.grpc.ProtoField;
+import com.codename1.annotations.grpc.ProtoMessage;
+
+@ProtoMessage
+public record HelloReply(
+    @ProtoField(tag = 1) String message,
+    @ProtoField(tag = 2, wireType = ProtoField.WireKind.SINT, name = "emoji_code") int emojiCode,
+    @ProtoField(tag = 3) com.example.hello.HelloRequest echo
+) {}

docs/demos/common/src/main/java/com/example/hello/HelloRequest.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+// Generated by cn1:generate-grpc.
+package com.example.hello;
+
+import com.codename1.annotations.grpc.ProtoField;
+import com.codename1.annotations.grpc.ProtoMessage;
+import java.util.List;
+
+@ProtoMessage
+public record HelloRequest(
+    @ProtoField(tag = 1) String name,
+    @ProtoField(tag = 2) List<String> aliases,
+    @ProtoField(tag = 3) com.example.hello.Mood mood
+) {}

docs/demos/common/src/main/java/com/example/hello/Mood.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+// Generated by cn1:generate-grpc.
+package com.example.hello;
+
+import com.codename1.annotations.grpc.ProtoEnum;
+
+@ProtoEnum
+public enum Mood {
+    UNKNOWN(0),
+    HAPPY(1),
+    SAD(2);
+
+    public final int number;
+    Mood(int n) { this.number = n; }
+
+    public static Mood forNumber(int n) {
+        for (Mood v : values()) {
+            if (v.number == n) return v;
+        }
+        return null;
+    }
+}

docs/demos/common/src/main/java/com/example/petstore/PetApi.java

@@ -1,10 +1,38 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+// Generated by cn1:generate-openapi.
 package com.example.petstore;
 
 import com.codename1.annotations.rest.Body;
+import com.codename1.annotations.rest.Cookie;
+import com.codename1.annotations.rest.DELETE;
 import com.codename1.annotations.rest.GET;
 import com.codename1.annotations.rest.Header;
+import com.codename1.annotations.rest.PATCH;
 import com.codename1.annotations.rest.POST;
+import com.codename1.annotations.rest.PUT;
 import com.codename1.annotations.rest.Path;
+import com.codename1.annotations.rest.Query;
 import com.codename1.annotations.rest.RestClient;
 import com.codename1.io.rest.Response;
 import com.codename1.io.rest.RestClients;
@@ -14,15 +42,20 @@
 @RestClient
 public interface PetApi {
 
+    @POST("/pet")
+    void addPet(@Body com.example.petstore.model.Pet body, @Header("Authorization") String bearerToken, OnComplete<Response<com.example.petstore.model.Pet>> callback);
+
+    @PUT("/pet")
+    void updatePet(@Body com.example.petstore.model.Pet body, @Header("Authorization") String bearerToken, OnComplete<Response<com.example.petstore.model.Pet>> callback);
+
+    @GET("/pet/findByStatus")
+    void findPetsByStatus(@Query("status") String status, @Header("Authorization") String bearerToken, OnComplete<Response<java.util.List<com.example.petstore.model.Pet>>> callback);
+
     @GET("/pet/{petId}")
-    void getPetById(@Path("petId") Long petId,
-                    @Header("Authorization") String bearerToken,
-                    OnComplete<Response<com.example.petstore.model.Pet>> callback);
+    void getPetById(@Path("petId") Long petId, @Header("Authorization") String bearerToken, OnComplete<Response<com.example.petstore.model.Pet>> callback);
 
-    @POST("/pet")
-    void addPet(@Body com.example.petstore.model.Pet body,
-                @Header("Authorization") String bearerToken,
-                OnComplete<Response<com.example.petstore.model.Pet>> callback);
+    @DELETE("/pet/{petId}")
+    void deletePet(@Path("petId") Long petId, @Header("Authorization") String bearerToken, OnComplete<Response<String>> callback);
 
     static PetApi of(String baseUrl) {
         return RestClients.create(PetApi.class, baseUrl);

docs/demos/common/src/main/java/com/example/petstore/PetApiCallSite.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.example.petstore;
+
+import com.codename1.components.ToastBar;
+
+/// Call site for the `@RestClient` interface `cn1:generate-openapi` emits.
+/// Included by the developer guide's `generate-openapi` appendix.
+class PetApiCallSite {
+
+    // tag::appendix-goal-generate-openapi-java-003[]
+    void loadPet(String bearerToken) {
+        PetApi api = PetApi.of("https://petstore3.swagger.io/api/v3");
+
+        api.getPetById(10L, bearerToken, response -> {
+            // Two things have to be settled before the payload is a Pet.
+            // The generated impl passes null when the request never
+            // completed, and on an error status it forwards the raw
+            // Response<String> under this type -- so on that path
+            // getResponseData() is the error body, not a Pet, and
+            // touching it as one is a cast that does not throw on iOS.
+            if (response == null) {
+                ToastBar.showErrorMessage("The request did not complete");
+            } else if (response.getResponseCode() < 200 || response.getResponseCode() > 299) {
+                ToastBar.showErrorMessage(response.getResponseErrorMessage());
+            } else if (response.getResponseData() == null) {
+                ToastBar.showErrorMessage("The server returned no pet");
+            } else {
+                ToastBar.showInfoMessage(response.getResponseData().name());
+            }
+        });
+    }
+    // end::appendix-goal-generate-openapi-java-003[]
+}

docs/demos/common/src/main/java/com/example/petstore/StoreApi.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+// Generated by cn1:generate-openapi.
+package com.example.petstore;
+
+import com.codename1.annotations.rest.Body;
+import com.codename1.annotations.rest.Cookie;
+import com.codename1.annotations.rest.DELETE;
+import com.codename1.annotations.rest.GET;
+import com.codename1.annotations.rest.Header;
+import com.codename1.annotations.rest.PATCH;
+import com.codename1.annotations.rest.POST;
+import com.codename1.annotations.rest.PUT;
+import com.codename1.annotations.rest.Path;
+import com.codename1.annotations.rest.Query;
+import com.codename1.annotations.rest.RestClient;
+import com.codename1.io.rest.Response;
+import com.codename1.io.rest.RestClients;
+import com.codename1.util.OnComplete;
+
+@RestClient
+public interface StoreApi {
+
+    @POST("/store/order")
+    void placeOrder(@Body com.example.petstore.model.Order body, @Header("Authorization") String bearerToken, OnComplete<Response<com.example.petstore.model.Order>> callback);
+
+    @GET("/store/order/{orderId}")
+    void getOrderById(@Path("orderId") Long orderId, @Header("Authorization") String bearerToken, OnComplete<Response<com.example.petstore.model.Order>> callback);
+
+    @DELETE("/store/order/{orderId}")
+    void deleteOrder(@Path("orderId") Long orderId, @Header("Authorization") String bearerToken, OnComplete<Response<String>> callback);
+
+    static StoreApi of(String baseUrl) {
+        return RestClients.create(StoreApi.class, baseUrl);
+    }
+}