work/workmanager/src/main/java/androidx/work/SynchronousWorkManager.java

/*
 * Copyright 2018 The Android Open Source Project
 *
 * 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 androidx.work;

import android.support.annotation.NonNull;
import android.support.annotation.WorkerThread;

import java.util.List;
import java.util.UUID;

/**
 * Blocking methods for {@link WorkManager} operations.  These methods are expected to be called
 * from a background thread.
 */
public interface SynchronousWorkManager {

    /**
     * Enqueues one or more {@link WorkRequest} in a synchronous fashion. This method is expected to
     * be called from a background thread and, upon successful execution, you can rely on that the
     * work has been enqueued.
     *
     * @param workRequest The Array of {@link WorkRequest}
     */
    @WorkerThread
    void enqueueSync(@NonNull WorkRequest... workRequest);

    /**
     * Enqueues the List of {@link WorkRequest} in a synchronous fashion. This method is expected to
     * be called from a background thread and, upon successful execution, you can rely on that the
     * work has been enqueued.
     *
     * @param workRequest The List of {@link WorkRequest}
     */
    @WorkerThread
    void enqueueSync(@NonNull List<? extends WorkRequest> workRequest);

    /**
     * This method allows you to synchronously enqueue a uniquely-named {@link PeriodicWorkRequest},
     * where only one PeriodicWorkRequest of a particular name can be active at a time.  For
     * example, you may only want one sync operation to be active.  If there is one pending, you can
     * choose to let it run or replace it with your new work.
     *
     * This method is expected to be called from a background thread.
     *
     * The {@code uniqueWorkName} uniquely identifies this PeriodicWorkRequest.
     *
     * @param uniqueWorkName A unique name which for this operation
     * @param existingPeriodicWorkPolicy An {@link ExistingPeriodicWorkPolicy}
     * @param periodicWork A {@link PeriodicWorkRequest} to enqueue. {@code REPLACE} ensures that if
     *                     there is pending work labelled with {@code uniqueWorkName}, it will be
     *                     cancelled and the new work will run. {@code KEEP} will run the new
     *                     PeriodicWorkRequest only if there is no pending work labelled with
     *                     {@code uniqueWorkName}.
     */
    @WorkerThread
    void enqueueUniquePeriodicWorkSync(
            @NonNull String uniqueWorkName,
            @NonNull ExistingPeriodicWorkPolicy existingPeriodicWorkPolicy,
            @NonNull PeriodicWorkRequest periodicWork);

    /**
     * Cancels work with the given id in a synchronous fashion if it isn't finished.  Note that
     * cancellation is dependent on timing (for example, the work could have completed in a
     * different thread just as you issue this call).  Use {@link #getStatusByIdSync(UUID)} to
     * find out the actual state of the work after this call.  This method is expected to be called
     * from a background thread.
     *
     * @param id The id of the work
     */
    @WorkerThread
    void cancelWorkByIdSync(@NonNull UUID id);

    /**
     * Cancels all unfinished work with the given tag in a synchronous fashion.  Note that
     * cancellation is dependent on timing (for example, the work could have completed in a
     * different thread just as you issue this call).  Use {@link #getStatusByIdSync(UUID)} to
     * find out the actual state of the work after this call.  This method is expected to be called
     * from a background thread.
     *
     * @param tag The tag used to identify the work
     */
    @WorkerThread
    void cancelAllWorkByTagSync(@NonNull String tag);

    /**
     * Cancels all unfinished work in the work chain with the given name in a synchronous fashion.
     * Note that cancellation is dependent on timing (for example, the work could have completed in
     * a different thread just as you issue this call).  Use {@link #getStatusByIdSync(UUID)} to
     * find out the actual state of the work after this call.  This method is expected to be called
     * from a background thread.
     *
     * @param uniqueWorkName The unique name used to identify the chain of work
     */
    @WorkerThread
    void cancelUniqueWorkSync(@NonNull String uniqueWorkName);

    /**
     * Cancels all unfinished work in a synchronous fashion.  <b>Use this method with extreme
     * caution!</b>  By invoking it, you will potentially affect other modules or libraries in your
     * codebase.  It is strongly recommended that you use one of the other cancellation methods at
     * your disposal.
     */
    @WorkerThread
    void cancelAllWorkSync();

    /**
     * Gets the timestamp of the last time all work was cancelled in a synchronous fashion.  This
     * method is intended for use by library and module developers who have dependent data in their
     * own repository that must be updated or deleted in case someone cancels their work without
     * their prior knowledge.
     *
     * @return The timestamp in milliseconds when a method that cancelled all work was last invoked
     */
    @WorkerThread
    long getLastCancelAllTimeMillisSync();

    /**
     * Gets the {@link WorkStatus} of a given work id in a synchronous fashion.  This method is
     * expected to be called from a background thread.
     *
     * @param id The id of the work
     * @return A {@link WorkStatus} associated with {@code id}
     */
    @WorkerThread
    WorkStatus getStatusByIdSync(@NonNull UUID id);

    /**
     * Gets the {@link WorkStatus} for all work with a given tag in a synchronous fashion.  This
     * method is expected to be called from a background thread.
     *
     * @param tag The tag of the work
     * @return A list of {@link WorkStatus} for work tagged with {@code tag}
     */
    @WorkerThread
    List<WorkStatus> getStatusesByTagSync(@NonNull String tag);

    /**
     * Gets the {@link WorkStatus} for all work for the chain of work with a given unique name in a
     * synchronous fashion.  This method is expected to be called from a background thread.
     *
     * @param uniqueWorkName The unique name used to identify the chain of work
     * @return A list of {@link WorkStatus} for work in the chain named {@code uniqueWorkName}
     */
    @WorkerThread
    List<WorkStatus> getStatusesForUniqueWorkSync(@NonNull String uniqueWorkName);
}