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