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 }