source: josm/trunk/src/org/openstreetmap/josm/io/ChangesetQuery.java@ 19050

Last change on this file since 19050 was 19050, checked in by taylor.smock, 15 months ago

Revert most var changes from r19048, fix most new compile warnings and checkstyle issues

Also, document why various ErrorProne checks were originally disabled and fix
generic SonarLint issues.
  • Property svn:eol-style set to native
File size: 23.9 KB
Line 
1// License: GPL. For details, see LICENSE file.
2package org.openstreetmap.josm.io;
3
4import static org.openstreetmap.josm.tools.I18n.tr;
5
6import java.text.MessageFormat;
7import java.time.Instant;
8import java.util.ArrayList;
9import java.util.Collection;
10import java.util.Collections;
11import java.util.HashMap;
12import java.util.Map;
13import java.util.Map.Entry;
14import java.util.stream.Collectors;
15import java.util.stream.Stream;
16
17import org.openstreetmap.josm.data.Bounds;
18import org.openstreetmap.josm.data.UserIdentityManager;
19import org.openstreetmap.josm.data.coor.LatLon;
20import org.openstreetmap.josm.tools.CheckParameterUtil;
21import org.openstreetmap.josm.tools.Logging;
22import org.openstreetmap.josm.tools.UncheckedParseException;
23import org.openstreetmap.josm.tools.Utils;
24import org.openstreetmap.josm.tools.date.DateUtils;
25
26/**
27 * Data class to collect restrictions (parameters) for downloading changesets from the
28 * OSM API.
29 * <p>
30 * @see <a href="https://wiki.openstreetmap.org/wiki/API_v0.6#Query:_GET_.2Fapi.2F0.6.2Fchangesets">OSM API 0.6 call "/changesets?"</a>
31 */
32public class ChangesetQuery {
33
34 /**
35 * Maximum number of changesets returned by the OSM API call "/changesets?"
36 */
37 public static final int MAX_CHANGESETS_NUMBER = 100;
38
39 /** the user id this query is restricted to. null, if no restriction to a user id applies */
40 private Integer uid;
41 /** the user name this query is restricted to. null, if no restriction to a user name applies */
42 private String userName;
43 /** the bounding box this query is restricted to. null, if no restriction to a bounding box applies */
44 private Bounds bounds;
45 /** the date after which changesets have been closed this query is restricted to. null, if no restriction to closure date applies */
46 private Instant closedAfter;
47 /** the date before which changesets have been created this query is restricted to. null, if no restriction to creation date applies */
48 private Instant createdBefore;
49 /** indicates whether only open changesets are queried. null, if no restrictions regarding open changesets apply */
50 private Boolean open;
51 /** indicates whether only closed changesets are queried. null, if no restrictions regarding closed changesets apply */
52 private Boolean closed;
53 /** a collection of changeset ids to query for */
54 private Collection<Long> changesetIds;
55
56 /**
57 * Replies a changeset query object from the query part of a OSM API URL for querying changesets.
58 *
59 * @param query the query part
60 * @return the query object
61 * @throws ChangesetQueryUrlException if query doesn't consist of valid query parameters
62 */
63 public static ChangesetQuery buildFromUrlQuery(String query) throws ChangesetQueryUrlException {
64 return new ChangesetQueryUrlParser().parse(query);
65 }
66
67 /**
68 * Replies a changeset query object restricted to the current user, if known.
69 * @return a changeset query object restricted to the current user, if known
70 * @throws IllegalStateException if current user is anonymous
71 * @since 12495
72 */
73 public static ChangesetQuery forCurrentUser() {
74 UserIdentityManager im = UserIdentityManager.getInstance();
75 if (im.isAnonymous()) {
76 throw new IllegalStateException("anonymous user");
77 }
78 ChangesetQuery query = new ChangesetQuery();
79 if (im.isFullyIdentified()) {
80 return query.forUser(im.getUserId());
81 } else {
82 return query.forUser(im.getUserName());
83 }
84 }
85
86 /**
87 * Restricts the query to changesets owned by the user with id <code>uid</code>.
88 *
89 * @param uid the uid of the user. &gt; 0 expected.
90 * @return the query object with the applied restriction
91 * @throws IllegalArgumentException if uid &lt;= 0
92 * @see #forUser(String)
93 */
94 public ChangesetQuery forUser(int uid) {
95 if (uid <= 0)
96 throw new IllegalArgumentException(MessageFormat.format("Parameter ''{0}'' > 0 expected. Got ''{1}''.", "uid", uid));
97 this.uid = uid;
98 this.userName = null;
99 return this;
100 }
101
102 /**
103 * Restricts the query to changesets owned by the user with user name <code>username</code>.
104 *
105 * Caveat: for historical reasons the username might not be unique! It is recommended to use
106 * {@link #forUser(int)} to restrict the query to a specific user.
107 *
108 * @param userName the username. Must not be null.
109 * @return the query object with the applied restriction
110 * @throws IllegalArgumentException if username is null.
111 * @see #forUser(int)
112 */
113 public ChangesetQuery forUser(String userName) {
114 CheckParameterUtil.ensureParameterNotNull(userName, "userName");
115 this.userName = userName;
116 this.uid = null;
117 return this;
118 }
119
120 /**
121 * Replies true if this query is restricted to user whom we only know the user name for.
122 *
123 * @return true if this query is restricted to user whom we only know the user name for
124 */
125 public boolean isRestrictedToPartiallyIdentifiedUser() {
126 return userName != null;
127 }
128
129 /**
130 * Replies true/false if this query is restricted to changesets which are or aren't open.
131 *
132 * @return whether changesets should or should not be open, or {@code null} if there is no restriction
133 * @since 14039
134 */
135 public Boolean getRestrictionToOpen() {
136 return open;
137 }
138
139 /**
140 * Replies true/false if this query is restricted to changesets which are or aren't closed.
141 *
142 * @return whether changesets should or should not be closed, or {@code null} if there is no restriction
143 * @since 14039
144 */
145 public Boolean getRestrictionToClosed() {
146 return closed;
147 }
148
149 /**
150 * Replies the date after which changesets have been closed this query is restricted to.
151 *
152 * @return the date after which changesets have been closed this query is restricted to.
153 * {@code null}, if no restriction to closure date applies
154 * @since 14039
155 */
156 public Instant getClosedAfter() {
157 return closedAfter;
158 }
159
160 /**
161 * Replies the date before which changesets have been created this query is restricted to.
162 *
163 * @return the date before which changesets have been created this query is restricted to.
164 * {@code null}, if no restriction to creation date applies
165 * @since 14039
166 */
167 public Instant getCreatedBefore() {
168 return createdBefore;
169 }
170
171 /**
172 * Replies the list of additional changeset ids to query.
173 * @return the list of additional changeset ids to query (never null)
174 * @since 14039
175 */
176 public final Collection<Long> getAdditionalChangesetIds() {
177 return changesetIds != null ? new ArrayList<>(changesetIds) : Collections.emptyList();
178 }
179
180 /**
181 * Replies the bounding box this query is restricted to.
182 * @return the bounding box this query is restricted to. null, if no restriction to a bounding box applies
183 * @since 14039
184 */
185 public final Bounds getBounds() {
186 return bounds;
187 }
188
189 /**
190 * Replies the user name which this query is restricted to. null, if this query isn't
191 * restricted to a user name, i.e. if {@link #isRestrictedToPartiallyIdentifiedUser()} is false.
192 *
193 * @return the user name which this query is restricted to
194 */
195 public String getUserName() {
196 return userName;
197 }
198
199 /**
200 * Replies true if this query is restricted to user whom know the user id for.
201 *
202 * @return true if this query is restricted to user whom know the user id for
203 */
204 public boolean isRestrictedToFullyIdentifiedUser() {
205 return uid > 0;
206 }
207
208 /**
209 * Replies a query which is restricted to a bounding box.
210 *
211 * @param minLon min longitude of the bounding box. Valid longitude value expected.
212 * @param minLat min latitude of the bounding box. Valid latitude value expected.
213 * @param maxLon max longitude of the bounding box. Valid longitude value expected.
214 * @param maxLat max latitude of the bounding box. Valid latitude value expected.
215 *
216 * @return the restricted changeset query
217 * @throws IllegalArgumentException if either of the parameters isn't a valid longitude or
218 * latitude value
219 */
220 public ChangesetQuery inBbox(double minLon, double minLat, double maxLon, double maxLat) {
221 if (!LatLon.isValidLon(minLon))
222 throw new IllegalArgumentException(tr("Illegal longitude value for parameter ''{0}'', got {1}", "minLon", minLon));
223 if (!LatLon.isValidLon(maxLon))
224 throw new IllegalArgumentException(tr("Illegal longitude value for parameter ''{0}'', got {1}", "maxLon", maxLon));
225 if (!LatLon.isValidLat(minLat))
226 throw new IllegalArgumentException(tr("Illegal latitude value for parameter ''{0}'', got {1}", "minLat", minLat));
227 if (!LatLon.isValidLat(maxLat))
228 throw new IllegalArgumentException(tr("Illegal longitude value for parameter ''{0}'', got {1}", "maxLat", maxLat));
229
230 return inBbox(new LatLon(minLon, minLat), new LatLon(maxLon, maxLat));
231 }
232
233 /**
234 * Replies a query which is restricted to a bounding box.
235 *
236 * @param min the min lat/lon coordinates of the bounding box. Must not be null.
237 * @param max the max lat/lon coordinates of the bounding box. Must not be null.
238 *
239 * @return the restricted changeset query
240 * @throws IllegalArgumentException if min is null
241 * @throws IllegalArgumentException if max is null
242 */
243 public ChangesetQuery inBbox(LatLon min, LatLon max) {
244 CheckParameterUtil.ensureParameterNotNull(min, "min");
245 CheckParameterUtil.ensureParameterNotNull(max, "max");
246 this.bounds = new Bounds(min, max);
247 return this;
248 }
249
250 /**
251 * Replies a query which is restricted to a bounding box given by <code>bbox</code>.
252 *
253 * @param bbox the bounding box. Must not be null.
254 * @return the changeset query
255 * @throws IllegalArgumentException if bbox is null.
256 */
257 public ChangesetQuery inBbox(Bounds bbox) {
258 CheckParameterUtil.ensureParameterNotNull(bbox, "bbox");
259 this.bounds = bbox;
260 return this;
261 }
262
263 /**
264 * Restricts the result to changesets which have been closed after the date given by <code>d</code>.
265 * <code>d</code> d is a date relative to the current time zone.
266 *
267 * @param d the date. Must not be null.
268 * @return the restricted changeset query
269 * @throws IllegalArgumentException if d is null
270 */
271 public ChangesetQuery closedAfter(Instant d) {
272 CheckParameterUtil.ensureParameterNotNull(d, "d");
273 this.closedAfter = d;
274 return this;
275 }
276
277 /**
278 * Restricts the result to changesets which have been closed after <code>closedAfter</code> and which
279 * have been created before <code>createdBefore</code>. Both dates are expressed relative to the current
280 * time zone.
281 *
282 * @param closedAfter only reply changesets closed after this date. Must not be null.
283 * @param createdBefore only reply changesets created before this date. Must not be null.
284 * @return the restricted changeset query
285 * @throws IllegalArgumentException if closedAfter is null
286 * @throws IllegalArgumentException if createdBefore is null
287 */
288 public ChangesetQuery closedAfterAndCreatedBefore(Instant closedAfter, Instant createdBefore) {
289 CheckParameterUtil.ensureParameterNotNull(closedAfter, "closedAfter");
290 CheckParameterUtil.ensureParameterNotNull(createdBefore, "createdBefore");
291 this.closedAfter = closedAfter;
292 this.createdBefore = createdBefore;
293 return this;
294 }
295
296 /**
297 * Restricts the result to changesets which are or aren't open, depending on the value of
298 * <code>isOpen</code>
299 *
300 * @param isOpen whether changesets should or should not be open
301 * @return the restricted changeset query
302 */
303 public ChangesetQuery beingOpen(boolean isOpen) {
304 this.open = isOpen;
305 return this;
306 }
307
308 /**
309 * Restricts the result to changesets which are or aren't closed, depending on the value of
310 * <code>isClosed</code>
311 *
312 * @param isClosed whether changesets should or should not be open
313 * @return the restricted changeset query
314 */
315 public ChangesetQuery beingClosed(boolean isClosed) {
316 this.closed = isClosed;
317 return this;
318 }
319
320 /**
321 * Restricts the query to the given changeset ids (which are added to previously added ones).
322 *
323 * @param changesetIds the changeset ids
324 * @return the query object with the applied restriction
325 * @throws IllegalArgumentException if changesetIds is null.
326 */
327 public ChangesetQuery forChangesetIds(Collection<Long> changesetIds) {
328 CheckParameterUtil.ensureParameterNotNull(changesetIds, "changesetIds");
329 if (changesetIds.size() > MAX_CHANGESETS_NUMBER) {
330 Logging.warn("Changeset query built with more than " + MAX_CHANGESETS_NUMBER + " changeset ids (" + changesetIds.size() + ')');
331 }
332 this.changesetIds = changesetIds;
333 return this;
334 }
335
336 /**
337 * Replies the query string to be used in a query URL for the OSM API.
338 *
339 * @return the query string
340 */
341 public String getQueryString() {
342 StringBuilder sb = new StringBuilder();
343 if (uid != null) {
344 sb.append("user=").append(uid);
345 } else if (userName != null) {
346 sb.append("display_name=").append(Utils.encodeUrl(userName));
347 }
348 if (bounds != null) {
349 if (sb.length() > 0) {
350 sb.append('&');
351 }
352 sb.append("bbox=").append(bounds.encodeAsString(","));
353 }
354 if (closedAfter != null && createdBefore != null) {
355 if (sb.length() > 0) {
356 sb.append('&');
357 }
358 sb.append("time=").append(closedAfter);
359 sb.append(',').append(createdBefore);
360 } else if (closedAfter != null) {
361 if (sb.length() > 0) {
362 sb.append('&');
363 }
364 sb.append("time=").append(closedAfter);
365 }
366
367 if (open != null) {
368 if (sb.length() > 0) {
369 sb.append('&');
370 }
371 sb.append("open=").append(Boolean.toString(open));
372 } else if (closed != null) {
373 if (sb.length() > 0) {
374 sb.append('&');
375 }
376 sb.append("closed=").append(Boolean.toString(closed));
377 } else if (changesetIds != null) {
378 // since 2013-12-05, see https://github.com/openstreetmap/openstreetmap-website/commit/1d1f194d598e54a5d6fb4f38fb569d4138af0dc8
379 if (sb.length() > 0) {
380 sb.append('&');
381 }
382 sb.append("changesets=").append(changesetIds.stream().map(String::valueOf).collect(Collectors.joining(",")));
383 }
384 return sb.toString();
385 }
386
387 @Override
388 public String toString() {
389 return getQueryString();
390 }
391
392 /**
393 * Exception thrown for invalid changeset queries.
394 */
395 public static class ChangesetQueryUrlException extends Exception {
396
397 /**
398 * Constructs a new {@code ChangesetQueryUrlException} with the specified detail message.
399 *
400 * @param message the detail message. The detail message is saved for later retrieval by the {@link #getMessage()} method.
401 */
402 public ChangesetQueryUrlException(String message) {
403 super(message);
404 }
405
406 /**
407 * Constructs a new {@code ChangesetQueryUrlException} with the specified cause and detail message.
408 *
409 * @param message the detail message. The detail message is saved for later retrieval by the {@link #getMessage()} method.
410 * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method).
411 * (A <code>null</code> value is permitted, and indicates that the cause is nonexistent or unknown.)
412 */
413 public ChangesetQueryUrlException(String message, Throwable cause) {
414 super(message, cause);
415 }
416
417 /**
418 * Constructs a new {@code ChangesetQueryUrlException} with the specified cause and a detail message of
419 * <code>(cause==null ? null : cause.toString())</code> (which typically contains the class and detail message of <code>cause</code>).
420 *
421 * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method).
422 * (A <code>null</code> value is permitted, and indicates that the cause is nonexistent or unknown.)
423 */
424 public ChangesetQueryUrlException(Throwable cause) {
425 super(cause);
426 }
427 }
428
429 /**
430 * Changeset query URL parser.
431 */
432 public static class ChangesetQueryUrlParser {
433 protected int parseUid(String value) throws ChangesetQueryUrlException {
434 if (Utils.isBlank(value))
435 throw new ChangesetQueryUrlException(
436 tr("Unexpected value for ''{0}'' in changeset query url, got {1}", "uid", value));
437 int id;
438 try {
439 id = Integer.parseInt(value);
440 if (id <= 0)
441 throw new ChangesetQueryUrlException(
442 tr("Unexpected value for ''{0}'' in changeset query url, got {1}", "uid", value));
443 } catch (NumberFormatException e) {
444 throw new ChangesetQueryUrlException(
445 tr("Unexpected value for ''{0}'' in changeset query url, got {1}", "uid", value), e);
446 }
447 return id;
448 }
449
450 protected boolean parseBoolean(String value, String parameter) throws ChangesetQueryUrlException {
451 if (Utils.isBlank(value))
452 throw new ChangesetQueryUrlException(
453 tr("Unexpected value for ''{0}'' in changeset query url, got {1}", parameter, value));
454 switch (value) {
455 case "true":
456 return true;
457 case "false":
458 return false;
459 default:
460 throw new ChangesetQueryUrlException(
461 tr("Unexpected value for ''{0}'' in changeset query url, got {1}", parameter, value));
462 }
463 }
464
465 protected Instant parseDate(String value, String parameter) throws ChangesetQueryUrlException {
466 if (Utils.isBlank(value))
467 throw new ChangesetQueryUrlException(
468 tr("Unexpected value for ''{0}'' in changeset query url, got {1}", parameter, value));
469 try {
470 return DateUtils.parseInstant(value);
471 } catch (UncheckedParseException e) {
472 throw new ChangesetQueryUrlException(
473 tr("Unexpected value for ''{0}'' in changeset query url, got {1}", parameter, value), e);
474 }
475 }
476
477 protected Instant[] parseTime(String value) throws ChangesetQueryUrlException {
478 String[] dates = value.split(",", -1);
479 if (dates.length == 0 || dates.length > 2)
480 throw new ChangesetQueryUrlException(
481 tr("Unexpected value for ''{0}'' in changeset query url, got {1}", "time", value));
482 if (dates.length == 1)
483 return new Instant[]{parseDate(dates[0], "time")};
484 else if (dates.length == 2)
485 return new Instant[]{parseDate(dates[0], "time"), parseDate(dates[1], "time")};
486 return new Instant[]{};
487 }
488
489 protected Collection<Long> parseLongs(String value) {
490 if (Utils.isEmpty(value)) {
491 return Collections.<Long>emptySet();
492 } else {
493 return Stream.of(value.split(",", -1)).map(Long::valueOf).collect(Collectors.toSet());
494 }
495 }
496
497 protected ChangesetQuery createFromMap(Map<String, String> queryParams) throws ChangesetQueryUrlException {
498 ChangesetQuery csQuery = new ChangesetQuery();
499
500 for (Entry<String, String> entry: queryParams.entrySet()) {
501 String k = entry.getKey();
502 switch (k) {
503 case "uid":
504 if (queryParams.containsKey("display_name"))
505 throw new ChangesetQueryUrlException(
506 tr("Cannot create a changeset query including both the query parameters ''uid'' and ''display_name''"));
507 csQuery.forUser(parseUid(queryParams.get("uid")));
508 break;
509 case "display_name":
510 if (queryParams.containsKey("uid"))
511 throw new ChangesetQueryUrlException(
512 tr("Cannot create a changeset query including both the query parameters ''uid'' and ''display_name''"));
513 csQuery.forUser(queryParams.get("display_name"));
514 break;
515 case "open":
516 csQuery.beingOpen(parseBoolean(entry.getValue(), "open"));
517 break;
518 case "closed":
519 csQuery.beingClosed(parseBoolean(entry.getValue(), "closed"));
520 break;
521 case "time":
522 Instant[] dates = parseTime(entry.getValue());
523 switch (dates.length) {
524 case 1:
525 csQuery.closedAfter(dates[0]);
526 break;
527 case 2:
528 csQuery.closedAfterAndCreatedBefore(dates[0], dates[1]);
529 break;
530 default:
531 Logging.warn("Unable to parse time: " + entry.getValue());
532 }
533 break;
534 case "bbox":
535 try {
536 csQuery.inBbox(new Bounds(entry.getValue(), ","));
537 } catch (IllegalArgumentException e) {
538 throw new ChangesetQueryUrlException(e);
539 }
540 break;
541 case "changesets":
542 try {
543 csQuery.forChangesetIds(parseLongs(entry.getValue()));
544 } catch (NumberFormatException e) {
545 throw new ChangesetQueryUrlException(e);
546 }
547 break;
548 default:
549 throw new ChangesetQueryUrlException(
550 tr("Unsupported parameter ''{0}'' in changeset query string", k));
551 }
552 }
553 return csQuery;
554 }
555
556 protected Map<String, String> createMapFromQueryString(String query) {
557 Map<String, String> queryParams = new HashMap<>();
558 String[] keyValuePairs = query.split("&", -1);
559 for (String keyValuePair: keyValuePairs) {
560 String[] kv = keyValuePair.split("=", -1);
561 queryParams.put(kv[0], kv.length > 1 ? kv[1] : "");
562 }
563 return queryParams;
564 }
565
566 /**
567 * Parses the changeset query given as URL query parameters and replies a {@link ChangesetQuery}.
568 *
569 * <code>query</code> is the query part of a API url for querying changesets,
570 * see <a href="http://wiki.openstreetmap.org/wiki/API_v0.6#Query:_GET_.2Fapi.2F0.6.2Fchangesets">OSM API</a>.
571 *
572 * Example for a query string:<br>
573 * <pre>
574 * uid=1234&amp;open=true
575 * </pre>
576 *
577 * @param query the query string. If null, an empty query (identical to a query for all changesets) is assumed
578 * @return the changeset query
579 * @throws ChangesetQueryUrlException if the query string doesn't represent a legal query for changesets
580 */
581 public ChangesetQuery parse(String query) throws ChangesetQueryUrlException {
582 if (query == null)
583 return new ChangesetQuery();
584 String apiQuery = query.trim();
585 if (apiQuery.isEmpty())
586 return new ChangesetQuery();
587 return createFromMap(createMapFromQueryString(apiQuery));
588 }
589 }
590}
Note: See TracBrowser for help on using the repository browser.