feat(baseUrl): add UrlResolver

clients/java/client/src/it/java/org/camunda/bpm/client/client/ClientIT.java

@@ -38,6 +38,7 @@
 import java.util.concurrent.atomic.AtomicReference;
 import org.camunda.bpm.client.ExternalTaskClient;
 import org.camunda.bpm.client.ExternalTaskClientBuilder;
+import org.camunda.bpm.client.UrlResolver;
 import org.camunda.bpm.client.backoff.BackoffStrategy;
 import org.camunda.bpm.client.backoff.ErrorAwareBackoffStrategy;
 import org.camunda.bpm.client.dto.ProcessDefinitionDto;
@@ -233,6 +234,30 @@ public void shouldThrowExceptionDueToBaseUrlIsNull() {
     }
   }
 
+  @Test
+  public void shouldThrowExceptionDueToBaseUrlAndBaseUrlResolverIsNull() {
+    ExternalTaskClient client = null;
+
+    try {
+      // given
+      ExternalTaskClientBuilder externalTaskClientBuilder = ExternalTaskClient.create();
+
+      // then
+      thrown.expect(ExternalTaskClientException.class);
+
+      // when
+      client = externalTaskClientBuilder
+          .baseUrl(null)
+          .urlResolver(null)
+          .build();
+    }
+    finally {
+      if (client != null) {
+        client.stop();
+      }
+    }
+  }
+
   @Test
   public void shouldThrowExceptionDueToMaxTasksNotGreaterThanZero() {
     ExternalTaskClient client = null;

clients/java/client/src/main/java/org/camunda/bpm/client/ExternalTaskClientBuilder.java

@@ -16,14 +16,13 @@
  */
 package org.camunda.bpm.client;
 
+import java.util.function.Consumer;
 import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
 import org.camunda.bpm.client.backoff.BackoffStrategy;
 import org.camunda.bpm.client.backoff.ExponentialBackoffStrategy;
 import org.camunda.bpm.client.exception.ExternalTaskClientException;
 import org.camunda.bpm.client.interceptor.ClientRequestInterceptor;
 
-import java.util.function.Consumer;
-
 /**
  * <p>A fluent builder to configure the Camunda client</p>
  *
@@ -33,12 +32,42 @@ public interface ExternalTaskClientBuilder {
 
   /**
    * Base url of the Camunda BPM Platform REST API. This information is mandatory.
+   * <p>
+   * If this method is used, it will create a permanent url resolver with the given baseUrl.
    *
    * @param baseUrl of the Camunda BPM Platform REST API
    * @return the builder
    */
   ExternalTaskClientBuilder baseUrl(String baseUrl);
 
+  /**
+   * Url resolver of the Camunda BPM Platform REST API. This information is mandatory.
+   * <p>
+   * If the server is in a cluster or you are using spring cloud, you can create a class which implements UrlResolver..
+   * <p>
+   * this is a sample for spring cloud DiscoveryClient
+   * <p>
+   * public class CustomUrlResolver implements UrlResolver{
+   * <p>
+   * protected String serviceId;
+   * <p>
+   * protected DiscoveryClient discoveryClient;
+   * <p>
+   * protected String getRandomServiceInstance() {
+   * List<ServiceInstance> serviceInstances = discoveryClient.getInstances(serviceId);
+   * Random random = new Random();
+   * return serviceInstances.get(random.nextInt(serviceInstances.size())).getUri().toString();
+   * }
+   *
+   * @param urlResolver of the Camunda BPM Platform REST API
+   * @return the builder
+   * @Override public String getBaseUrl() {
+   * return getRandomServiceInstance();
+   * }
+   * }
+   */
+  ExternalTaskClientBuilder urlResolver(UrlResolver urlResolver);
+
   /**
    * A custom worker id the Workflow Engine is aware of. This information is optional.
    * Note: make sure to choose a unique worker id
@@ -144,10 +173,10 @@ public interface ExternalTaskClientBuilder {
 
   /**
    * @param lockDuration <ul>
-   *                       <li> in milliseconds to lock the external tasks
-   *                       <li> must be greater than zero
-   *                       <li> the default lock duration is 20 seconds (20,000 milliseconds)
-   *                       <li> is overridden by the lock duration configured on a topic subscription
+   *                     <li> in milliseconds to lock the external tasks
+   *                     <li> must be greater than zero
+   *                     <li> the default lock duration is 20 seconds (20,000 milliseconds)
+   *                     <li> is overridden by the lock duration configured on a topic subscription
    *                     </ul>
    * @return the builder
    */
@@ -174,7 +203,7 @@ public interface ExternalTaskClientBuilder {
    * Disables the client-side backoff strategy. On invocation, the configuration option {@link #backoffStrategy} is ignored.
    * <p>
    * NOTE: Please bear in mind that disabling the client-side backoff can lead to heavy load situations on engine side.
-   *       To avoid this, please specify an appropriate {@link #asyncResponseTimeout(long)}.
+   * To avoid this, please specify an appropriate {@link #asyncResponseTimeout(long)}.
    *
    * @return the builder
    */
@@ -193,15 +222,14 @@ public interface ExternalTaskClientBuilder {
   /**
    * Bootstraps the Camunda client
    *
-   * @throws ExternalTaskClientException
-   * <ul>
-   *   <li> if base url is null or string is empty
-   *   <li> if hostname cannot be retrieved
-   *   <li> if maximum amount of tasks is not greater than zero
-   *   <li> if maximum asynchronous response timeout is not greater than zero
-   *   <li> if lock duration is not greater than zero
-   * </ul>
    * @return the builder
+   * @throws ExternalTaskClientException <ul>
+   *                                       <li> if base url is null or string is empty
+   *                                       <li> if hostname cannot be retrieved
+   *                                       <li> if maximum amount of tasks is not greater than zero
+   *                                       <li> if maximum asynchronous response timeout is not greater than zero
+   *                                       <li> if lock duration is not greater than zero
+   *                                     </ul>
    */
   ExternalTaskClient build();
 

clients/java/client/src/main/java/org/camunda/bpm/client/UrlResolver.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH
+ * under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright
+ * ownership. Camunda licenses this file to you under the Apache License,
+ * Version 2.0; you may not use this file 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.
+ */
+package org.camunda.bpm.client;
+
+/**
+ * Get service url of the Camunda server
+ */
+public interface UrlResolver {
+
+  String getBaseUrl();
+}

clients/java/client/src/main/java/org/camunda/bpm/client/impl/EngineClient.java

@@ -19,9 +19,9 @@
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
-
-import org.camunda.bpm.client.task.OrderingConfig;
+import org.camunda.bpm.client.UrlResolver;
 import org.camunda.bpm.client.task.ExternalTask;
+import org.camunda.bpm.client.task.OrderingConfig;
 import org.camunda.bpm.client.task.impl.ExternalTaskImpl;
 import org.camunda.bpm.client.task.impl.dto.BpmnErrorRequestDto;
 import org.camunda.bpm.client.task.impl.dto.CompleteRequestDto;
@@ -46,7 +46,8 @@ public class EngineClient {
   protected static final String ID_RESOURCE_PATH = EXTERNAL_TASK_RESOURCE_PATH + "/" + ID_PATH_PARAM;
   public static final String LOCK_RESOURCE_PATH = ID_RESOURCE_PATH + "/lock";
   public static final String EXTEND_LOCK_RESOURCE_PATH = ID_RESOURCE_PATH + "/extendLock";
-  public static final String SET_VARIABLES_RESOURCE_PATH = EXTERNAL_TASK__PROCESS_RESOURCE_PATH + "/" + ID_PATH_PARAM + "/variables";
+  public static final String SET_VARIABLES_RESOURCE_PATH =
+      EXTERNAL_TASK__PROCESS_RESOURCE_PATH + "/" + ID_PATH_PARAM + "/variables";
   public static final String UNLOCK_RESOURCE_PATH = ID_RESOURCE_PATH + "/unlock";
   public static final String COMPLETE_RESOURCE_PATH = ID_RESOURCE_PATH + "/complete";
   public static final String FAILURE_RESOURCE_PATH = ID_RESOURCE_PATH + "/failure";
@@ -56,7 +57,7 @@ public class EngineClient {
   public static final String PROCESS_INSTANCE_ID_RESOURCE_PATH = PROCESS_INSTANCE_RESOURCE_PATH + "/" + ID_PATH_PARAM;
   public static final String GET_BINARY_VARIABLE =
       PROCESS_INSTANCE_ID_RESOURCE_PATH + "/variables/" + NAME_PATH_PARAM + "/data";
-  protected String baseUrl;
+  protected UrlResolver urlResolver;
   protected String workerId;
   protected int maxTasks;
   protected boolean usePriority;
@@ -65,97 +66,136 @@ public class EngineClient {
   protected RequestExecutor engineInteraction;
   protected TypedValues typedValues;
 
-  public EngineClient(String workerId, int maxTasks, Long asyncResponseTimeout, String baseUrl, RequestExecutor engineInteraction) {
+  public EngineClient(String workerId,
+                      int maxTasks,
+                      Long asyncResponseTimeout,
+                      String baseUrl,
+                      RequestExecutor engineInteraction) {
     this(workerId, maxTasks, asyncResponseTimeout, baseUrl, engineInteraction, true, OrderingConfig.empty());
   }
 
-  public EngineClient(String workerId, int maxTasks, Long asyncResponseTimeout, String baseUrl, RequestExecutor engineInteraction,
-                      boolean usePriority, OrderingConfig orderingConfig) {
+  public EngineClient(String workerId,
+                      int maxTasks,
+                      Long asyncResponseTimeout,
+                      String baseUrl,
+                      RequestExecutor engineInteraction,
+                      boolean usePriority,
+                      OrderingConfig orderingConfig) {
+    this.workerId = workerId;
+    this.asyncResponseTimeout = asyncResponseTimeout;
+    this.maxTasks = maxTasks;
+    this.usePriority = usePriority;
+    this.engineInteraction = engineInteraction;
+    this.urlResolver = new PermanentUrlResolver(baseUrl);
+    this.orderingConfig = orderingConfig;
+  }
+
+  public EngineClient(String workerId,
+                      int maxTasks,
+                      Long asyncResponseTimeout,
+                      UrlResolver urlResolver,
+                      RequestExecutor engineInteraction) {
+    this(workerId, maxTasks, asyncResponseTimeout, urlResolver, engineInteraction, true, OrderingConfig.empty());
+  }
+
+  public EngineClient(String workerId,
+                      int maxTasks,
+                      Long asyncResponseTimeout,
+                      UrlResolver urlResolver,
+                      RequestExecutor engineInteraction,
+                      boolean usePriority,
+                      OrderingConfig orderingConfig) {
     this.workerId = workerId;
     this.asyncResponseTimeout = asyncResponseTimeout;
     this.maxTasks = maxTasks;
     this.usePriority = usePriority;
     this.engineInteraction = engineInteraction;
-    this.baseUrl = baseUrl;
+    this.urlResolver = urlResolver;
     this.orderingConfig = orderingConfig;
   }
 
-  public List<ExternalTask> fetchAndLock(List<TopicRequestDto> topics)  {
-    FetchAndLockRequestDto payload = new FetchAndLockRequestDto(workerId, maxTasks, asyncResponseTimeout,
-        topics, usePriority, orderingConfig);
+  public List<ExternalTask> fetchAndLock(List<TopicRequestDto> topics) {
+    FetchAndLockRequestDto payload = new FetchAndLockRequestDto(workerId, maxTasks, asyncResponseTimeout, topics,
+        usePriority, orderingConfig);
 
-    String resourceUrl = baseUrl + FETCH_AND_LOCK_RESOURCE_PATH;
+    String resourceUrl = getBaseUrl() + FETCH_AND_LOCK_RESOURCE_PATH;
     ExternalTask[] externalTasks = engineInteraction.postRequest(resourceUrl, payload, ExternalTaskImpl[].class);
     return Arrays.asList(externalTasks);
   }
 
-  public void lock(String taskId, long lockDuration)  {
+  public void lock(String taskId, long lockDuration) {
     LockRequestDto payload = new LockRequestDto(workerId, lockDuration);
     String resourcePath = LOCK_RESOURCE_PATH.replace("{id}", taskId);
-    String resourceUrl = baseUrl + resourcePath;
+    String resourceUrl = getBaseUrl() + resourcePath;
     engineInteraction.postRequest(resourceUrl, payload, Void.class);
   }
 
-  public void unlock(String taskId)  {
+  public void unlock(String taskId) {
     String resourcePath = UNLOCK_RESOURCE_PATH.replace("{id}", taskId);
-    String resourceUrl = baseUrl + resourcePath;
+    String resourceUrl = getBaseUrl() + resourcePath;
     engineInteraction.postRequest(resourceUrl, null, Void.class);
   }
 
-  public void complete(String taskId, Map<String, Object> variables, Map<String, Object> localVariables)  {
+  public void complete(String taskId, Map<String, Object> variables, Map<String, Object> localVariables) {
     Map<String, TypedValueField> typedValueDtoMap = typedValues.serializeVariables(variables);
     Map<String, TypedValueField> localTypedValueDtoMap = typedValues.serializeVariables(localVariables);
 
     CompleteRequestDto payload = new CompleteRequestDto(workerId, typedValueDtoMap, localTypedValueDtoMap);
     String resourcePath = COMPLETE_RESOURCE_PATH.replace("{id}", taskId);
-    String resourceUrl = baseUrl + resourcePath;
+    String resourceUrl = getBaseUrl() + resourcePath;
     engineInteraction.postRequest(resourceUrl, payload, Void.class);
   }
 
-  public void setVariables(String processId, Map<String, Object> variables)  {
+  public void setVariables(String processId, Map<String, Object> variables) {
     Map<String, TypedValueField> typedValueDtoMap = typedValues.serializeVariables(variables);
     SetVariablesRequestDto payload = new SetVariablesRequestDto(workerId, typedValueDtoMap);
     String resourcePath = SET_VARIABLES_RESOURCE_PATH.replace("{id}", processId);
-    String resourceUrl = baseUrl + resourcePath;
+    String resourceUrl = getBaseUrl() + resourcePath;
     engineInteraction.postRequest(resourceUrl, payload, Void.class);
   }
 
-
-  public void failure(String taskId, String errorMessage, String errorDetails, int retries, long retryTimeout, Map<String, Object> variables, Map<String, Object> localVariables)  {
+  public void failure(String taskId,
+                      String errorMessage,
+                      String errorDetails,
+                      int retries,
+                      long retryTimeout,
+                      Map<String, Object> variables,
+                      Map<String, Object> localVariables) {
     Map<String, TypedValueField> typedValueDtoMap = typedValues.serializeVariables(variables);
     Map<String, TypedValueField> localTypedValueDtoMap = typedValues.serializeVariables(localVariables);
 
-    FailureRequestDto payload = new FailureRequestDto(workerId, errorMessage, errorDetails, retries, retryTimeout, typedValueDtoMap, localTypedValueDtoMap);
+    FailureRequestDto payload = new FailureRequestDto(workerId, errorMessage, errorDetails, retries, retryTimeout,
+        typedValueDtoMap, localTypedValueDtoMap);
     String resourcePath = FAILURE_RESOURCE_PATH.replace("{id}", taskId);
-    String resourceUrl = baseUrl + resourcePath;
+    String resourceUrl = getBaseUrl() + resourcePath;
     engineInteraction.postRequest(resourceUrl, payload, Void.class);
   }
 
-  public void bpmnError(String taskId, String errorCode, String errorMessage, Map<String, Object> variables)  {
+  public void bpmnError(String taskId, String errorCode, String errorMessage, Map<String, Object> variables) {
     Map<String, TypedValueField> typeValueDtoMap = typedValues.serializeVariables(variables);
     BpmnErrorRequestDto payload = new BpmnErrorRequestDto(workerId, errorCode, errorMessage, typeValueDtoMap);
     String resourcePath = BPMN_ERROR_RESOURCE_PATH.replace("{id}", taskId);
-    String resourceUrl = baseUrl + resourcePath;
+    String resourceUrl = getBaseUrl() + resourcePath;
     engineInteraction.postRequest(resourceUrl, payload, Void.class);
   }
 
   public void extendLock(String taskId, long newDuration)  {
     ExtendLockRequestDto payload = new ExtendLockRequestDto(workerId, newDuration);
     String resourcePath = EXTEND_LOCK_RESOURCE_PATH.replace("{id}", taskId);
-    String resourceUrl = baseUrl + resourcePath;
+    String resourceUrl = getBaseUrl() + resourcePath;
     engineInteraction.postRequest(resourceUrl, payload, Void.class);
   }
 
   public byte[] getLocalBinaryVariable(String variableName, String executionId)  {
-    String resourcePath = baseUrl + GET_BINARY_VARIABLE
+    String resourcePath =  getBaseUrl()  + GET_BINARY_VARIABLE
             .replace(ID_PATH_PARAM, executionId)
             .replace(NAME_PATH_PARAM, variableName);
 
     return engineInteraction.getRequest(resourcePath);
   }
 
   public String getBaseUrl() {
-    return baseUrl;
+    return urlResolver.getBaseUrl();
   }
 
   public String getWorkerId() {