Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(sdk): Update Java Client and spring SDK docs #5055

Merged
merged 3 commits into from
Feb 26, 2025
Merged

docs(sdk): Update Java Client and spring SDK docs #5055

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
285592d
docs(sdk): Update Java Client and spring SDK docs
houssain-barouni Feb 21, 2025
7b6e831
docs: apply requested changes in code review
houssain-barouni Feb 25, 2025
d4ad1e5
the cloud properties changed a bit
jonathanlukas Feb 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 32 additions & 32 deletions docs/apis-tools/java-client/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,26 +17,26 @@ To use the Java client library, declare the following Maven dependency in your p
```xml
<dependency>
<groupId>io.camunda</groupId>
<artifactId>zeebe-client-java</artifactId>
<version>${zeebe.version}</version>
<artifactId>camunda-client-java</artifactId>
<version>${camunda.version}</version>
</dependency>
```

If you are using Gradle, declare the following:

```groovy
implementation 'io.camunda:zeebe-client-java:${zeebe.version}'
implementation 'io.camunda:camunda-client-java:${camunda.version}'
```

Use the latest released version from [Maven Central](https://search.maven.org/artifact/io.camunda/zeebe-client-java).
Use the latest released version from [Maven Central](https://search.maven.org/artifact/io.camunda/camunda-client-java).

## Bootstrapping

In Java code, instantiate the client as follows:

```java
private static final String zeebeGrpc = "[Zeebe Address e.g. grpcs://f887f1a6-7c2b-48ce-809a-e11e5a6ba31a.dsm-1.zeebe.camunda.io:443]";
private static final String zeebeRest = "[Zeebe Address e.g. https://dsm-1.zeebe.camunda.io/f887f1a6-7c2b-48ce-809a-e11e5a6ba31a]";
private static final String zeebeGrpc = "[Gateway gRPC Address e.g. grpcs://f887f1a6-7c2b-48ce-809a-e11e5a6ba31a.dsm-1.zeebe.camunda.io:443]";
private static final String zeebeRest = "[Gateway REST Address e.g. https://dsm-1.zeebe.camunda.io/f887f1a6-7c2b-48ce-809a-e11e5a6ba31a]";
private static final String audience = "[Zeebe Token Audience, e.g., zeebe.camunda.io]";
private static final String clientId = "[Client ID, e.g., FmT7K8gVv_FcwiUhc8U-fAJ9wph0Kn~P]";
private static final String clientSecret = "[Client Secret]";
Expand All @@ -51,7 +51,7 @@ In Java code, instantiate the client as follows:
.clientSecret(clientSecret)
.build();

try (ZeebeClient client = ZeebeClient.newClientBuilder()
try (CamundaClient client = CamundaClient.newClientBuilder()
.grpcAddress(URI.create(zeebeGrpc))
.restAddress(URI.create(zeebeRest))
.credentialsProvider(credentialsProvider)
Expand All @@ -68,27 +68,27 @@ Let's go over this code snippet line by line:
3. Create the client by passing in the address of the cluster we want to connect to and the credentials provider from the step above. Note that a client should be closed after usage, which is easily achieved by the try-with-resources statement.
4. Send a test request to verify the connection was established.

Refer to [io.camunda.zeebe.client.ZeebeClientBuilder](https://javadoc.io/doc/io.camunda/zeebe-client-java/latest/io/camunda/zeebe/client/ZeebeClientBuilder.html) for a description of all available configuration properties.
Refer to [io.camunda.client.CamundaClientBuilder](https://javadoc.io/doc/io.camunda/camunda-client-java/latest/io/camunda/client/CamundaClientBuilder.html) for a description of all available configuration properties.

Another (more compact) option is to pass in the connection settings via environment variables:

```bash
export ZEEBE_GRPC_ADDRESS='[Zeebe gRPC Address]'
export ZEEBE_REST_ADDRESS='[Zeebe REST Address]'
export ZEEBE_CLIENT_ID='[Client ID]'
export ZEEBE_CLIENT_SECRET='[Client Secret]'
export ZEEBE_AUTHORIZATION_SERVER_URL='[OAuth API]'
export CAMUNDA_GRPC_ADDRESS='[Gateway gRPC Address]'
export CAMUNDA_REST_ADDRESS='[Gateway REST Address]'
export CAMUNDA_CLIENT_ID='[Client ID]'
export CAMUNDA_CLIENT_SECRET='[Client Secret]'
export CAMUNDA_AUTHORIZATION_SERVER_URL='[OAuth API]'
```

When you create client credentials in Camunda 8, you have the option to download a file with the lines above filled out for you.

Given these environment variables, you can instantiate the client as follows:

```java
ZeebeClient client =
ZeebeClient.newClientBuilder()
.grpcAddress(System.getenv("ZEEBE_GRPC_ADDRESS"))
.restAddress(System.getenv("ZEEBE_REST_ADDRESS"))
CamundaClient client =
CamundaClient.newClientBuilder()
.grpcAddress(System.getenv("CAMUNDA_GRPC_ADDRESS"))
.restAddress(System.getenv("CAMUNDA_REST_ADDRESS"))
.build();
```

Expand All @@ -102,10 +102,10 @@ Several identity providers, such as Keycloak, support client X.509 authorizers a

As a prerequisite, ensure you have proper KeyStore and TrustStore configured, so that:

- Both the Spring Zeebe application and identity provider share the same CA trust certificates.
- Both the Spring Zeebe and identity provider own certificates signed by trusted CA.
- Your Spring Zeebe application own certificate has proper `Distinguished Name` (DN), e.g.
`CN=My Zeebe Client, OU=Camunda Users, O=Best Company, C=DE`.
- Both the Spring Camunda application and identity provider share the same CA trust certificates.
- Both the Spring Camunda and identity provider own certificates signed by trusted CA.
- Your Spring Camunda application own certificate has proper `Distinguished Name` (DN), e.g.
`CN=My Camunda Client, OU=Camunda Users, O=Best Company, C=DE`.
- Your application DN registered in the identity provider client authorization details.

In that case, configuring `OAuthCredentialsProvider` might look like this
Expand All @@ -116,7 +116,7 @@ final OAuthCredentialsProvider provider =
.clientId("myClient")
.clientSecret("")
.audience("myClient-aud")
.authorizationServerUrl(ZEEBE_AUTHORIZATION_SERVER_URL)
.authorizationServerUrl(System.getenv("CAMUNDA_AUTHORIZATION_SERVER_URL"))
.keystorePath(Paths.get("/path/to/keystore.p12"))
.keystorePassword("password")
.keystoreKeyPassword("password")
Expand All @@ -128,26 +128,26 @@ final OAuthCredentialsProvider provider =
Or via environment variables:

```bash
export ZEEBE_CLIENT_ID='[Client ID]'
export ZEEBE_CLIENT_SECRET=''
export ZEEBE_AUTHORIZATION_SERVER_URL='[OAuth API]'
export ZEEBE_SSL_CLIENT_KEYSTORE_PATH='[Keystore path]'
export ZEEBE_SSL_CLIENT_KEYSTORE_SECRET='[Keystore password]'
export ZEEBE_SSL_CLIENT_KEYSTORE_KEY_SECRET='[Keystore material password]'
export ZEEBE_SSL_CLIENT_TRUSTSTORE_PATH='[Truststore path]'
export ZEEBE_SSL_CLIENT_TRUSTSTORE_SECRET='[Truststore password]'
export CAMUNDA_CLIENT_ID='[Client ID]'
export CAMUNDA_CLIENT_SECRET=''
export CAMUNDA_AUTHORIZATION_SERVER_URL='[OAuth API]'
export CAMUNDA_SSL_CLIENT_KEYSTORE_PATH='[Keystore path]'
export CAMUNDA_SSL_CLIENT_KEYSTORE_SECRET='[Keystore password]'
export CAMUNDA_SSL_CLIENT_KEYSTORE_KEY_SECRET='[Keystore material password]'
export CAMUNDA_SSL_CLIENT_TRUSTSTORE_PATH='[Truststore path]'
export CAMUNDA_SSL_CLIENT_TRUSTSTORE_SECRET='[Truststore password]'
```

Refer to your identity provider documentation on how to configure X.509 authentication. For example, [Keycloak](https://www.keycloak.org/server/mutual-tls).

## Javadoc

The official Java client library API documentation can be found [here](https://javadoc.io/doc/io.camunda/zeebe-client-java). These are standard Javadocs, so your favorite JVM IDE will be able to install them locally as well.
The official Java client library API documentation can be found [here](https://javadoc.io/doc/io.camunda/camunda-client-java). These are standard Javadocs, so your favorite JVM IDE will be able to install them locally as well.

## Next steps

- [Getting Started Guide](https://github.com/camunda/camunda-platform-get-started): A comprehensive tutorial that covers Camunda Modeler, Operate, and the Java client.
- [Job worker](job-worker.md): An introduction to the Java client's job worker.
- [Logging](logging.md): An introduction to configuring logging for a Zeebe client.
- [Logging](logging.md): An introduction to configuring logging for a Camunda client.
- [Writing tests](zeebe-process-test.md): An introduction to unit testing processes.
- [Examples](apis-tools/java-client-examples/index.md): A collection of specific examples for different use cases.
16 changes: 8 additions & 8 deletions docs/apis-tools/java-client/job-worker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ If streaming is enabled (via `streamEnabled`), it will also open a long-living s

When a poll fails with an error response, the job worker applies a backoff strategy. It waits for some time, after which it polls again for more jobs. This gives a Zeebe cluster some time to recover from a failure. In some cases, you may want to configure this backoff strategy to better fit your situation.

The retry delay (i.e. the time the job worker waits after an error before the next poll for new jobs) is provided by the [`BackoffSupplier`](https://github.com/camunda/camunda/blob/b9165e9759143e80e7e3bd2a884837cf141276a1/clients/java/src/main/java/io/camunda/zeebe/client/api/worker/BackoffSupplier.java). You can replace it using the `.backoffSupplier()` method on the [`JobWorkerBuilder`](https://github.com/camunda/camunda/blob/b9165e9759143e80e7e3bd2a884837cf141276a1/clients/java/src/main/java/io/camunda/zeebe/client/api/worker/JobWorkerBuilderStep1.java).
The retry delay (i.e. the time the job worker waits after an error before the next poll for new jobs) is provided by the [`BackoffSupplier`](https://github.com/camunda/camunda/blob/main/clients/java/src/main/java/io/camunda/client/api/worker/BackoffSupplier.java). You can replace it using the `.backoffSupplier()` method on the [`JobWorkerBuilder`](https://github.com/camunda/camunda/blob/main/clients/java/src/main/java/io/camunda/client/api/worker/JobWorkerBuilderStep1.java).

By default, the job worker uses an exponential backoff implementation, which you can configure using `BackoffSupplier.newBackoffBuilder()`.

Expand All @@ -60,7 +60,7 @@ Zeebe's [backpressure mechanism](../../../self-managed/zeebe-deployment/operatio

## Metrics

The job worker exposes metrics through a custom interface: [JobWorkerMetrics](https://github.com/camunda/camunda/blob/main/clients/java/src/main/java/io/camunda/zeebe/client/api/worker/JobWorkerMetrics.java). These represent specific callbacks used by the job worker to keep track of various internals, e.g. count of jobs activated, count of jobs handled, etc.
The job worker exposes metrics through a custom interface: [JobWorkerMetrics](https://github.com/camunda/camunda/blob/main/clients/java/src/main/java/io/camunda/client/api/worker/JobWorkerMetrics.java). These represent specific callbacks used by the job worker to keep track of various internals, e.g. count of jobs activated, count of jobs handled, etc.

:::note
By default, job workers will not track any metrics, and it's up to the caller to specify an implementation if they wish to make use of this feature.
Expand All @@ -82,7 +82,7 @@ Additionally, by subtracting both counters, you can derive the count of queued o
To use job worker metrics, create a new instance of a `JobWorkerMetrics` implementation, and pass it along to the builder:

```java
public final JobWorker openWorker(final ZeebeClient client, final JobHandler handler) {
public final JobWorker openWorker(final CamundaClient client, final JobHandler handler) {
final JobWorkerMetrics metrics = new MyCustomJobWorkerMetrics();
return client.newJobWorker()
.jobType("foo")
Expand All @@ -105,7 +105,7 @@ If your project does not yet use Micrometer, you need to add it to your dependen
Once Micrometer is set up in your project, you can start using the implementation. For example:

```java
public final JobWorker openWorker(final ZeebeClient client, final JobHandler handler) {
public final JobWorker openWorker(final CamundaClient client, final JobHandler handler) {
final MeterRegistry meterRegistry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);
final JobWorkerMetrics metrics = JobWorkerMetrics
.micrometer()
Expand Down Expand Up @@ -143,7 +143,7 @@ Here's an example using Micrometer APIs that integrate a gRPC [ClientInterceptor
```java
import java.nio.channels.AsynchronousCloseException;

public ZeebeClientBuilder configureClientMetrics(final ZeebeClientBuilder builder, final MeterRegistry meterRegistry, final ObservationRegistry observationRegistry) {
public CamundaClientBuilder configureClientMetrics(final CamundaClientBuilder builder, final MeterRegistry meterRegistry, final ObservationRegistry observationRegistry) {
final ClientInterceptor monitoringInterceptor = new MetricCollectingClientInterceptor(meterRegistry);
final AsyncExecChainHandler monitoringHandler = new ObservationExecChainHandler(observationRegistry);
return builder.withInterceptors(monitoringInterceptor).withChainHandlers(monitoringHandler);
Expand All @@ -155,8 +155,8 @@ public ZeebeClientBuilder configureClientMetrics(final ZeebeClientBuilder builde
If you wish to tune your job worker executor, you can pass a custom, instrumented executor to the client builder. For example, if we use Micrometer:

```java
public ZeebeClientBuilder configureClientMetrics(
final ZeebeClientBuilder builder,
public CamundaClientBuilder configureClientMetrics(
final CamundaClientBuilder builder,
final ScheduledExecutorService executor,
final MeterRegistry meterRegistry) {
final ScheduledExecutorService instrumentedExecutor = ExecutorServiceMetrics.monitor(meterRegistry, executor, "job-worker-executor");
Expand Down Expand Up @@ -247,4 +247,4 @@ client.newWorker()
### Default tenant

You can configure the default tenant(s) using environment variables or system properties. It's configured using
`DEFAULT_JOB_WORKER_TENANT_IDS` or `zeebe.client.worker.tenantIds` respectively.
`CAMUNDA_DEFAULT_JOB_WORKER_TENANT_IDS` or `camunda.client.worker.tenantIds` respectively.
Loading
Loading