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.data.type.Byte; 18 import org.as2lib.data.holder.Map; 19 import org.as2lib.data.type.Bit; 20 import org.as2lib.env.event.EventListenerSource; 21 import org.as2lib.app.exec.Executable; 22 import org.as2lib.io.file.File; 23 import org.as2lib.data.type.Time; 24 25 /** 26 * {@code FileLoader} is built to handle the loading of a external files. 27 * 28 * <p>A {@code FileLoader} allows to get a resource and create a representation 29 * of the certain file to allow proper access. 30 * 31 * <p>It is build to handle the loading of one file. But it can be executed 32 * twice or more often. This is because its possible to handle more than one 33 * request parallel in any system. 34 * 35 * <p>Example to handle the loading of a resource: 36 * <code> 37 * import org.as2lib.io.file.AbstractFileLoader; 38 * import org.as2lib.io.file.FileLoader; 39 * import org.as2lib.io.file.LoadStartListener; 40 * import org.as2lib.io.file.LoadCompleteListener; 41 * import org.as2lib.io.file.LoadProgressListener; 42 * import org.as2lib.io.file.LoadErrorListener; 43 * 44 * class Main implements 45 * LoadStartListener, 46 * LoadCompleteListener, 47 * LoadErrorListener, 48 * LoadProgressListener { 49 * 50 * public function main(loader:FileLoader):Void { 51 * loader.addListener(this); 52 * loader.load("test.txt"); 53 * } 54 * 55 * public function onLoadComplete(loader:FileLoader):Void { 56 * var resource = loader.getFile(); 57 * // Do anything you like.... 58 * } 59 * 60 * public function onLoadError(loader:FileLoader, errorCode:String, error):Boolean { 61 * if (errorCode == AbstractFileLoader.FILE_NOT_FOUND_ERROR) { 62 * trace("Resource could not be found"+error); 63 * } 64 * return false 65 * } 66 * 67 * public function onLoadProgress(loader:FileLoader):Void { 68 * trace("loaded: "+loader.getPercentage()+"% of "+loader.getUri()); 69 * } 70 * 71 * public function onLoadStart(loader:FileLoader):Void { 72 * trace("started loading: "+loader.getUri()); 73 * } 74 * } 75 * </code> 76 * 77 * @author Martin Heidegger 78 * @version 2.0 79 */ 80 interface org.as2lib.io.file.FileLoader extends EventListenerSource { 81 82 /** 83 * Loads a certain resource. 84 * 85 * <p>It sends http request by using the passed-in {@code uri}, {@code method} 86 * and {@code parameters}. 87 * 88 * <p>If you only need to listen if the {@code File} finished loading you can 89 * apply a {@code callBack} that gets called if the {@code File} is loaded. 90 * 91 * <p>Example of using the callback: 92 * <code> 93 * import org.as2lib.io.file.FileLoader; 94 * import org.as2lib.app.exec.Call; 95 * 96 * class Main { 97 * public function main(loader:FileLoader) { 98 * loader.load("test.txt", null, null, new Call(this, resource); 99 * } 100 * 101 * public function finish(resource:Resource):Void { 102 * // Processing the resource ... 103 * } 104 * } 105 * 106 * </code> 107 * 108 * @param uri location of the resource to load 109 * @param parameters (optional) parameters for loading the resource 110 * @param method (optional) POST/GET as method for submitting the parameters, 111 * default method used if {@code method} was not passed-in is POST. 112 * @param callBack (optional) {@link Executable} to be executed after the 113 * the resource was loaded. 114 */ 115 public function load(uri:String, method:String, params:Map, callBack:Executable):Void; 116 117 /** 118 * Returns the URI of the resource that was requested to load. 119 * 120 * @return URI of the resource to load 121 */ 122 public function getUri(Void):String; 123 124 /** 125 * Returns the {@code method} to pass request parameters for request. 126 * 127 * @return method to pass request parameters 128 */ 129 public function getParameterSubmitMethod(Void):String; 130 131 /** 132 * Sets the {@code parameters} for the request to the resource. 133 * 134 * <p>Returns {@code null} if no parameters has been set. 135 * 136 * @return parameters to be passed with the resource request 137 */ 138 public function getParameters(Void):Map; 139 140 /** 141 * Returns the loaded file. 142 * 143 * @return the loaded file 144 * @throws org.as2lib.io.file.ResourceNotLoadedException if the resource has 145 * not been loaded yet 146 */ 147 public function getFile(Void):File; 148 149 /** 150 * Returns the percentage of the execution of {@code null} if its not evaluable. 151 * 152 * @returns the percentage of the execution or {@code null} if its not evaluable 153 */ 154 public function getPercentage(Void):Number; 155 156 /** 157 * Returns the total amount of bytes that has been loaded. 158 * 159 * <p>Returns {@code null} if its not possible to get the loaded bytes. 160 * 161 * @return amount of bytes that has been loaded 162 */ 163 public function getBytesLoaded(Void):Byte; 164 165 /** 166 * Returns the total amount of bytes that will approximately be loaded. 167 * 168 * <p>Returns {@code null} if its not possible to get the total amount of bytes. 169 * 170 * @return amount of bytes to load 171 */ 172 public function getBytesTotal(Void):Byte; 173 174 /** 175 * Returns the current transfer rate for the execution. 176 * 177 * @return transfer rate in bit (per second) 178 */ 179 public function getTransferRate(Void):Bit; 180 181 182 /** 183 * Estimates the approximate time until the resource was loaded. 184 * 185 * @return estimated time until finish of loading 186 */ 187 public function getEstimatedRestTime(Void):Time; 188 189 /** 190 * Estimates the approximate time for the complete loading. 191 * 192 * @return estimated duration at the end of the loading 193 */ 194 public function getEstimatedTotalTime(Void):Time; 195 196 /** 197 * Returns the duration it loads the certain resource. 198 * 199 * @return time difference between start time and end time/current time. 200 */ 201 public function getDuration(Void):Time; 202 }