001 // License: GPL. For details, see LICENSE file.
002 package org.openstreetmap.josm.actions.downloadtasks;
003
004 import java.util.List;
005 import java.util.concurrent.Future;
006
007 import org.openstreetmap.josm.data.Bounds;
008 import org.openstreetmap.josm.gui.progress.NullProgressMonitor;
009 import org.openstreetmap.josm.gui.progress.ProgressMonitor;
010
011 /**
012 * Interface defining a general download task used to download geographic data (OSM data, GPX tracks, etc.) for a given URL or geographic area.
013 */
014 public interface DownloadTask {
015
016 /**
017 * Asynchronously launches the download task for a given bounding box.
018 *
019 * Set <code>progressMonitor</code> to null, if the task should create, open, and close a progress monitor.
020 * Set progressMonitor to {@link NullProgressMonitor#INSTANCE} if progress information is to
021 * be discarded.
022 *
023 * You can wait for the asynchronous download task to finish by synchronizing on the returned
024 * {@link Future}, but make sure not to freeze up JOSM. Example:
025 * <pre>
026 * Future<?> future = task.download(...);
027 * // DON'T run this on the Swing EDT or JOSM will freeze
028 * future.get(); // waits for the dowload task to complete
029 * </pre>
030 *
031 * The following example uses a pattern which is better suited if a task is launched from
032 * the Swing EDT:
033 * <pre>
034 * final Future<?> future = task.download(...);
035 * Runnable runAfterTask = new Runnable() {
036 * public void run() {
037 * // this is not strictly necessary because of the type of executor service
038 * // Main.worker is initialized with, but it doesn't harm either
039 * //
040 * future.get(); // wait for the download task to complete
041 * doSomethingAfterTheTaskCompleted();
042 * }
043 * }
044 * Main.worker.submit(runAfterTask);
045 * </pre>
046 *
047 * @param newLayer true, if the data is to be downloaded into a new layer. If false, the task
048 * selects one of the existing layers as download layer, preferably the active layer.
049 *
050 * @param downloadArea the area to download
051 * @param progressMonitor the progressMonitor
052 * @return the future representing the asynchronous task
053 */
054 Future<?> download(boolean newLayer, Bounds downloadArea, ProgressMonitor progressMonitor);
055
056 /**
057 * Asynchronously launches the download task for a given bounding URL.
058 *
059 * Set progressMonitor to null, if the task should create, open, and close a progress monitor.
060 * Set progressMonitor to {@link NullProgressMonitor#INSTANCE} if progress information is to
061 * be discarded.
062
063 * @param newLayer newLayer true, if the data is to be downloaded into a new layer. If false, the task
064 * selects one of the existing layers as download layer, preferably the active layer.
065 * @param url the url to download from
066 * @param progressMonitor the progressMonitor
067 * @return the future representing the asynchronous task
068 *
069 * @see #download(boolean, Bounds, ProgressMonitor)
070 */
071 Future<?> loadUrl(boolean newLayer, String url, ProgressMonitor progressMonitor);
072
073 /**
074 * Returns true if the task is able to open the given URL, false otherwise.
075 * @param url the url to download from
076 * @return True if the task is able to open the given URL, false otherwise.
077 */
078 boolean acceptsUrl(String url);
079
080 /**
081 * Replies the error objects of the task. Empty list, if no error messages are available.
082 *
083 * Error objects are either {@link String}s with error messages or {@link Exception}s.
084 *
085 * @return the list of error objects
086 */
087 List<Object> getErrorObjects();
088
089 /**
090 * Cancels the asynchronous download task.
091 *
092 */
093 public void cancel();
094 }