001/*
002 * (C) Copyright 2013 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Florent Guillaume
018 */
019package org.nuxeo.ecm.core.work;
020
021import org.nuxeo.ecm.core.work.api.Work;
022import org.nuxeo.ecm.core.work.api.Work.State;
023import org.nuxeo.ecm.core.work.api.WorkManager;
024
025import java.util.List;
026import java.util.Set;
027import java.util.concurrent.BlockingQueue;
028import java.util.concurrent.ThreadPoolExecutor;
029
030/**
031 * Interface describing how the {@link WorkManager} implements queuing.
032 * <p>
033 * There are 4 structures maintained per-queue:
034 * <ul>
035 * <li>the work queue managed by the {@link ThreadPoolExecutor},</li>
036 * <li>the set of scheduled work, this enables to list a work as being scheduled while it has been removed from the
037 * queue by the {@link ThreadPoolExecutor} and not yet executed (not yet running).</li>
038 * <li>the set of running work,</li>
039 * <li>the set of completed work.</li>
040 *
041 * @since 5.8
042 */
043public interface WorkQueuing {
044
045    /**
046     * Starts up this {@link WorkQueuing} and attempts to resume work previously suspended and saved at
047     * shutdown time.
048     */
049    void init();
050
051    /**
052     * Creates a blocking queue of work used by the {@link ThreadPoolExecutor}.
053     *
054     * @since 8.1
055     * @param queueId
056     * @return
057     */
058    BlockingQueue<Runnable> initWorkQueue(String queueId);
059
060    /**
061     * Submit a work to the {@link ThreadPoolExecutor} and put it in the scheduled set.
062     *
063     * @param queueId the queue id
064     * @param work the work instance
065     * @since 8.1
066     */
067    boolean workSchedule(String queueId, Work work);
068
069    /**
070     * Put the work instance into the running set.
071     *
072     * @param queueId the queue id
073     * @param work the work instance
074     * @since 5.8
075     */
076    void workRunning(String queueId, Work work);
077
078    /**
079     * Moves a work instance from the running set to the completed set.
080     *
081     * @param queueId the queue id
082     * @param work the work instance
083     * @since 5.8
084     */
085    void workCompleted(String queueId, Work work);
086
087    /**
088     * Finds a work instance in the scheduled or running or completed sets.
089     *
090     * @param workId the id of the work to find
091     * @param state the state defining the state to look into, {@link State#SCHEDULED SCHEDULED}, {@link State#RUNNING
092     *            RUNNING}, {@link State#COMPLETED COMPLETED}, or {@code null} for SCHEDULED or RUNNING
093     * @return the found work instance, or {@code null} if not found
094     */
095    Work find(String workId, State state);
096
097    /**
098     * Finds a scheduled work instance and removes it from the scheduled queue.
099     *
100     * @param queueId the queue id
101     * @param workId the id of the work to find
102     * @return the work if found, otherwise {@code null}
103     * @since 5.8
104     */
105    Work removeScheduled(String queueId, String workId);
106
107    /**
108     * Checks if a work instance with the given id is in the given state.
109     *
110     * @param workId the work id
111     * @param state the state, {@link State#SCHEDULED SCHEDULED}, {@link State#RUNNING RUNNING}, {@link State#COMPLETED
112     *            COMPLETED}, or {@code null} for non-completed
113     * @return {@code true} if a work instance with the given id is in the given state
114     * @since 5.8
115     */
116    boolean isWorkInState(String workId, State state);
117
118    /**
119     * Gets the state in which a work instance is.
120     * <p>
121     * This can be {@link State#SCHEDULED}, {@link State#RUNNING}, {@link State#COMPLETED}, {@link State#FAILED}, or
122     * {@link State#CANCELED}.
123     *
124     * @param workId the id of the work to find
125     * @return the work state, or {@code null} if not found
126     * @since 5.8
127     */
128    State getWorkState(String workId);
129
130    /**
131     * Lists the work instances in a given queue in a defined state.
132     * <p>
133     * Note that an instance requested as RUNNING could be found SUSPENDING or SUSPENDED, and an instance requested as
134     * COMPLETED could be found FAILED.
135     *
136     * @param queueId the queue id
137     * @param state the state defining the state to look into, {@link State#SCHEDULED SCHEDULED}, {@link State#RUNNING
138     *            RUNNING}, {@link State#COMPLETED COMPLETED}, or {@code null} for non-completed
139     * @return the list of work instances in the given state
140     */
141    List<Work> listWork(String queueId, State state);
142
143    /**
144     * Lists the work ids in a given queue in a defined state.
145     *
146     * @param queueId the queue id
147     * @param state the state defining the state to look into, {@link State#SCHEDULED SCHEDULED}, {@link State#RUNNING
148     *            RUNNING}, {@link State#COMPLETED COMPLETED}, or {@code null} for non-completed
149     * @return the list of work ids in the given state
150     */
151    List<String> listWorkIds(String queueId, State state);
152
153    /**
154     * Gets the number of work instances in the given state in a given queue.
155     *
156     * @param queueId the queue id
157     * @param state the state, {@link State#SCHEDULED SCHEDULED}, {@link State#RUNNING RUNNING} or
158     *            {@link State#COMPLETED COMPLETED}
159     * @return the number of scheduled work instances in the queue
160     * @since 5.8
161     */
162    int count(String queueId, State state);
163
164    /**
165     * Notifies this queuing that all work should be suspending.
166     *
167     * @return the number of scheduled instances removed from queue
168     */
169    int setSuspending(String queueId);
170
171    /**
172     * Finds which queues have completed work.
173     *
174     * @return a set of queue ids
175     * @since 5.8
176     */
177    Set<String> getCompletedQueueIds();
178
179    /**
180     * Clears the list of completed work instances older than the given time in the given queue.
181     *
182     * @param queueId the queue id
183     * @param completionTime the completion time (milliseconds since epoch) before which completed work instances are
184     *            cleared, or {@code 0} for all
185     */
186    void clearCompletedWork(String queueId, long completionTime);
187
188}