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 {@code false}.
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 filter the JavaScriptJobFilter
118 * @return the number of background JavaScript jobs still executing or waiting to be executed when this
119 * method returns; will be <code>0</code> if there are no jobs left to execute
120 */
121 int waitForJobsStartingBefore(long delayMillis, JavaScriptJobFilter filter);
122
123 /**
124 * Shuts down this job manager and stops all of its jobs.
125 */
126 void shutdown();
127
128 /**
129 * Gets the earliest job for this manager.
130 * @return {@code null} if none
131 */
132 JavaScriptJob getEarliestJob();
133
134 /**
135 * Gets the earliest job for this manager.
136 * @param filter the JavaScriptJobFilter
137 * @return {@code null} if none
138 */
139 JavaScriptJob getEarliestJob(JavaScriptJobFilter filter);
140
141 /**
142 * Runs the provided job if it is the right time for it.
143 * @param job the job to run
144 * @return returns true if the job was run.
145 */
146 boolean runSingleJob(JavaScriptJob job);
147
148 /**
149 * <span style="color:red">INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.</span><br>
150 *
151 * Utility method to report the current job status.
152 * Might help some tools.
153 * @param filter the JavaScriptJobFilter
154 * @return the job status report as string
155 */
156 String jobStatusDump(JavaScriptJobFilter filter);
157 }