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&lt;?&gt; 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&lt;?&gt; 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     *    MainApplication.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
131    /**
132     * Sets whether the map view will zoom to download area after download
133     * @param zoomAfterDownload if true, the map view will zoom to download area after download
134     * @since 13261
135     */
136    void setZoomAfterDownload(boolean zoomAfterDownload);
137}