1 /* 2 * Copyright (c) 2002-2025 Gargoyle Software Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * https://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 package org.htmlunit.javascript.background; 16 17 import java.io.Serializable; 18 19 import org.htmlunit.Page; 20 21 /** 22 * A manager for {@link JavaScriptJob}s. 23 * 24 * @author Daniel Gredler 25 * @author Ronald Brill 26 */ 27 public interface JavaScriptJobManager extends Serializable { 28 29 /** 30 * Simple filter interface. The caller can use this to filter 31 * the jobs of interest in the job list. 32 */ 33 interface JavaScriptJobFilter { 34 35 /** 36 * Check if the job passes the filter. 37 * @param job the job to check 38 * @return true if the job passes the filter 39 */ 40 boolean passes(JavaScriptJob job); 41 } 42 43 /** 44 * Returns the number of active jobs, including jobs that are currently executing and jobs that are 45 * waiting to execute. 46 * @return the number of active jobs 47 */ 48 int getJobCount(); 49 50 /** 51 * Returns the number of active jobs, including jobs that are currently executing and jobs that are 52 * waiting to execute. Only jobs passing the filter are counted. 53 * @param filter the JavaScriptJobFilter 54 * @return the number of active jobs 55 */ 56 int getJobCount(JavaScriptJobFilter filter); 57 58 /** 59 * Adds the specified job to this job manager, assigning it an ID. If the specified page is not currently 60 * loaded in the window which owns this job manager, the operation fails and this method returns <code>0</code>. 61 * @param job the job to add to the job manager 62 * @param page the page which is trying to add the job 63 * @return the ID assigned to the job 64 */ 65 int addJob(JavaScriptJob job, Page page); 66 67 /** 68 * Removes the specified job from the execution queue. This doesn't interrupt the job if it is currently running. 69 * @param id the ID of the job to be removed from the execution queue 70 */ 71 void removeJob(int id); 72 73 /** 74 * Removes all jobs from the execution queue. This doesn't interrupt any jobs that may be currently running. 75 */ 76 void removeAllJobs(); 77 78 /** 79 * Stops the specified job and removes it from the execution queue, not even allowing the job to finish if it is 80 * currently executing. 81 * @param id the ID of the job to be stopped 82 */ 83 void stopJob(int id); 84 85 /** 86 * Blocks until all active jobs have finished executing. If a job is scheduled to begin executing after 87 * <code>(now + timeoutMillis)</code>, this method will wait for <code>timeoutMillis</code> milliseconds and then 88 * return the number of background JavaScript jobs still executing. 89 * @param timeoutMillis the maximum amount of time to wait (in milliseconds); may be negative, in which 90 * case this method returns immediately 91 * @return the number of background JavaScript jobs still executing or waiting to be executed when this 92 * method returns; will be <code>0</code> if there are no jobs left to execute 93 */ 94 int waitForJobs(long timeoutMillis); 95 96 /** 97 * Blocks until all jobs scheduled to start executing before 98 * <code>(now + delayMillis)</code> have finished executing. 99 * If there is no background JavaScript task currently executing, and there is no background JavaScript task 100 * scheduled to start executing within the specified time, this method returns immediately -- even if there are 101 * tasks scheduled to be executed after <code>(now + delayMillis)</code>. 102 * @param delayMillis the delay which determines the background tasks to wait for (in milliseconds); 103 * may be negative, as it is relative to the current time 104 * @return the number of background JavaScript jobs still executing or waiting to be executed when this 105 * method returns; will be <code>0</code> if there are no jobs left to execute 106 */ 107 int waitForJobsStartingBefore(long delayMillis); 108 109 /** 110 * Blocks until all jobs scheduled to start executing before 111 * <code>(now + delayMillis)</code> have finished executing. 112 * If there is no background JavaScript task currently executing, and there is no background JavaScript task 113 * scheduled to start executing within the specified time, this method returns immediately -- even if there are 114 * tasks scheduled to be executed after <code>(now + delayMillis)</code>. 115 * @param delayMillis the delay which determines the background tasks to wait for (in milliseconds); 116 * may be negative, as it is relative to the current time 117 * @param timeoutMillis the maximum amount of time to wait (in milliseconds); this has to be larger than 118 * the delayMillis parameter, otherwise the timeout is ignored 119 * @return the number of background JavaScript jobs still executing or waiting to be executed when this 120 * method returns; will be <code>0</code> if there are no jobs left to execute 121 */ 122 int waitForJobsStartingBefore(long delayMillis, long timeoutMillis); 123 124 /** 125 * Blocks until all jobs scheduled to start executing before 126 * <code>(now + delayMillis)</code> have finished executing. 127 * If there is no background JavaScript task currently executing, and there is no background JavaScript task 128 * scheduled to start executing within the specified time, this method returns immediately -- even if there are 129 * tasks scheduled to be executed after <code>(now + delayMillis)</code>. 130 * @param delayMillis the delay which determines the background tasks to wait for (in milliseconds); 131 * may be negative, as it is relative to the current time 132 * @param filter the JavaScriptJobFilter 133 * @return the number of background JavaScript jobs still executing or waiting to be executed when this 134 * method returns; will be <code>0</code> if there are no jobs left to execute 135 */ 136 int waitForJobsStartingBefore(long delayMillis, JavaScriptJobFilter filter); 137 138 /** 139 * Blocks until all jobs scheduled to start executing before <code>(now + delayMillis)</code> 140 * have finished executing or the 141 * If there is no background JavaScript task currently executing, and there is no background JavaScript task 142 * scheduled to start executing within the specified time, this method returns immediately -- even if there are 143 * tasks scheduled to be executed after <code>(now + delayMillis)</code>. 144 * @param delayMillis the delay which determines the background tasks to wait for (in milliseconds); 145 * may be negative, as it is relative to the current time 146 * @param timeoutMillis the maximum amount of time to wait (in milliseconds); this has to be larger than 147 * the delayMillis parameter, otherwise the timeout is ignored 148 * @param filter the JavaScriptJobFilter 149 * @return the number of background JavaScript jobs still executing or waiting to be executed when this 150 * method returns; will be <code>0</code> if there are no jobs left to execute 151 */ 152 int waitForJobsStartingBefore(long delayMillis, long timeoutMillis, JavaScriptJobFilter filter); 153 154 /** 155 * Shuts down this job manager and stops all of its jobs. 156 */ 157 void shutdown(); 158 159 /** 160 * Gets the earliest job for this manager. 161 * @return {@code null} if none 162 */ 163 JavaScriptJob getEarliestJob(); 164 165 /** 166 * Gets the earliest job for this manager. 167 * @param filter the JavaScriptJobFilter 168 * @return {@code null} if none 169 */ 170 JavaScriptJob getEarliestJob(JavaScriptJobFilter filter); 171 172 /** 173 * Runs the provided job if it is the right time for it. 174 * @param job the job to run 175 * @return returns true if the job was run. 176 */ 177 boolean runSingleJob(JavaScriptJob job); 178 179 /** 180 * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br> 181 * 182 * Utility method to report the current job status. 183 * Might help some tools. 184 * @param filter the JavaScriptJobFilter 185 * @return the job status report as string 186 */ 187 String jobStatusDump(JavaScriptJobFilter filter); 188 }