| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you 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.apache.sling.event.jobs.consumer; |
| |
| import org.osgi.annotation.versioning.ProviderType; |
| |
| /** |
| * |
| * @since 1.1 |
| */ |
| @ProviderType |
| public interface JobExecutionContext { |
| |
| /** |
| * Report an async result. |
| * @param result Tje job execution result |
| * @throws IllegalStateException If the job is not processed asynchronously |
| * or if this method has already been called. |
| */ |
| void asyncProcessingFinished(JobExecutionResult result); |
| |
| /** |
| * If a job is stoppable, it should periodically check this method |
| * and stop processing if the method return <code>true</code>. |
| * If a job is stopped and the job executor detects this, its up |
| * to the implementation to decide the result of such a state. |
| * There might be use cases where the job returns {@link JobExecutionResult#succeeded()} |
| * although it didn't process everything, or {@link JobExecutionResult#failed()} |
| * to retry later on or {@link JobExecutionResult#cancelled()}. |
| * |
| * @return Whether this job has been stopped from the outside. |
| */ |
| boolean isStopped(); |
| |
| /** |
| * Indicate that the job executor is able to report the progress. |
| * The progress can either be reported by a step count, |
| * assuming that all steps take roughly the same amount of time. |
| * Or the progress can be reported by an ETA containing the number |
| * of seconds the job needs to finish. |
| * This method should only be called once, consecutive calls |
| * have no effect. |
| * By using a step count of 100, the progress can be displayed |
| * in percentage. |
| * @param steps Number of total steps or -1 if the number of |
| * steps is unknown. |
| * @param eta Number of seconds the process should take or |
| * -1 of it's not known now. |
| */ |
| void initProgress(int steps, long eta); |
| |
| /** |
| * Update the progress by additionally marking the provided |
| * number of steps as finished. If the total number of finished |
| * steps is equal or higher to the initial number of steps |
| * reported in {@link #initProgress(int, long)}, then the |
| * job progress is assumed to be 100%. |
| * This method has only effect if {@link #initProgress(int, long)} |
| * has been called first with a positive number for steps |
| * @param steps The number of finished steps since the last call. |
| */ |
| void incrementProgressCount(int steps); |
| |
| /** |
| * Update the progress to the new ETA. |
| * This method has only effect if {@link #initProgress(int, long)} |
| * has been called first. |
| * @param eta The new ETA |
| */ |
| void updateProgress(long eta); |
| |
| /** |
| * Log a message. |
| * A job consumer can use this method during job processing to add additional information |
| * about the current state of job processing. |
| * As calling this method adds a significant overhead it should only |
| * be used to log a few statements per job processing. If a consumer wants |
| * to output detailed information about the processing it should persists it |
| * by itself and not use this method for it. |
| * The message and the arguments are passed to the {@link java.text.MessageFormat} |
| * class. |
| * @param message A message |
| * @param args Additional arguments |
| */ |
| void log(String message, Object...args); |
| |
| /** |
| * Build a result for the processing. |
| * @return The build for the result |
| */ |
| ResultBuilder result(); |
| |
| public interface ResultBuilder { |
| |
| /** |
| * Add an optional processing message. |
| * This message can be viewed using {@link org.apache.sling.event.jobs.Job#getResultMessage()}. |
| * @param message The message |
| * @return The builder to continue building the result. |
| */ |
| ResultBuilder message(String message); |
| |
| /** |
| * The job processing finished successfully. |
| * @return The job execution result. |
| */ |
| JobExecutionResult succeeded(); |
| |
| /** |
| * The job processing failed and might be retried. |
| * @return The job execution result. |
| */ |
| JobExecutionResult failed(); |
| |
| /** |
| * The job processing failed and might be retried. |
| * @param retryDelayInMs The new retry delay in ms. |
| * @return The job execution result |
| */ |
| JobExecutionResult failed(long retryDelayInMs); |
| |
| /** |
| * The job processing failed permanently. |
| * @return The job execution result |
| */ |
| JobExecutionResult cancelled(); |
| } |
| } |