This is an automated email from the ASF dual-hosted git repository.
ricardozanini pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-kie-kogito-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 458a18df0 [Fix #616] Adding dependency documentation to embedded
(#620)
458a18df0 is described below
commit 458a18df0ced54ee9663d7bae9d640103936a3e6
Author: Francisco Javier Tirado Sarti
<[email protected]>
AuthorDate: Tue Apr 9 14:28:03 2024 +0200
[Fix #616] Adding dependency documentation to embedded (#620)
---
serverlessworkflow/antora.yml | 11 +++++++
.../ROOT/pages/core/custom-functions-support.adoc | 5 +--
.../getting-started/java-embedded-workflows.adoc | 38 ++++++++++++++++++++--
3 files changed, 49 insertions(+), 5 deletions(-)
diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml
index e55fad243..819fbd413 100644
--- a/serverlessworkflow/antora.yml
+++ b/serverlessworkflow/antora.yml
@@ -82,6 +82,8 @@ asciidoc:
kogito_examples_url:
https://github.com/apache/incubator-kie-kogito-examples.git
kogito_apps_url:
https://github.com/apache/incubator-kie-kogito-apps/tree/main
kogito_runtimes_url:
https://github.com/apache/incubator-kie-kogito-runtimes/tree/main
+ kogito_runtimes_swf_url:
https://github.com/apache/incubator-kie-kogito-runtimes/tree/main/kogito-serverless-workflow/
+ kogito_runtimes_swf_test_url:
https://github.com/apache/incubator-kie-kogito-runtimes/tree/main/kogito-serverless-workflow/kogito-serverless-workflow-executor-tests/src/test/java/org/kie/kogito/serverless/workflow/executor
quarkus_cli_url: https://quarkus.io/guides/cli-tooling
spec_website_url: https://serverlessworkflow.io/
spec_doc_url:
https://github.com/serverlessworkflow/specification/blob/0.8.x/specification.md
@@ -125,6 +127,15 @@ asciidoc:
golang_install_url: https://go.dev/doc/install
serverless_logic_web_tools_url: https://start.kubesmarts.org/
swf_executor_core_maven_repo_url:
https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-executor-core
+ swf_fluent_maven_repo_url:
https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-fluent
+ swf_executor_rest_maven_repo_url:
https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-executor-rest
+ swf_executor_python_maven_repo_url:
https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-executor-python
+ swf_executor_grpc_maven_repo_url:
https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-executor-grpc
+ swf_executor_events_maven_repo_url:
https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-executor-kafka
+ swf_executor_service_maven_repo_url:
https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-executor-service
+ swf_executor_openapi_maven_repo_url:
https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-openapi-parser
+ rocksdb_addon_maven_repo_url:
https://mvnrepository.com/artifact/org.kie.kogito/kogito-addons-persistence-rocksdb
+ rocksdb_url: https://rocksdb.org/
github_tokens_url: https://github.com/settings/tokens
openshift_developer_sandbox_url:
https://developers.redhat.com/developer-sandbox
openshift_application_data_services_service_account_url:
https://console.redhat.com/application-services/service-accounts
diff --git
a/serverlessworkflow/modules/ROOT/pages/core/custom-functions-support.adoc
b/serverlessworkflow/modules/ROOT/pages/core/custom-functions-support.adoc
index f299d1c80..5eff9a08b 100644
--- a/serverlessworkflow/modules/ROOT/pages/core/custom-functions-support.adoc
+++ b/serverlessworkflow/modules/ROOT/pages/core/custom-functions-support.adoc
@@ -300,7 +300,7 @@ The Camel route is responsible to produce the return value
in a way that the wor
include::../../pages/_common-content/camel-valid-responses.adoc[]
-[[con-func-python]
+[[con-func-python]]
== Python custom function
{product_name} implements a custom function to execute embedded Python scripts
and functions. See
xref:use-cases/advanced-developer-use-cases/integrations/custom-functions-knative.adoc[Invoking
Python from {product_name}]
@@ -535,7 +535,8 @@ kogito.sw.functions.greet.timeout=5000 <1>
----
<1> Time in milliseconds
-== Rest custom function
+[[con-func-rest]]
+== REST custom function
Serverless Workflow Specification defines the
xref:service-orchestration/orchestration-of-openapi-based-services.adoc[OpenAPI
function type], which is the preferred way to interact with existing REST
servers.
However, sometimes a workflow should interact with several REST APIs that are
not described using an OpenAPI specification file. Since generating such files
for these services might be tedious, {product_name} offers REST custom type as
a shortcut.
diff --git
a/serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc
b/serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc
index bacfae958..86c86e6ef 100644
---
a/serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc
@@ -1,4 +1,10 @@
= Workflow embedded execution in Java
+:compat-mode!:
+// Metadata:
+:description: Embedded execution of Workflows
+:keywords: kogito, workflow, embedded, java, sonataflow
+
+
This guide uses a standard Java virtual machine and a small set of Maven
dependencies to execute a link:{spec_doc_url}[CNCF Serverless Workflow]
definition. Therefore, it is assumed you are fluent both in Java and Maven.
The workflow definition to be executed can be read from a `.json` or `.yaml`
file or programmatically defined using the {product_name} fluent API.
@@ -54,7 +60,7 @@ Workflow execution result is {"greeting":"Hello
World","mantra":"Serverless Work
[[embedded-fluent-quick-start]]
== Hello world (using fluent API)
-Using the same Maven setup as in the previous section, you can
programmatically generate that workflow definition rather than loading it from
a file definition by using the
link:{kogito_runtimes_url}/kogito-serverless-workflow/kogito-serverless-workflow-fluent/src/main/java/org/kie/kogito/serverless/workflow/fluent[fluent
API]
+Adding link:{swf_fluent_maven_repo_url}[kogito-serverless-workflow-fluent]
dependency to the Maven setup in the previous section, you can programmatically
generate that workflow definition rather than loading it from a file definition
by using the
link:{kogito_runtimes_url}/kogito-serverless-workflow/kogito-serverless-workflow-fluent/src/main/java/org/kie/kogito/serverless/workflow/fluent[fluent
API]
Therefore, you can modify the previous example to generate the same output
when it is executed, but rather than creating a `FileReader` that reads the
`Workflow` object, we create the `Workflow` object using Java statements. The
resulting modified main method is the following
@@ -78,11 +84,37 @@ Therefore, you can modify the previous example to generate
the same output when
<6> Build the workflow definition
<7> Execute and print as in previous example
-
-== Further reading
+=== Additional fluent examples
You can find additional and commented examples of fluent API usage (including
jq expression evaluation and orchestration of rest services)
link:{kogito_sw_examples_url}/sonataflow-fluent[here]
+== Dependencies explanation
+
+Embedded workflow uses a modular approach to keep the number of required
dependencies as small as possible. The rationale is to avoid adding something
that you will not use to the dependency set. For example, the OpenAPI module is
based on a Swagger parser, if you are not going to call any OpenAPI service, it
is better to avoid adding Swagger to the dependency set. This means the
link:{swf_executor_core_maven_repo_url}[Core] dependency does not include the
stuff to use gRPC, OpenAPI, or [...]
+
+This is the list of additional dependencies you might need to add depending on
the functionality you are using:
+
+* link:{swf_executor_rest_maven_repo_url}[REST]: Add if you use
xref:core/custom-functions-support#con-func-rest[custom Rest] function type.
+* link:{swf_executor_service_maven_repo_url}[Service]: Add if your use
xref:core/custom-functions-support#con-func-java[custom Service] function type.
+* link:{swf_executor_openapi_maven_repo_url}[OpenAPI]: Add if you use
link:{spec_doc_url}#using-functions-for-restful-service-invocations[OpenAPI]
function type. See
link:{kogito_runtimes_swf_test_url}/OpenAPIWorkflowApplicationTest.java[example].
+* link:{swf_executor_grpc_maven_repo_url}[gRPC]: Add if you use
link:{spec_doc_url}#using-functions-for-rpc-service-invocations[gRPC] function
type. See
link:{kogito_runtimes_swf_test_url}/RPCWorkflowApplicationTest.java[example].
+* link:{swf_executor_python_maven_repo_url}[Python]: Add if you use
xref:core/custom-functions-support#con-func-python[custom Python] function
type. See
link:{kogito_runtimes_swf_url}/kogito-serverless-workflow-executor-python/src/test/java/org/kie/kogito/serverless/workflow/executor/PythonFluentWorkflowApplicationTest.java[example].
+* link:{swf_executor_events_maven_repo_url}[Events]: Add if you use Event or
Callback state in your workflow. Only Kafka events are supported right now. See
link:{kogito_runtimes_swf_url}/kogito-serverless-workflow-executor-kafka/src/test/java/org/kie/kogito/serverless/workflow/executor/WorkflowEventPublisherTest.java[Publisher]
and
link:{kogito_runtimes_swf_url}/kogito-serverless-workflow-executor-kafka/src/test/java/org/kie/kogito/serverless/workflow/executor/WorkflowEventSusbcriberTes
[...]
+
+== Persistence support
+
+To enable persistence, you must include the desired {product_name} persistence
add-on as a dependency and set up `StaticWorkflowApplication` to use the
`ProcessInstances` implementation provided by the add-on.
+
+Since, within an embedded environment, you usually do not want to contact an
external database, the recommendation is to use the link:{rocksdb_url}[rocksdb]
embedded database. You do that by adding the
link:{rocksdb_addon_maven_repo_url}[rocksdb add-on] dependency and adding the
following code snippet when you create your `StaticWorkflowApplication` object.
+
+[source,java]
+----
+ StaticWorkflowApplication.create().processInstancesFactory(new
RocksDBProcessInstancesFactory(new Options().setCreateIfMissing(true),
tempDir.toString()))
+----
+
+See the
link:{kogito_runtimes_swf_test_url}/PersistentApplicationTest.java[persistence
example].
+
+
== Additional resources
include::../../pages/_common-content/report-issue.adoc[]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
