001/*
002 * (C) Copyright 2013 Nuxeo SA (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl-2.1.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Florent Guillaume
016 */
017package org.nuxeo.ecm.core.work;
018
019import java.util.List;
020import java.util.Set;
021import java.util.concurrent.BlockingQueue;
022import java.util.concurrent.ThreadPoolExecutor;
023import org.nuxeo.ecm.core.work.api.Work;
024import org.nuxeo.ecm.core.work.api.Work.State;
025import org.nuxeo.ecm.core.work.api.WorkManager;
026
027/**
028 * Interface describing how the {@link WorkManager} implements queuing.
029 * <p>
030 * There are 3 structures maintained per-queue:
031 * <ul>
032 * <li>the queue of scheduled work,</li>
033 * <li>the set of running work,</li>
034 * <li>the set of completed work.</li>
035 *
036 * @since 5.8
037 */
038public interface WorkQueuing {
039
040    /**
041     * Starts up this {@link WorkQueuing} and attempts to resume work previously suspended and saved at
042     * {@link #shutdown} time.
043     */
044    void init();
045
046    /**
047     * @since 6.0
048     * @param queueId
049     * @return
050     */
051    BlockingQueue<Runnable> initScheduleQueue(String queueId);
052
053    /**
054     * Gets the blocking queue for scheduled work, to be used in a {@link ThreadPoolExecutor}.
055     *
056     * @param queueId the queue id
057     * @return the queue
058     * @since 5.8
059     */
060    BlockingQueue<Runnable> getScheduledQueue(String queueId);
061
062    /**
063     * Moves a work instance from the scheduled queue to the running set. When called, the work instance is already
064     * removed from the scheduled queue.
065     *
066     * @param queueId the queue id
067     * @param work the work instance
068     * @since 5.8
069     */
070    void workRunning(String queueId, Work work);
071
072    /**
073     * Moves a work instance from the running set to the completed set.
074     *
075     * @param queueId the queue id
076     * @param work the work instance
077     * @since 5.8
078     */
079    void workCompleted(String queueId, Work work);
080
081    /**
082     * Finds a work instance in the scheduled queue or running or completed sets.
083     *
084     * @param workId the id of the work to find
085     * @param state the state defining the state to look into, {@link State#SCHEDULED SCHEDULED}, {@link State#RUNNING
086     *            RUNNING}, {@link State#COMPLETED COMPLETED}, or {@code null} for SCHEDULED or RUNNING
087     * @return the found work instance, or {@code null} if not found
088     */
089    Work find(String workId, State state);
090
091    /**
092     * Finds a scheduled work instance and removes it from the scheduled work.
093     *
094     * @param queueId the queue id
095     * @param workId the id of the work to find
096     * @return the work if found, otherwise {@code null}
097     * @since 5.8
098     */
099    Work removeScheduled(String queueId, String workId);
100
101    /**
102     * Checks if a work instance with the given id is in the given state.
103     *
104     * @param workId the work id
105     * @param state the state, {@link State#SCHEDULED SCHEDULED}, {@link State#RUNNING RUNNING}, {@link State#COMPLETED
106     *            COMPLETED}, or {@code null} for non-completed
107     * @return {@code true} if a work instance with the given id is in the given state
108     * @since 5.8
109     */
110    boolean isWorkInState(String workId, State state);
111
112    /**
113     * Gets the state in which a work instance is.
114     * <p>
115     * This can be {@link State#SCHEDULED}, {@link State#RUNNING}, {@link State#COMPLETED}, {@link State#FAILED}, or
116     * {@link State#CANCELED}.
117     *
118     * @param workId the id of the work to find
119     * @return the work state, or {@code null} if not found
120     * @since 5.8
121     */
122    State getWorkState(String workId);
123
124    /**
125     * Lists the work instances in a given queue in a defined state.
126     * <p>
127     * Note that an instance requested as RUNNING could be found SUSPENDING or SUSPENDED, and an instance requested as
128     * COMPLETED could be found FAILED.
129     *
130     * @param queueId the queue id
131     * @param state the state defining the state to look into, {@link State#SCHEDULED SCHEDULED}, {@link State#RUNNING
132     *            RUNNING}, {@link State#COMPLETED COMPLETED}, or {@code null} for non-completed
133     * @return the list of work instances in the given state
134     */
135    List<Work> listWork(String queueId, State state);
136
137    /**
138     * Lists the work ids in a given queue in a defined state.
139     *
140     * @param queueId the queue id
141     * @param state the state defining the state to look into, {@link State#SCHEDULED SCHEDULED}, {@link State#RUNNING
142     *            RUNNING}, {@link State#COMPLETED COMPLETED}, or {@code null} for non-completed
143     * @return the list of work ids in the given state
144     */
145    List<String> listWorkIds(String queueId, State state);
146
147    /**
148     * Gets the number of work instances in the given state in a given queue.
149     *
150     * @param queueId the queue id
151     * @param state the state, {@link State#SCHEDULED SCHEDULED}, {@link State#RUNNING RUNNING} or
152     *            {@link State#COMPLETED COMPLETED}
153     * @return the number of scheduled work instances in the queue
154     * @since 5.8
155     */
156    int getQueueSize(String queueId, State state);
157
158    /**
159     * Notifies this queuing that all work should be suspending.
160     *
161     * @return the number of scheduled instances removed from queue
162     */
163    int setSuspending(String queueId);
164
165    /**
166     * Finds which queues have completed work.
167     *
168     * @return a set of queue ids
169     * @since 5.8
170     */
171    Set<String> getCompletedQueueIds();
172
173    /**
174     * Clears the list of completed work instances older than the given time in the given queue.
175     *
176     * @param queueId the queue id
177     * @param completionTime the completion time (milliseconds since epoch) before which completed work instances are
178     *            cleared, or {@code 0} for all
179     */
180    void clearCompletedWork(String queueId, long completionTime);
181
182}