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}