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}