1 /* 2 * Copyright the original author or authors. 3 * 4 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (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 * 8 * http://www.mozilla.org/MPL/MPL-1.1.html 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 import org.as2lib.env.event.EventListenerSource; 18 import org.as2lib.data.type.Time; 19 20 /** 21 * {@code Process} represents the access to a lacy execution. 22 * 23 * <p>{@code Process} can be used as access to application code that executes with 24 * a time delay. This can be eighter file requests or time consuming algorithms 25 * that have to be delayed to prevent player timeouts. 26 * 27 * <p>Any {@code Process} implementation can be started with {@link #start}. 28 * 29 * <p>Any {@code Process} can send events defined in following interfaces: 30 * {@link ProcessStartListener}, {@link ProcessErrorListener}, 31 * {@link ProcessFinishListener}, {@link ProcessPauseListener}, 32 * {@link ProcessResumeListener}, {@link ProcessUpdateListener} 33 * 34 * <p>To listen to the events implement one or more of the above interfaces and 35 * add the listener with {@code addListener} as listener to the {@code Process}. 36 * 37 * @author Martin Heidegger 38 * @version 1.0 39 * @see org.as2lib.app.exec.AbstractProcess 40 */ 41 interface org.as2lib.app.exec.Process extends EventListenerSource { 42 43 /** 44 * Starts the execution of this process. 45 * 46 * <p>It is possible that the process finishes execution before returning the 47 * from this method, but it is also possible that it finishes after returning 48 * from this method. This rule exists to not loose unnecessary performance by 49 * simple accepting that every process has to be finished after this execution. 50 * 51 * <p>Problematic example: 52 * <code> 53 * 54 * class MyClass implements ProcessFinishListener { 55 * private var processStarted:Boolean 56 * 57 * public function MyClass(Void) { 58 * processStarted = false; 59 * } 60 * 61 * public function doSomething(Void):Void { 62 * var process:Process = new MyProcess(); 63 * process.start(); 64 * process.addListener(this); 65 * processStarted = true; 66 * } 67 * 68 * public function onFinishProcess(process:Process):Void { 69 * if (processStarted) { 70 * // do something 71 * processStarted = false; 72 * } else { 73 * // throw an error (will be called if the process finishes immediatly. 74 * } 75 * } 76 * } 77 * </code> 78 * 79 * <p>Any {@code Process} is allowed to take arguments for its execution or 80 * return a result of its execution. 81 * 82 * @return (optiona) result for the start (implementation specific). 83 */ 84 public function start(); 85 86 /** 87 * Flag if the process has been started. 88 * 89 * @return true if the process has been started and isn't finish yet else false. 90 */ 91 public function hasStarted(Void):Boolean; 92 93 /** 94 * Returns {@code true} if the process has been finished else {@code false}. 95 * 96 * <p>A {@code Process} can only be finished if it has been started with 97 * {@code start()} 98 * 99 * @return {@code true} if the process has been finished else {@code false} 100 */ 101 public function hasFinished(Void):Boolean; 102 103 /** 104 * Returns {@code true} if the process has been started and has been paused. 105 * 106 * <p>A {@code Process} is allowed to be paused, this indicates that the process 107 * is actually waiting for something. 108 * 109 * @return {@code true} if the process has been started and has been paused 110 */ 111 public function isPaused(Void):Boolean; 112 113 /** 114 * Returns {@code true} if the process has been started and is not paused. 115 * 116 * <p>A {@code Process} is allowed to be paused, this indicates that the process 117 * is actually not waiting for something. 118 * 119 * @return {@code true} if the process has been started and is not paused 120 */ 121 public function isRunning(Void):Boolean; 122 123 /** 124 * Returns the percentage of execution 125 * 126 * <p>There are several possibilies of return values: 127 * 128 * <p>If the execution has not been started and the percentage will be 129 * evaluateable for sure it will return {@code 0}. 130 * 131 * <p>If the execution has been started and the percentage is evaluateable, 132 * it returns the current amount of percentage from {@code 0}-{@code 100}. 133 * 134 * <p>If the execution has finished and the percentage was evaluateable, it 135 * returns {@code 100}. 136 * 137 * <p>In any other case it will return {@code null}. 138 * 139 * @return current percentage of execution 140 */ 141 public function getPercentage(Void):Number; 142 143 /** 144 * Allows the integration and access to a process hierarchy. 145 * 146 * @param process {@code Process} that started the current process. 147 * @throws org.as2lib.env.except.IllegalArgumentException if the passed-in 148 * process has the current process within the parent process list or 149 * if the passed-in process is the same process as the current 150 * process. 151 */ 152 public function setParentProcess(process:Process):Void; 153 154 /** 155 * Returns the parent {@code Process} set with {@code setParentProcess}. 156 * 157 * @return parent process if available, else {@code null}. 158 */ 159 public function getParentProcess(Void):Process; 160 161 /** 162 * Returns the occured errors published with {@code onProcessError} during 163 * exeuction of the {@code Process} in an array. 164 * 165 * @return all occured errors during the execution of the event 166 */ 167 public function getErrors(Void):Array; 168 169 /** 170 * Checks if an error occured during execution of the {@code Process}. 171 * 172 * @return {@code true} if an error occured, else {@code false} 173 */ 174 public function hasError(Void):Boolean; 175 176 /** 177 * By using {@code start()} it saves the start time of the execution of the process. 178 * 179 * <p>This method allows access to the total execution time of the process. The total 180 * execution time get evaluated by comparing start time with end time or (if the 181 * process has not finished yet) with the current time. 182 * 183 * @return time difference between start time and finish time or current point 184 */ 185 public function getDuration(Void):Time; 186 187 /** 188 * Evaluates the expected total time of execution. 189 * 190 * <p>If the {@code Process} has been finished it returns the final total time 191 * of the execution. 192 * 193 * <p>If the {@code Process} has not been started it returns a estimated total 194 * time of {@code 0}. 195 * 196 * @return estimated time difference between start and finish time 197 */ 198 public function getEstimatedTotalTime(Void):Time; 199 200 /** 201 * Evaluates the expected rest time until the execution finishes. 202 * 203 * <p>If the {@code Process} has been finished it returns {@code 0}. If it 204 * has not been started it returns {@code null}. 205 * 206 * @return estimated rest time of the execution of the process. 207 */ 208 public function getEstimatedRestTime(Void):Time; 209 }