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 * @param isRemotecontrol True if download request comes from remotecontrol. 078 * @return True if the task is able to open the given URL, false otherwise. 079 * Return false, if the request comes from remotecontrol, but the task is not 080 * safe for remotecontrol. 081 * A task is not safe for remotecontrol if it is possible to prepare a file 082 * for download which does something unintended, e.g. gain access to the 083 * local file system. 084 */ 085 boolean acceptsUrl(String url, boolean isRemotecontrol); 086 087 /** 088 * Returns a short HTML documentation string, describing acceptable URLs. 089 * @return The HTML documentation 090 * @since 6031 091 */ 092 String acceptsDocumentationSummary(); 093 094 /** 095 * Returns human-readable description of the task 096 * @return The task description 097 * @since 6031 098 */ 099 String getTitle(); 100 101 /** 102 * Returns regular expressions that match the URLs 103 * @return The array of accepted URL patterns 104 * @since 6031 105 */ 106 String[] getPatterns(); 107 108 /** 109 * Replies the error objects of the task. Empty list, if no error messages are available. 110 * 111 * Error objects are either {@link String}s with error messages or {@link Exception}s. 112 * 113 * @return the list of error objects 114 */ 115 List<Object> getErrorObjects(); 116 117 /** 118 * Cancels the asynchronous download task. 119 * 120 */ 121 void cancel(); 122 123 /** 124 * Replies the HTML-formatted confirmation message to be shown to user when the given URL needs to be confirmed before loading. 125 * @param url The URL to be confirmed 126 * @return The HTML-formatted confirmation message to be shown to user 127 * @since 5691 128 */ 129 String getConfirmationMessage(URL url); 130}