1 | // License: GPL. For details, see LICENSE file.
|
---|
2 | package org.openstreetmap.josm.actions.downloadtasks;
|
---|
3 |
|
---|
4 | import java.util.List;
|
---|
5 | import java.util.concurrent.Future;
|
---|
6 |
|
---|
7 | import org.openstreetmap.josm.data.Bounds;
|
---|
8 | import org.openstreetmap.josm.gui.progress.NullProgressMonitor;
|
---|
9 | import org.openstreetmap.josm.gui.progress.ProgressMonitor;
|
---|
10 |
|
---|
11 | /**
|
---|
12 | * Interface defining a general download task used to download geographic data (OSM data, GPX tracks, etc.) for a given URL or geographic area.
|
---|
13 | */
|
---|
14 | public interface DownloadTask {
|
---|
15 |
|
---|
16 | /**
|
---|
17 | * Asynchronously launches the download task for a given bounding box.
|
---|
18 | *
|
---|
19 | * Set <code>progressMonitor</code> to null, if the task should create, open, and close a progress monitor.
|
---|
20 | * Set progressMonitor to {@link NullProgressMonitor#INSTANCE} if progress information is to
|
---|
21 | * be discarded.
|
---|
22 | *
|
---|
23 | * You can wait for the asynchronous download task to finish by synchronizing on the returned
|
---|
24 | * {@link Future}, but make sure not to freeze up JOSM. Example:
|
---|
25 | * <pre>
|
---|
26 | * Future<?> future = task.download(...);
|
---|
27 | * // DON'T run this on the Swing EDT or JOSM will freeze
|
---|
28 | * future.get(); // waits for the dowload task to complete
|
---|
29 | * </pre>
|
---|
30 | *
|
---|
31 | * The following example uses a pattern which is better suited if a task is launched from
|
---|
32 | * the Swing EDT:
|
---|
33 | * <pre>
|
---|
34 | * final Future<?> future = task.download(...);
|
---|
35 | * Runnable runAfterTask = new Runnable() {
|
---|
36 | * public void run() {
|
---|
37 | * // this is not strictly necessary because of the type of executor service
|
---|
38 | * // Main.worker is initialized with, but it doesn't harm either
|
---|
39 | * //
|
---|
40 | * future.get(); // wait for the download task to complete
|
---|
41 | * doSomethingAfterTheTaskCompleted();
|
---|
42 | * }
|
---|
43 | * }
|
---|
44 | * Main.worker.submit(runAfterTask);
|
---|
45 | * </pre>
|
---|
46 | *
|
---|
47 | * @param newLayer true, if the data is to be downloaded into a new layer. If false, the task
|
---|
48 | * selects one of the existing layers as download layer, preferably the active layer.
|
---|
49 | *
|
---|
50 | * @param downloadArea the area to download
|
---|
51 | * @param progressMonitor the progressMonitor
|
---|
52 | * @return the future representing the asynchronous task
|
---|
53 | */
|
---|
54 | Future<?> download(boolean newLayer, Bounds downloadArea, ProgressMonitor progressMonitor);
|
---|
55 |
|
---|
56 | /**
|
---|
57 | * Asynchronously launches the download task for a given bounding URL.
|
---|
58 | *
|
---|
59 | * Set progressMonitor to null, if the task should create, open, and close a progress monitor.
|
---|
60 | * Set progressMonitor to {@link NullProgressMonitor#INSTANCE} if progress information is to
|
---|
61 | * be discarded.
|
---|
62 |
|
---|
63 | * @param newLayer newLayer true, if the data is to be downloaded into a new layer. If false, the task
|
---|
64 | * selects one of the existing layers as download layer, preferably the active layer.
|
---|
65 | * @param url the url to download from
|
---|
66 | * @param progressMonitor the progressMonitor
|
---|
67 | * @return the future representing the asynchronous task
|
---|
68 | *
|
---|
69 | * @see #download(boolean, Bounds, ProgressMonitor)
|
---|
70 | */
|
---|
71 | Future<?> loadUrl(boolean newLayer, String url, ProgressMonitor progressMonitor);
|
---|
72 |
|
---|
73 | /**
|
---|
74 | * Returns true if the task is able to open the given URL, false otherwise.
|
---|
75 | * @param url the url to download from
|
---|
76 | * @return True if the task is able to open the given URL, false otherwise.
|
---|
77 | */
|
---|
78 | boolean acceptsUrl(String url);
|
---|
79 |
|
---|
80 | /**
|
---|
81 | * Replies the error objects of the task. Empty list, if no error messages are available.
|
---|
82 | *
|
---|
83 | * Error objects are either {@link String}s with error messages or {@link Exception}s.
|
---|
84 | *
|
---|
85 | * @return the list of error objects
|
---|
86 | */
|
---|
87 | List<Object> getErrorObjects();
|
---|
88 |
|
---|
89 | /**
|
---|
90 | * Cancels the asynchronous download task.
|
---|
91 | *
|
---|
92 | */
|
---|
93 | public void cancel();
|
---|
94 | }
|
---|