Spec-Zone .ru
спецификации, руководства, описания, API
|
001/* 002 * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved. 003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 004 * 005 * This code is free software; you can redistribute it and/or modify it 006 * under the terms of the GNU General Public License version 2 only, as 007 * published by the Free Software Foundation. Oracle designates this 008 * particular file as subject to the "Classpath" exception as provided 009 * by Oracle in the LICENSE file that accompanied this code. 010 * 011 * This code is distributed in the hope that it will be useful, but WITHOUT 012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 014 * version 2 for more details (a copy is included in the LICENSE file that 015 * accompanied this code). 016 * 017 * You should have received a copy of the GNU General Public License version 018 * 2 along with this work; if not, write to the Free Software Foundation, 019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 020 * 021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 022 * or visit www.oracle.com if you need additional information or have any 023 * questions. 024 */ 025 026package javafx.concurrent; 027 028import javafx.beans.property.ReadOnlyBooleanProperty; 029import javafx.beans.property.ReadOnlyDoubleProperty; 030import javafx.beans.property.ReadOnlyObjectProperty; 031import javafx.beans.property.ReadOnlyStringProperty; 032 033/** 034 * <p> 035 * A Worker is an object which performs some work in one or more background 036 * threads, and who's state is observable and available to JavaFX applications 037 * and is usable from the main JavaFX Application thread. This interface is 038 * primarily implemented by both {@link Task} and {@link Service}, providing 039 * a common API among both classes which makes it easier for libraries and 040 * frameworks to provide workers which work well when developing user interfaces. 041 * </p> 042 * <p> 043 * A Worker may or may not be reusable depending on the implementation. A 044 * {@link Task}, for example, is not reusable while a {@link Service} is. 045 * </p> 046 * <p> 047 * A Worker has a well defined life cycle. Every Worker begins in the 048 * {@link State#READY} state. When the Worker has been scheduled for work 049 * (for example, when a Service's {@link javafx.concurrent.Service#start()} 050 * method is called), it is transitioned to {@link State#SCHEDULED}. Even 051 * Workers which are not technically scheduled, but started immediately 052 * (such as with {@link javafx.concurrent.Task#run()}) will transition through 053 * the {@link State#SCHEDULED} on its way to the {@link State#RUNNING} state. 054 * </p> 055 * <p> 056 * When the Worker is actually performing its work, the state will have been 057 * transitioned to {@link State#RUNNING}. If the Worker completes normally, 058 * it will end in the {@link State#SUCCEEDED} state, and the result of the 059 * Worker will be set as the <code>value</code> property. If however an Exception 060 * occurs during the execution of the Worker, then the state will be set to 061 * {@link State#FAILED} and the <code>exception</code> property will be set 062 * to the Exception which occurred. 063 * </p> 064 * <p> 065 * At any time prior to the conclusion of the Worker (that is, if the state 066 * is not already {@link State#SUCCEEDED} or {@link State#FAILED}) the developer 067 * may invoke the {@link javafx.concurrent.Worker#cancel()} method. If called, the 068 * Worker will cease execution (if possible, including use of Thread.interrupt) 069 * and the state changed to {@link State#CANCELLED}. 070 * </p> 071 * <p> 072 * The only valid beginning state for a Worker is {@link State#READY}, and the 073 * valid ending states are {@link State#CANCELLED}, {@link State#SUCCEEDED}, 074 * and {@link State#FAILED}. The <code>running</code> property is set to 075 * true when the state is either {@link State#SCHEDULED} or {@link State#RUNNING}. 076 * </p> 077 * <p> 078 * The Worker's progress can be monitored via three different properties, 079 * <code>totalWork</code>, <code>workDone</code>, and <code>progress</code>. 080 * These properties are set by the actual implementation of the Worker 081 * interface, but can be observed by anybody. The <code>workDone</code> is 082 * a number between -1 (meaning indeterminate progress) and 083 * <code>totalWork</code>, inclusive. When <code>workDone == totalWork</code> 084 * the <code>progress</code> will be 100% (or 1). <code>totalWork</code> 085 * will be a number between -1 and Long.MAX_VALUE, inclusive. The progress 086 * will be either -1 (meaning indeterminate), or a value between 0 and 1, inclusive, 087 * representing 0% through 100%. 088 * </p> 089 * <p> 090 * A Worker which is in the {@link State#READY} or {@link State#SCHEDULED} states 091 * will always have <code>workDone</code> and <code>progress</code> set to -1. 092 * A Worker which is in the {@link State#SUCCEEDED} state will always have 093 * <code>workDone == totalWork</code> and <code>progress == 1</code>. In any 094 * other state, the values for these properties may be any value in their 095 * respective valid ranges. 096 * </p> 097 */ 098public interface Worker<V> { 099 /** 100 * <p> 101 * The state of a Worker. The state transitions in a Worker are very well defined. 102 * All Workers begin in the READY state. In some circumstances, a Worker might 103 * be scheduled for execution before it is actually executed. In such cases, 104 * it is sometimes useful to know when the Worker has been SCHEDULED separately 105 * from when it is RUNNING. However even in cases where the Worker is executed 106 * immediately, the Worker will temporarily enter the SCHEDULED state before 107 * entering the RUNNING state. That is, the transition is always from 108 * READY to SCHEDULED to RUNNING (unless of course the Worker in cancelled). 109 * </p> 110 * <p> 111 * A Worker which runs but is never cancelled can only end up in one of two 112 * states, either SUCCEEDED or FAILED. It only enters FAILED if an exception 113 * was thrown during the execution of the Worker. A Worker may be cancelled when 114 * READY, SCHEDULED, or RUNNING, in which case the final status will be CANCELLED. 115 * When a Worker is cancelled in one of these circumstances it will transition 116 * immediately to the CANCELLED state. 117 * </p> 118 * <p> 119 * A reusable Worker will transition from CANCELLED, SUCCEEDED or FAILED back to 120 * READY. From that point the normal state transitions are again followed. 121 * </p> 122 */ 123 public enum State { 124 /** 125 * Indicates that the Worker has not yet been executed and is ready 126 * to be executed, or that it has been reinitialized. This is the 127 * default initial state of the Worker. 128 */ 129 READY, 130 /** 131 * Indicates that the Worker has been scheduled for execution, but 132 * that it is not currently running. This might be because the 133 * Worker is waiting for a thread in a thread pool to become 134 * available before it can start running. 135 */ 136 SCHEDULED, 137 /** 138 * Indicates that this Worker is running. This is set just immediately 139 * prior to the Worker actually doing its first bit of work. 140 */ 141 RUNNING, 142 /** 143 * Indicates that this Worker has completed successfully, and that there 144 * is a valid result ready to be read from the <code>value</code> property. 145 */ 146 SUCCEEDED, 147 /** 148 * Indicates that this Worker has been cancelled via the {@link #cancel()} 149 * method. 150 */ 151 CANCELLED, 152 /** 153 * Indicates that this Worker has failed, usually due to some unexpected 154 * condition having occurred. The exception can be retrieved from the 155 * <code>exception</code> property. 156 */ 157 FAILED 158 } 159 160 /** 161 * Specifies the current state of this Worker. The initial value is State.READY. 162 * A Task may be restarted, in which case it will progress from one of these 163 * end states (SUCCEEDED, CANCELLED, or FAILED) back to READY and then 164 * immediately to SCHEDULED and RUNNING. These state transitions may occur 165 * immediately one after the other, but will always occur in the prescribed order. 166 * 167 * @return The current state of this Worker 168 */ 169 public State getState(); 170 171 /** 172 * Gets the ReadOnlyObjectProperty representing the current state. 173 * 174 * @return The property representing the state 175 */ 176 public ReadOnlyObjectProperty<State> stateProperty(); 177 178 /** 179 * Specifies the value, or result, of this Worker. This is set upon entering 180 * the SUCCEEDED state, and cleared (set to null) if the Worker is reinitialized 181 * (that is, if the Worker is a reusable Worker and is reset or restarted). 182 * 183 * @return the current value of this Worker 184 */ 185 public V getValue(); 186 187 /** 188 * Gets the ReadOnlyObjectProperty representing the value. 189 * 190 * @return The property representing the current value 191 */ 192 public ReadOnlyObjectProperty<V> valueProperty(); 193 194 /** 195 * Indicates the exception which occurred while the Worker was running, if any. 196 * If this property value is {@code null}, there is no known exception, even if 197 * the status is FAILED. If this property is not {@code null}, it will most 198 * likely contain an exception that describes the cause of failure. 199 * 200 * @return the exception, if one occurred 201 */ 202 public Throwable getException(); 203 204 /** 205 * Gets the ReadOnlyObjectProperty representing any exception which occurred. 206 * 207 * @return the property representing the exception 208 */ 209 public ReadOnlyObjectProperty<Throwable> exceptionProperty(); 210 211 /** 212 * Indicates the current amount of work that has been completed. Zero or a 213 * positive value indicate progress toward completion. This variables value 214 * may or may not change from its default value depending on the specific 215 * Worker implementation. A value of -1 means that the current amount of work 216 * done cannot be determined (ie: it is indeterminate). The value of 217 * this property is always less than or equal to totalWork. 218 * 219 * @see #totalWorkProperty 220 * @see #progressProperty 221 * @return the amount of work done 222 */ 223 public double getWorkDone(); 224 225 /** 226 * Gets the ReadOnlyDoubleProperty representing the current progress. 227 * 228 * @return The property representing the amount of work done 229 */ 230 public ReadOnlyDoubleProperty workDoneProperty(); 231 232 /** 233 * Indicates a maximum value for the {@link #workDoneProperty} property. The 234 * totalWork will either be -1 (indicating that the amount of work 235 * to do is indeterminate), or it will be a non-zero value less than or 236 * equal to Double.MAX_VALUE. 237 * 238 * @see #workDoneProperty 239 * @see #progressProperty 240 * @return the total work to be done 241 */ 242 public double getTotalWork(); 243 244 /** 245 * Gets the ReadOnlyDoubleProperty representing the maximum amount of work 246 * that needs to be done. These "work units" have meaning to the Worker 247 * implementation, such as the number of bytes that need to be downloaded 248 * or the number of images to process or some other such metric. 249 * 250 * @return the property representing the total work to be done 251 */ 252 public ReadOnlyDoubleProperty totalWorkProperty(); 253 254 /** 255 * Indicates the current progress of this Worker in terms of percent complete. 256 * A value between zero and one indicates progress toward completion. A value 257 * of -1 means that the current progress cannot be determined (that is, it is 258 * indeterminate). This property may or may not change from its default value 259 * of -1 depending on the specific Worker implementation. 260 * 261 * @see #workDoneProperty 262 * @see #totalWorkProperty 263 * @return the current progress 264 */ 265 public double getProgress(); 266 267 /** 268 * Gets the ReadOnlyDoubleProperty representing the progress. 269 * 270 * @return the property representing the progress 271 */ 272 public ReadOnlyDoubleProperty progressProperty(); 273 274 /** 275 * True if the state is either SCHEDULED or RUNNING. When binding a Worker to a 276 * {@link javafx.scene.control.ProgressIndicator}, you will typically bind the visibility 277 * of the ProgressIndicator to the Worker's running property, and the progress of the 278 * ProgressIndicator to the Worker's progress property. 279 * 280 * @return true if this Worker is running 281 */ 282 public boolean isRunning(); 283 284 /** 285 * Gets the ReadOnlyBooleanProperty representing whether the Worker is running. 286 * 287 * @return the property representing whether the worker is running 288 */ 289 public ReadOnlyBooleanProperty runningProperty(); 290 291 /** 292 * Gets a message associated with the current state of this Worker. This may 293 * be something such as "Processing image 1 of 3", for example. 294 * 295 * @return the current message 296 */ 297 public String getMessage(); 298 299 /** 300 * Gets the ReadOnlyStringProperty representing the message. 301 * 302 * @return a property representing the current message 303 */ 304 public ReadOnlyStringProperty messageProperty(); 305 306 /** 307 * An optional title that should be associated with this Worker. 308 * This may be something such as "Modifying Images". 309 * 310 * @return the current title 311 */ 312 public String getTitle(); 313 314 /** 315 * Gets the ReadOnlyStringProperty representing the title. 316 * 317 * @return the property representing the current title 318 */ 319 public ReadOnlyStringProperty titleProperty(); 320 321 /** 322 * Terminates execution of this Worker. Calling this method will either 323 * remove this Worker from the execution queue or stop execution. 324 * 325 * @return returns true if the cancel was successful 326 */ 327 public boolean cancel(); 328}