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