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