From 7dc6700c2b38749ae0cf6a8117d81fde125c2345 Mon Sep 17 00:00:00 2001 From: Christophe Bornet Date: Thu, 24 Nov 2022 15:55:47 +0100 Subject: [PATCH] [improve][doc] Add doc for builtin functions (#18569) Co-authored-by: tison --- .../docs/functions-deploy-cluster-builtin.md | 16 +++ site2/docs/functions-deploy-cluster.md | 1 + site2/docs/functions-package-java.md | 101 +++++++++++++++++- site2/website/sidebars.json | 3 +- 4 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 site2/docs/functions-deploy-cluster-builtin.md diff --git a/site2/docs/functions-deploy-cluster-builtin.md b/site2/docs/functions-deploy-cluster-builtin.md new file mode 100644 index 0000000000000..2e0e3b3cd38cd --- /dev/null +++ b/site2/docs/functions-deploy-cluster-builtin.md @@ -0,0 +1,16 @@ +--- +id: functions-deploy-cluster-builtin +title: Use built-in functions +sidebar_label: "Use built-in functions" +--- + +Similar to built-in connectors, the code of Java functions [packaged as NAR](functions-package-java.md) that are placed in the `functions` directory of the function worker are loaded at startup and can be referenced when creating a function. + +For instance if you have a built-in function with name `exclamation` in its `pulsar-io.yaml`, you can create a function instance with: + +```bash +bin/pulsar-admin functions create \ + --function-type exclamation \ + --inputs persistent://public/default/input-1 \ + --output persistent://public/default/output-1 +``` diff --git a/site2/docs/functions-deploy-cluster.md b/site2/docs/functions-deploy-cluster.md index 042d5a3d2edbc..ccfd36e63de8f 100644 --- a/site2/docs/functions-deploy-cluster.md +++ b/site2/docs/functions-deploy-cluster.md @@ -31,4 +31,5 @@ bin/pulsar-admin functions update \ * [Enable parallel processing](functions-deploy-cluster-parallelism.md) * [Enable end-to-end encryption](functions-deploy-cluster-encryption.md) * [Enable package management service](functions-deploy-cluster-package.md) +* [Use built-in functions](functions-deploy-cluster-builtin.md) diff --git a/site2/docs/functions-package-java.md b/site2/docs/functions-package-java.md index f2187a1435771..daa3bf8aa4c10 100644 --- a/site2/docs/functions-package-java.md +++ b/site2/docs/functions-package-java.md @@ -4,13 +4,25 @@ title: Package Java Functions sidebar_label: "Package Java Functions" --- +There are two methods to package Java Functions, that is [uber JAR](#package-as-jar) and [NAR](#package-as-nar). + :::note +If you plan to package and distribute your function for others to use, you are obligated to +license and copyright your own code properly. Remember to add the license and copyright to +all libraries your code uses and to your distribution. + +If you use the [NAR](#package-as-nar) method, the NAR plugin +automatically creates a `DEPENDENCIES` file in the generated NAR package, including the proper +licensing and copyrights of all libraries of your function. + For the runtime Java version, refer to [Pulsar Runtime Java Version Recommendation](https://github.com/apache/pulsar/blob/master/README.md#pulsar-runtime-java-version-recommendation) according to your target Pulsar version. ::: -To package a Java function, complete the following steps. +## Package as JAR + +To package a Java function as JAR, complete the following steps. 1. Create a new maven project with a pom file. In the following code sample, the value of `mainClass` is your package name. @@ -106,3 +118,90 @@ To package a Java function, complete the following steps. 07:55:03.724 [main] INFO org.apache.pulsar.functions.runtime.ProcessRuntime - Started process successfully ... ``` + +## Package as NAR + +To package a Java function as NAR, complete the following steps. + +1. Create a new maven project with a pom file. + + ```xml + + + 4.0.0 + + java-function + java-function + 1.0-SNAPSHOT + + + + org.apache.pulsar + pulsar-functions-api + @pulsar:version@ + + + + + + + org.apache.nifi + nifi-nar-maven-plugin + 1.2.0 + + + org.apache.maven.plugins + maven-compiler-plugin + + 17 + + + + + + + ``` + + You must also create a `resources/META-INF/services/pulsar-io.yaml` file. In the following code sample, the value of `functionClass` is your function class name. The `name` is the one used when the Function is deployed as a [built-in](functions-deploy-cluster-builtin.md) one. + + ```yaml + name: java-function + description: my java function + functionClass: org.example.test.ExclamationFunction + ``` + +2. Package your Java function. + + ```bash + mvn package + ``` + + After the Java function is packaged, a `target` directory is created automatically. Open the `target` directory to check if there is a NAR package similar to `java-function-1.0-SNAPSHOT.nar`. + +3. Copy the packaged NAR file to the Pulsar image. + + ```bash + docker cp CONTAINER ID:/pulsar + ``` + +4. Run the Java function using the following command. + + ```bash + ./bin/pulsar-admin functions localrun \ + --jar java-function-1.0-SNAPSHOT.nar \ + --inputs persistent://public/default/my-topic-1 \ + --output persistent://public/default/test-1 \ + --tenant public \ + --namespace default \ + --name JavaFunction + ``` + + The following log indicates that the Java function starts successfully. + + ```text + ... + 07:55:03.724 [main] INFO org.apache.pulsar.functions.runtime.ProcessRuntime - Started process successfully + ... + ``` diff --git a/site2/website/sidebars.json b/site2/website/sidebars.json index 0e80e22c9e249..630ce31f8a968 100644 --- a/site2/website/sidebars.json +++ b/site2/website/sidebars.json @@ -102,7 +102,8 @@ "functions-deploy-cluster-resource", "functions-deploy-cluster-parallelism", "functions-deploy-cluster-encryption", - "functions-deploy-cluster-package" + "functions-deploy-cluster-package", + "functions-deploy-cluster-builtin" ] }, "functions-deploy-trigger"