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 }