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    }