/* Licensed under the Apache License, Version 2.0 (the "License");
 * 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;

/**
 * <p>Service that provides possibilities to interact with fetched and locked tasks.</p>
 *
 * @author Tassilo Weidner
 */
public interface LockedTaskService {

  /**
   * Unlocks a task and clears the task’s lock expiration time and worker id.
   */
  void unlock();

  /**
   * Completes a task.
   */
  void complete();

  /**
   * Reports a failure to execute a task. A number of retries and a timeout until
   * the task can be specified. If the retries are set to 0, an incident for this
   * task is created.
   *
   * @param errorMessage indicates the reason of the failure.
   * @param errorDetails provides a detailed error description.
   * @param retries      specifies how often the task should be retried. Must be >= 0.
   *                     If 0, an incident is created and the task cannot be fetched anymore
   *                     unless the retries are increased again. The incident's message is set
   *                     to the {@param errorMessage} parameter.
   * @param retryTimeout specifies a timeout in milliseconds before the external task
   *                     becomes available again for fetching. Must be >= 0.
   */
  void failure(String errorMessage, String errorDetails, int retries, long retryTimeout);

  /**
   * Reports a business error in the context of a running task.
   * The error code must be specified to identify the BPMN error handler.
   *
   * @param errorCode that indicates the predefined error. The error code
   *                  is used to identify the BPMN error handler.
   */
  void bpmnError(String errorCode);

  /**
   * Extends the timeout of the lock by a given amount of time.
   *
   * @param newDuration specifies the the new lock duration in milliseconds
   */
  void extendLock(long newDuration);

}

@@ -843,56 +843,580 @@
    *
-/%0A  void unlock();%0A%0A  /**%0A   * Completes a task.
+%0A   * @throws UnlockTaskException%0A   * %3Cul%3E%0A   *   %3Cli%3E if the task has been canceled and therefore does not exist anymore%0A   *   %3Cli%3E if the connection could not be established%0A   * %3C/ul%3E%0A   */%0A  void unlock();%0A%0A  /**%0A   * Completes a task.%0A   *%0A   * @throws CompleteTaskException%0A   * %3Cul%3E%0A   *   %3Cli%3E if the task's most recent lock could not be acquired%0A   *   %3Cli%3E if the task has been canceled and therefore does not exist anymore%0A   *   %3Cli%3E if the corresponding process instance could not be resumed%0A   *   %3Cli%3E if the connection could not be established%0A   * %3C/ul%3E
 %0A   
@@ -2260,24 +2260,354 @@
 st be %3E= 0.%0A
+   *%0A   * @throws TaskFailureException%0A   * %3Cul%3E%0A   *   %3Cli%3E if the task's most recent lock could not be acquired%0A   *   %3Cli%3E if the task has been canceled and therefore does not exist anymore%0A   *   %3Cli%3E if the corresponding process instance could not be resumed%0A   *   %3Cli%3E if the connection could not be established%0A   * %3C/ul%3E%0A
    */%0A  void
@@ -2988,197 +2988,783 @@
    *
-/%0A  void bpmnError(String errorCode);%0A%0A  /**%0A   * Extends the timeout of the lock by a given amount of time.%0A   *%0A   * @param newDuration specifies the the new lock duration in milliseconds
+%0A   * @throws BpmnErrorException%0A   * %3Cul%3E%0A   *   %3Cli%3E if the task's most recent lock could not be acquired%0A   *   %3Cli%3E if the task has been canceled and therefore does not exist anymore%0A   *   %3Cli%3E if the corresponding process instance could not be resumed%0A   *   %3Cli%3E if the connection could not be established%0A   * %3C/ul%3E%0A   */%0A  void bpmnError(String errorCode);%0A%0A  /**%0A   * Extends the timeout of the lock by a given amount of time.%0A   *%0A   * @param newDuration specifies the the new lock duration in milliseconds%0A   *%0A   * @throws ExtendLockException%0A   * %3Cul%3E%0A   *   %3Cli%3E if the task's most recent lock could not be acquired%0A   *   %3Cli%3E if the task has been canceled and therefore does not exist anymore%0A   *   %3Cli%3E if the connection could not be established%0A   * %3C/ul%3E
 %0A   

add javadocs about exceptions