Provide GraalVM descriptors for temporal-sdk, add docs for users using native-image (temporalio#1660)

Author: Spikhalskiy

CONTRIBUTING.md

@@ -8,8 +8,8 @@ before we can merge in any of your changes
 
 ## Development Environment
 
-* Java 11
-* Docker
+* Java 11+
+* Docker to run Temporal Server
 
 ## Build
 

README.md

@@ -11,15 +11,16 @@ Java SDK:
 - [Javadoc API reference](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/index.html)
 - [Sample applications](https://github.com/temporalio/samples-java#samples-directory)
 
-Temporal in general:
+Temporal:
 
 - [Temporal docs](https://docs.temporal.io/)
 - [Install Temporal Server](https://docs.temporal.io/docs/server/quick-install)
 - [Temporal CLI](https://docs.temporal.io/docs/devtools/tctl/)
 
-## Requirements
+## Supported Java runtimes
 
 - Java 1.8+
+- [GraalVM native-image](docs/AOT-native-image.md)
 
 ## Build configuration
 
@@ -37,19 +38,6 @@ or to *build.gradle*:
 
     compile group: 'io.temporal', name: 'temporal-sdk', version: 'N.N.N'
 
-## macOS Users
-
-Due to issues with default hostname resolution
-(see [this StackOverflow question](https://stackoverflow.com/questions/33289695/inetaddress-getlocalhost-slow-to-run-30-seconds) for more details),
-macOS Users may see gRPC `DEADLINE_EXCEEDED` errors and other slowdowns when running the SDK.
-
-To solve the problem add the following entries to your `/etc/hosts` file (where my-macbook is your hostname):
-
-```conf
-127.0.0.1   my-macbook
-::1         my-macbook
-```
-
 ## Contributing
 
 We'd love your help in improving the Temporal Java SDK. Please review our [contribution guidelines](CONTRIBUTING.md).

build.gradle

@@ -1,7 +1,7 @@
 buildscript {
     ext {
         palantirGitVersionVersion = "${JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_11) ? '0.15.0' : '0.13.0'}"
-        kotlinVersion = "${project.hasProperty("edgeDepsTest") ? '1.8.0' : (JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_16) ? '1.5.32' : '1.4.32')}"
+        kotlinVersion = "${project.hasProperty("edgeDepsTest") ? '1.8.10' : (JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_16) ? '1.5.32' : '1.4.32')}"
     }
 }
 
@@ -17,7 +17,7 @@ plugins {
     //    id 'org.jetbrains.kotlin.jvm' version '1.5.32'
     //    id 'org.jetbrains.kotlin.jvm' version '1.6.21'
     //    id 'org.jetbrains.kotlin.jvm' version '1.7.22'
-    //    id 'org.jetbrains.kotlin.jvm' version '1.8.0'
+    //    id 'org.jetbrains.kotlin.jvm' version '1.8.10'
     id 'org.jetbrains.kotlin.jvm' version "${kotlinVersion}" apply false
     id 'base'
 }
@@ -38,10 +38,10 @@ ext {
     // stay on 1.x for a while to don't use any APIs from 2.x which may break our users which still stay on 1.x
     // also slf4j 2.x is not compatible with spring boot 2.x
     slf4jVersion = project.hasProperty("edgeDepsTest") ? '2.0.6' : '1.7.36' // [1.4.0,)
-    protoVersion = '3.21.12' // [3.12.0,) 3.12 is brought by min gRPC 1.38
+    protoVersion = '3.22.0' // [3.12.0,) 3.12 is brought by min gRPC 1.38
     annotationApiVersion = '1.3.2'
     guavaVersion = '31.1-jre' // [10.0,)
-    tallyVersion = '0.12.0' // [0.4.0,)
+    tallyVersion = '0.13.0' // [0.4.0,)
 
     gsonVersion = '2.10.1' // [2.0,)
 

docs/AOT-native-image.md

@@ -0,0 +1,25 @@
+# Ahead Of Time (AOT) compilation
+
+Ahead Of Time compilation build tools such as those provided by [GraalVM's `native-image`](https://www.graalvm.org/reference-manual/native-image/) require some configuration when using Temporal JavaSDK.
+Temporal JavaSDK uses Java proxies to provide Workflow and Activity stubs and the target classes of these proxies are application-specific. Proxy classes need to be generated at a build time by the current AOT tools.
+Temporal JavaSDK dependencies like gRPC and Protobuf use reflection and some of its target classes are sometimes not possible to determine in advance during the static analysis.
+
+## [native-image](https://www.graalvm.org/reference-manual/native-image/)
+
+Temporal JavaSDK and Test Server support and can be used with GraalVM `native-image`.
+
+Temporal JavaSDK team does its best effort to maintain as complete `native-image` descriptors as technically possible for the following modules:
+`temporal-sdk`, `temporal-testing`, `temporal-serviceclient`, `temporal-test-server`.
+These modules are distributed with the embedded `native-image` descriptors.
+While these descriptors provide enough information for `native-image` to build and run a fully functional Temporal Test Server,
+any user building an application with Temporal JavaSDK will require an additional configuration for the reasons mentioned above: user interfaces are used by the JavaSDK for proxy creation, and they need to know in advance for `native-image`.
+
+`native-image` build can be configured with respect to JNI, java proxying, reflection, etc
+by providing [JSON configuration descriptors](https://www.graalvm.org/22.3/reference-manual/native-image/metadata/#specifying-metadata-with-json)
+which help `native-image` during building of the native execution file.
+This can be done manually, but it's labor-intensive and requires good understanding of `native-image` build [process](https://www.graalvm.org/22.3/reference-manual/native-image/basics/) and [configuration](https://www.graalvm.org/22.3/reference-manual/native-image/overview/Build-Overview/).
+
+Instead we recommend users to run their JVM application along with
+[the native-image Tracing agent](https://www.graalvm.org/22.3/reference-manual/native-image/metadata/AutomaticMetadataCollection/).
+For example, the agent can be run with the full set of integration tests of the app to cover the largest variety of code paths.
+This agent will automatically generate additional descriptor files that users should [place and retain with their project's source code](https://www.graalvm.org/22.3/reference-manual/native-image/overview/BuildConfiguration/#embed-a-configuration-file) under `META-INF/native-image`.

temporal-kotlin/build.gradle

@@ -1,7 +1,7 @@
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
-    id 'org.jlleitschuh.gradle.ktlint' version '11.1.0'
+    id 'org.jlleitschuh.gradle.ktlint' version '11.2.0'
 }
 
 apply plugin: 'org.jetbrains.kotlin.jvm'

temporal-sdk/src/main/resources/temporal-sdk/jni-config.json

@@ -0,0 +1,2 @@
+[
+]

temporal-sdk/src/main/resources/temporal-sdk/native-image.properties

@@ -0,0 +1,25 @@
+#
+# Copyright (C) 2022 Temporal Technologies, Inc. All Rights Reserved.
+#
+# Copyright (C) 2012-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Modifications copyright (C) 2017 Uber Technologies, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this material except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+Args = -H:DynamicProxyConfigurationResources=${.}/proxy-config.json \
+  -H:JNIConfigurationResources=${.}/jni-config.json \
+  -H:ReflectionConfigurationResources=${.}/reflect-config.json \
+  -H:ResourceConfigurationResources=${.}/resource-config.json \
+  -H:SerializationConfigurationResources=${.}/serialization-config.json

temporal-sdk/src/main/resources/temporal-sdk/proxy-config.json

@@ -0,0 +1,2 @@
+[
+]

temporal-sdk/src/main/resources/temporal-sdk/reflect-config.json

@@ -0,0 +1,26 @@
+[
+{
+  "name":"[Lcom.fasterxml.jackson.databind.deser.Deserializers;"
+},
+{
+  "name":"[Lcom.fasterxml.jackson.databind.deser.KeyDeserializers;"
+},
+{
+  "name":"[Lcom.fasterxml.jackson.databind.deser.ValueInstantiators;"
+},
+{
+  "name":"[Lcom.fasterxml.jackson.databind.ser.Serializers;"
+},
+{
+  "name":"com.fasterxml.jackson.databind.ext.Java7HandlersImpl",
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+},
+{
+  "name":"com.fasterxml.jackson.databind.ext.Java7SupportImpl",
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+},
+{
+  "name":"com.fasterxml.jackson.datatype.jsr310.JavaTimeModule",
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+}
+]

temporal-sdk/src/main/resources/temporal-sdk/resource-config.json

@@ -0,0 +1,6 @@
+{
+  "resources":{
+  "includes":[
+  ]},
+  "bundles":[]
+}

temporal-sdk/src/main/resources/temporal-sdk/serialization-config.json

@@ -0,0 +1,8 @@
+{
+  "types":[
+  ],
+  "lambdaCapturingTypes":[
+  ],
+  "proxies":[
+  ]
+}

temporal-serviceclient/src/main/resources/META-INF/native-image/io/temporal/temporal-serviceclient/jni-config.json

@@ -0,0 +1,25 @@
+[
+{
+  "name":"java.lang.ClassLoader",
+  "methods":[
+    {"name":"getPlatformClassLoader","parameterTypes":[] },
+    {"name":"loadClass","parameterTypes":["java.lang.String"] }
+  ]
+},
+{
+  "name":"jdk.internal.loader.ClassLoaders$PlatformClassLoader"
+},
+{
+  "name":"sun.management.VMManagementImpl",
+  "fields":[
+    {"name":"compTimeMonitoringSupport"},
+    {"name":"currentThreadCpuTimeSupport"},
+    {"name":"objectMonitorUsageSupport"},
+    {"name":"otherThreadCpuTimeSupport"},
+    {"name":"remoteDiagnosticCommandsSupport"},
+    {"name":"synchronizerUsageSupport"},
+    {"name":"threadAllocatedMemorySupport"},
+    {"name":"threadContentionMonitoringSupport"}
+  ]
+}
+]

temporal-testing/src/main/resources/META-INF/native-image/io.temporal/temporal-testing/native-image.properties temporal-serviceclient/src/main/resources/META-INF/native-image/io/temporal/temporal-serviceclient/native-image.properties

@@ -22,12 +22,12 @@ Args = --initialize-at-build-time=org.slf4j.impl.StaticLoggerBinder \
   --initialize-at-build-time=org.slf4j.LoggerFactory \
   --initialize-at-run-time=io.grpc.netty.shaded.io.netty.channel.epoll \
   --initialize-at-run-time=io.grpc.netty.shaded.io.netty.channel.unix \
+  --initialize-at-run-time=io.grpc.netty.shaded.io.netty.util.internal.logging.Slf4JLoggerFactory$NopInstanceHolder \
   --initialize-at-run-time=io.grpc.netty.shaded.io.netty.util.internal.logging.Log4JLogger \
   --initialize-at-run-time=io.grpc.netty.shaded.io.netty.internal.tcnative \
   --initialize-at-run-time=io.grpc.netty.shaded.io.netty.handler.ssl \
   -H:DynamicProxyConfigurationResources=${.}/proxy-config.json \
   -H:JNIConfigurationResources=${.}/jni-config.json \
   -H:ReflectionConfigurationResources=${.}/reflect-config.json \
   -H:ResourceConfigurationResources=${.}/resource-config.json \
-  -H:SerializationConfigurationResources=${.}/serialization-config.json
-
+  -H:SerializationConfigurationResources=${.}/serialization-config.json

temporal-serviceclient/src/main/resources/META-INF/native-image/io/temporal/temporal-serviceclient/proxy-config.json

@@ -0,0 +1,5 @@
+[
+  {
+    "interfaces":["io.temporal.client.WorkflowClient"]
+  }
+]