content: /*
   * Copyright 2010-2025 Hyland Software, Inc. and its affiliates.
   *
   * 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.activiti.engine;
  
  import java.sql.Connection;
  import java.util.List;
  import java.util.Map;
  import org.activiti.engine.api.internal.Internal;
  import org.activiti.engine.event.EventLogEntry;
  import org.activiti.engine.impl.cmd.CustomSqlExecution;
  import org.activiti.engine.impl.interceptor.Command;
  import org.activiti.engine.impl.interceptor.CommandConfig;
  import org.activiti.engine.impl.persistence.entity.DeadLetterJobEntity;
  import org.activiti.engine.impl.persistence.entity.SuspendedJobEntity;
  import org.activiti.engine.impl.persistence.entity.TimerJobEntity;
  import org.activiti.engine.management.TableMetaData;
  import org.activiti.engine.management.TablePage;
  import org.activiti.engine.management.TablePageQuery;
  import org.activiti.engine.runtime.DeadLetterJobQuery;
  import org.activiti.engine.runtime.Job;
  import org.activiti.engine.runtime.JobQuery;
  import org.activiti.engine.runtime.SuspendedJobQuery;
  import org.activiti.engine.runtime.TimerJobQuery;
  
  /**
   * Service for admin and maintenance operations on the process engine.
   *
   * These operations will typically not be used in a workflow driven application, but are used in for example the operational console.
   *
   */
  @Internal
  public interface ManagementService {
      /**
       * Get the mapping containing {table name, row count} entries of the Activiti database schema.
       */
      Map<String, Long> getTableCount();
  
      /**
       * Gets the table name (including any configured prefix) for an Activiti entity like Task, Execution or the like.
       */
      String getTableName(Class<?> activitiEntityClass);
  
      /**
       * Gets the metadata (column names, column types, etc.) of a certain table. Returns null when no table exists with the given name.
       */
      TableMetaData getTableMetaData(String tableName);
  
      /**
       * Creates a {@link TablePageQuery} that can be used to fetch {@link TablePage} containing specific sections of table row data.
       */
      TablePageQuery createTablePageQuery();
  
      /**
       * Returns a new JobQuery implementation, that can be used to dynamically query the jobs.
       */
      JobQuery createJobQuery();
  
      /**
       * Returns a new TimerJobQuery implementation, that can be used to dynamically query the timer jobs.
       */
      TimerJobQuery createTimerJobQuery();
  
      /**
       * Returns a new SuspendedJobQuery implementation, that can be used to dynamically query the suspended jobs.
       */
      SuspendedJobQuery createSuspendedJobQuery();
  
      /**
       * Returns a new DeadLetterJobQuery implementation, that can be used to dynamically query the dead letter jobs.
       */
      DeadLetterJobQuery createDeadLetterJobQuery();
  
      /**
       * Forced synchronous execution of a job (eg. for administration or testing) The job will be executed, even if the process definition and/or the process instance is in suspended state.
       *
       * @param jobId
       *          id of the job to execute, cannot be null.
       * @throws ActivitiObjectNotFoundException
       *           when there is no job with the given id.
       */
      void executeJob(String jobId);
  
      /**
       * Moves a timer job to the executable job table (eg. for administration or testing). The timer job will be moved, even if the process definition and/or the process instance is in suspended state.
       *
       * @param jobId
       *          id of the timer job to move, cannot be null.
       * @throws ActivitiObjectNotFoundException
       *           when there is no job with the given id.
       */
      Job moveTimerToExecutableJob(String jobId);
  
      /**
       * Moves a job to the dead letter job table (eg. for administration or testing). The job will be moved, even if the process definition and/or the process instance has retries left.
       *
       * @param jobId
       *          id of the job to move, cannot be null.
       * @throws ActivitiObjectNotFoundException
       *           when there is no job with the given id.
       */
      Job moveJobToDeadLetterJob(String jobId);
  
      /**
       * Moves a job that is in the dead letter job table back to be an executable job,
       * and resetting the retries (as the retries was 0 when it was put into the dead letter job table).
       *
       * @param jobId
       *          id of the job to move, cannot be null.
       * @param retries
       *          the number of retries (value greater than 0) which will be set on the job.
       * @throws ActivitiObjectNotFoundException
       *           when there is no job with the given id.
       */
      Job moveDeadLetterJobToExecutableJob(String jobId, int retries);
  
      /**
       * Delete the job with the provided id.
       *
       * @param jobId
       *          id of the job to delete, cannot be null.
       * @throws ActivitiObjectNotFoundException
       *           when there is no job with the given id.
       */
      void deleteJob(String jobId);
  
      /**
       * Delete the timer job with the provided id.
       *
       * @param jobId
       *          id of the timer job to delete, cannot be null.
       * @throws ActivitiObjectNotFoundException
       *           when there is no job with the given id.
       */
      void deleteTimerJob(String jobId);
  
      /**
       * Delete the dead letter job with the provided id.
       *
       * @param jobId
       *          id of the dead letter job to delete, cannot be null.
       * @throws ActivitiObjectNotFoundException
       *           when there is no job with the given id.
       */
      void deleteDeadLetterJob(String jobId);
  
      /**
       * Sets the number of retries that a job has left.
       *
       * Whenever the JobExecutor fails to execute a job, this value is decremented. When it hits zero, the job is supposed to be dead and not retried again. In that case, this method can be used to
       * increase the number of retries.
       *
       * @param jobId
       *          id of the job to modify, cannot be null.
       * @param retries
       *          number of retries.
       */
      void setJobRetries(String jobId, int retries);
  
      /**
       * Sets the number of retries that a timer job has left.
       *
       * Whenever the JobExecutor fails to execute a timer job, this value is decremented. When it hits zero, the job is supposed to be dead and not retried again. In that case, this method can be used to
       * increase the number of retries.
       *
       * @param jobId
       *          id of the timer job to modify, cannot be null.
       * @param retries
       *          number of retries.
       */
      void setTimerJobRetries(String jobId, int retries);
  
      /**
       * Returns the full stacktrace of the exception that occurs when the job with the given id was last executed.
       * Returns null when the job has no exception stacktrace.
       *
       * @param jobId
       *          id of the job, cannot be null.
       * @throws ActivitiObjectNotFoundException
       *           when no job exists with the given id.
       */
      String getJobExceptionStacktrace(String jobId);
  
      /**
       * Returns the full stacktrace of the exception that occurs when the {@link TimerJobEntity} with the given id was last executed.
       * Returns null when the job has no exception stacktrace.
       *
       * @param jobId
       *          id of the job, cannot be null.
       * @throws ActivitiObjectNotFoundException
       *           when no job exists with the given id.
       */
      String getTimerJobExceptionStacktrace(String jobId);
  
      /**
       * Returns the full stacktrace of the exception that occurs when the {@link SuspendedJobEntity} with the given id was last executed.
       * Returns null when the job has no exception stacktrace.
       *
       * @param jobId
       *          id of the job, cannot be null.
       * @throws ActivitiObjectNotFoundException
       *           when no job exists with the given id.
       */
      String getSuspendedJobExceptionStacktrace(String jobId);
  
      /**
       * Returns the full stacktrace of the exception that occurs when the {@link DeadLetterJobEntity} with the given id was last executed.
       * Returns null when the job has no exception stacktrace.
       *
       * @param jobId
       *          id of the job, cannot be null.
       * @throws ActivitiObjectNotFoundException
       *           when no job exists with the given id.
       */
      String getDeadLetterJobExceptionStacktrace(String jobId);
  
      /** get the list of properties. */
      Map<String, String> getProperties();
  
      /**
       * programmatic schema update on a given connection returning feedback about what happened
       */
      String databaseSchemaUpgrade(Connection connection, String catalog, String schema);
  
      /**
       * Executes a given command with the default {@link CommandConfig}.
       *
       * @param command
       *          the command, cannot be null.
       * @return the result of command execution
       */
      <T> T executeCommand(Command<T> command);
  
      /**
       * Executes a given command with the specified {@link CommandConfig}.
       *
       * @param config
       *          the command execution configuration, cannot be null.
       * @param command
       *          the command, cannot be null.
       * @return the result of command execution
       */
      <T> T executeCommand(CommandConfig config, Command<T> command);
  
      /**
       * Executes the sql contained in the {@link CustomSqlExecution} parameter.
       */
      <MapperType, ResultType> ResultType executeCustomSql(CustomSqlExecution<MapperType, ResultType> customSqlExecution);
  
      /**
       * Returns a list of event log entries, describing everything the engine has processed. Note that the event logging must specifically must be enabled in the process engine configuration.
       *
       * Passing null as arguments will effectively fetch ALL event log entries. Be careful, as this list might be huge!
       */
      List<EventLogEntry> getEventLogEntries(Long startLogNr, Long pageSize);
  
      /**
       * Returns a list of event log entries for a specific process instance id. Note that the event logging must specifically must be enabled in the process engine configuration.
       *
       * Passing null as arguments will effectively fetch ALL event log entries. Be careful, as this list might be huge!
       */
      List<EventLogEntry> getEventLogEntriesByProcessInstanceId(String processInstanceId);
  
      /**
       * Delete a EventLogEntry. Typically only used in testing, as deleting log entries defeats the whole purpose of keeping a log.
       */
      void deleteEventLogEntry(long logNr);
  }
  