source: josm/trunk/src/org/openstreetmap/josm/data/osm/IPrimitive.java

Last change on this file was 19108, checked in by taylor.smock, 10 days ago

Cleanup some new PMD warnings from PMD 7.x (followup of r19101)
  • Property svn:eol-style set to native
File size: 17.8 KB
Line 
1// License: GPL. For details, see LICENSE file.
2package org.openstreetmap.josm.data.osm;
3
4import java.time.Instant;
5import java.util.Collections;
6import java.util.Date;
7import java.util.List;
8import java.util.Map;
9
10import org.openstreetmap.josm.data.IQuadBucketType;
11import org.openstreetmap.josm.data.osm.visitor.PrimitiveVisitor;
12import org.openstreetmap.josm.tools.LanguageInfo;
13
14/**
15 * IPrimitive captures the common functions of {@link OsmPrimitive} and {@link PrimitiveData}.
16 * @since 4098
17 */
18public interface IPrimitive extends IQuadBucketType, Tagged, PrimitiveId, Stylable, Comparable<IPrimitive> {
19
20 /**
21 * Replies <code>true</code> if the object has been modified since it was loaded from
22 * the server. In this case, on next upload, this object will be updated.
23 * <p>
24 * Deleted objects are deleted from the server. If the objects are added (id=0),
25 * the modified is ignored and the object is added to the server.
26 *
27 * @return <code>true</code> if the object has been modified since it was loaded from
28 * the server
29 */
30 boolean isModified();
31
32 /**
33 * Marks this primitive as being modified.
34 *
35 * @param modified true, if this primitive is to be modified
36 */
37 void setModified(boolean modified);
38
39 /**
40 * Set the status of the referrers
41 * @param referrersDownloaded {@code true} if all referrers for this object have been downloaded
42 * @since xxx
43 */
44 default void setReferrersDownloaded(boolean referrersDownloaded) {
45 throw new UnsupportedOperationException(this.getClass().getName() + " does not support referrers status");
46 }
47
48 /**
49 * Checks if object is known to the server.
50 * Replies true if this primitive is either unknown to the server (i.e. its id
51 * is 0) or it is known to the server and it hasn't be deleted on the server.
52 * Replies false, if this primitive is known on the server and has been deleted
53 * on the server.
54 *
55 * @return <code>true</code>, if the object is visible on server.
56 * @see #setVisible(boolean)
57 */
58 boolean isVisible();
59
60 /**
61 * Sets whether this primitive is visible, i.e. whether it is known on the server
62 * and not deleted on the server.
63 * @param visible {@code true} if this primitive is visible
64 *
65 * @throws IllegalStateException if visible is set to false on an primitive with id==0
66 * @see #isVisible()
67 */
68 void setVisible(boolean visible);
69
70 /**
71 * Replies <code>true</code>, if the object has been deleted.
72 *
73 * @return <code>true</code>, if the object has been deleted.
74 * @see #setDeleted(boolean)
75 */
76 boolean isDeleted();
77
78 /**
79 * Sets whether this primitive is deleted or not.
80 * <p>
81 * Also marks this primitive as modified if deleted is true.
82 *
83 * @param deleted true, if this primitive is deleted; false, otherwise
84 */
85 void setDeleted(boolean deleted);
86
87 /**
88 * Determines if this primitive is fully downloaded
89 * @return {@code true} if the primitive is fully downloaded and all parents and children should be available.
90 * {@code false} otherwise.
91 * @since xxx
92 */
93 default boolean isReferrersDownloaded() {
94 return false;
95 }
96
97 /**
98 * Determines if this primitive is incomplete.
99 * @return {@code true} if this primitive is incomplete, {@code false} otherwise
100 */
101 boolean isIncomplete();
102
103 /**
104 * Replies <code>true</code> if the object has been deleted on the server and was undeleted by the user.
105 * @return <code>true</code> if the object has been undeleted
106 */
107 boolean isUndeleted();
108
109 /**
110 * Replies <code>true</code>, if the object is usable
111 * (i.e. complete and not deleted).
112 *
113 * @return <code>true</code>, if the object is usable.
114 * @see #setDeleted(boolean)
115 */
116 boolean isUsable();
117
118 /**
119 * Determines if this primitive is new or undeleted.
120 * @return True if primitive is new or undeleted
121 * @see #isNew()
122 * @see #isUndeleted()
123 */
124 boolean isNewOrUndeleted();
125
126 /**
127 * Replies true, if this primitive is disabled. (E.g. a filter applies)
128 * @return {@code true} if this object has the "disabled" flag enabled
129 * @since 13662
130 */
131 default boolean isDisabled() {
132 return false;
133 }
134
135 /**
136 * Replies true, if this primitive is disabled and marked as completely hidden on the map.
137 * @return {@code true} if this object has both the "disabled" and "hide if disabled" flags enabled
138 * @since 13662
139 */
140 default boolean isDisabledAndHidden() {
141 return false;
142 }
143
144 /**
145 * Replies true, if this primitive is preserved from filtering.
146 * @return {@code true} if this object has the "preserved" flag enabled
147 * @since 13764
148 */
149 default boolean isPreserved() {
150 return false;
151 }
152
153 /**
154 * Determines if this object is selectable.
155 * <p>
156 * A primitive can be selected if all conditions are met:
157 * <ul>
158 * <li>it is drawable
159 * <li>it is not disabled (greyed out) by a filter.
160 * </ul>
161 * @return {@code true} if this object is selectable
162 * @since 13664
163 */
164 default boolean isSelectable() {
165 return true;
166 }
167
168 /**
169 * Determines if this object is drawable.
170 * <p>
171 * A primitive is drawable if all conditions are met:
172 * <ul>
173 * <li>type and id is known
174 * <li>tags are known
175 * <li>it is not deleted
176 * <li>it is not hidden by a filter
177 * <li>for nodes: lat/lon are known
178 * <li>for ways: all nodes are known and complete
179 * <li>for relations: all members are known and complete
180 * </ul>
181 * @return {@code true} if this object is drawable
182 * @since 13664
183 */
184 default boolean isDrawable() {
185 return true;
186 }
187
188 /**
189 * Determines whether the primitive is selected
190 * @return whether the primitive is selected
191 * @since 13664
192 */
193 default boolean isSelected() {
194 return false;
195 }
196
197 /**
198 * Determines if this primitive is a member of a selected relation.
199 * @return {@code true} if this primitive is a member of a selected relation, {@code false} otherwise
200 * @since 13664
201 */
202 default boolean isMemberOfSelected() {
203 return false;
204 }
205
206 /**
207 * Determines if this primitive is an outer member of a selected multipolygon relation.
208 * @return {@code true} if this primitive is an outer member of a selected multipolygon relation, {@code false} otherwise
209 * @since 13664
210 */
211 default boolean isOuterMemberOfSelected() {
212 return false;
213 }
214
215 /**
216 * Replies the id of this primitive.
217 *
218 * @return the id of this primitive.
219 */
220 long getId();
221
222 /**
223 * Replies the OSM id of this primitive.
224 * By default, returns the same value as {@link #getId}.
225 * Can be overridden by primitive implementations handling an internal id different from the OSM one.
226 *
227 * @return the OSM id of this primitive.
228 * @since 13924
229 */
230 default long getOsmId() {
231 return getId();
232 }
233
234 /**
235 * Replies the OSM primitive id for this primitive.
236 *
237 * @return the OSM primitive id for this primitive
238 * @see #getOsmId
239 * @since 13924
240 */
241 default PrimitiveId getOsmPrimitiveId() {
242 return new SimplePrimitiveId(getOsmId(), getType());
243 }
244
245 /**
246 * Replies the unique primitive id for this primitive.
247 *
248 * @return the unique primitive id for this primitive
249 * @see #getUniqueId
250 */
251 default PrimitiveId getPrimitiveId() {
252 return new SimplePrimitiveId(getUniqueId(), getType());
253 }
254
255 /**
256 * Replies the version number as returned by the API. The version is 0 if the id is 0 or
257 * if this primitive is incomplete.
258 * @return the version number as returned by the API
259 *
260 * @see PrimitiveData#setVersion(int)
261 */
262 int getVersion();
263
264 /**
265 * Sets the id and the version of this primitive if it is known to the OSM API.
266 * <p>
267 * Since we know the id and its version it can't be incomplete anymore. incomplete
268 * is set to false.
269 *
270 * @param id the id. &gt; 0 required
271 * @param version the version &gt; 0 required
272 * @throws IllegalArgumentException if id &lt;= 0
273 * @throws IllegalArgumentException if version &lt;= 0
274 * @throws DataIntegrityProblemException if id is changed and primitive was already added to the dataset
275 */
276 void setOsmId(long id, int version);
277
278 /**
279 * Replies the user who has last touched this object. May be null.
280 *
281 * @return the user who has last touched this object. May be null.
282 */
283 User getUser();
284
285 /**
286 * Sets the user who has last touched this object.
287 *
288 * @param user the user
289 */
290 void setUser(User user);
291
292 /**
293 * Time of last modification to this object. This is not set by JOSM but
294 * read from the server and delivered back to the server unmodified. It is
295 * used to check against edit conflicts.
296 *
297 * @return date of last modification
298 * @see #setTimestamp
299 * @deprecated since 17749, use {@link #getInstant} instead
300 */
301 @Deprecated(since = "17749")
302 Date getTimestamp();
303
304 /**
305 * Time of last modification to this object. This is not set by JOSM but
306 * read from the server and delivered back to the server unmodified. It is
307 * used to check against edit conflicts.
308 *
309 * @return date of last modification
310 * @see #setInstant
311 */
312 Instant getInstant();
313
314 /**
315 * Time of last modification to this object. This is not set by JOSM but
316 * read from the server and delivered back to the server unmodified. It is
317 * used to check against edit conflicts.
318 *
319 * @return last modification as timestamp
320 * @see #setRawTimestamp
321 */
322 int getRawTimestamp();
323
324 /**
325 * Sets time of last modification to this object
326 * @param timestamp date of last modification
327 * @see #getTimestamp
328 * @deprecated since 17749, use {@link #setInstant} instead
329 */
330 @Deprecated(since = "17749")
331 void setTimestamp(Date timestamp);
332
333 /**
334 * Sets time of last modification to this object
335 * @param timestamp date of last modification
336 * @see #getInstant
337 */
338 void setInstant(Instant timestamp);
339
340 /**
341 * Sets time of last modification to this object
342 * @param timestamp date of last modification
343 * @see #getRawTimestamp
344 */
345 void setRawTimestamp(int timestamp);
346
347 /**
348 * Determines if this primitive has no timestamp information.
349 * @return {@code true} if this primitive has no timestamp information
350 * @see #getTimestamp
351 * @see #getRawTimestamp
352 */
353 boolean isTimestampEmpty();
354
355 /**
356 * Replies the id of the changeset this primitive was last uploaded to.
357 * 0 if this primitive wasn't uploaded to a changeset yet or if the
358 * changeset isn't known.
359 *
360 * @return the id of the changeset this primitive was last uploaded to.
361 */
362 int getChangesetId();
363
364 /**
365 * Sets the changeset id of this primitive. Can't be set on a new primitive.
366 *
367 * @param changesetId the id. &gt;= 0 required.
368 * @throws IllegalStateException if this primitive is new.
369 * @throws IllegalArgumentException if id &lt; 0
370 */
371 void setChangesetId(int changesetId);
372
373 /**
374 * Makes the given visitor visit this primitive.
375 * @param visitor visitor
376 */
377 void accept(PrimitiveVisitor visitor);
378
379 /**
380 * <p>Visits {@code visitor} for all referrers.</p>
381 *
382 * @param visitor the visitor. Ignored, if null.
383 * @since 13806
384 */
385 void visitReferrers(PrimitiveVisitor visitor);
386
387 /**
388 * Replies the name of this primitive. The default implementation replies the value
389 * of the tag <code>name</code> or null, if this tag is not present.
390 *
391 * @return the name of this primitive
392 */
393 default String getName() {
394 return get("name");
395 }
396
397 /**
398 * Replies a localized name for this primitive given by the value of the name tags
399 * accessed from very specific (language variant) to more generic (default name).
400 *
401 * @return the name of this primitive, <code>null</code> if no name exists
402 * @see LanguageInfo#getOSMLocaleCodes
403 */
404 default String getLocalName() {
405 for (String s : LanguageInfo.getOSMLocaleCodes("name:")) {
406 String val = get(s);
407 if (val != null)
408 return val;
409 }
410
411 return getName();
412 }
413
414 /**
415 * Get an object to synchronize the style cache on. This <i>should</i> be a field that does not change during paint.
416 * By default, it returns the current object, but should be overridden to avoid some performance issues.
417 * @return A non-{@code null} object to synchronize on when painting
418 */
419 default Object getStyleCacheSyncObject() {
420 return this;
421 }
422
423 /**
424 * Replies the display name of a primitive formatted by <code>formatter</code>
425 * @param formatter formatter to use
426 *
427 * @return the display name
428 * @since 13564
429 */
430 String getDisplayName(NameFormatter formatter);
431
432 /**
433 * Gets the type this primitive is displayed at
434 * @return A {@link OsmPrimitiveType}
435 * @since 13564
436 */
437 default OsmPrimitiveType getDisplayType() {
438 return getType();
439 }
440
441 /**
442 * Updates the highlight flag for this primitive.
443 * @param highlighted The new highlight flag.
444 * @since 13664
445 */
446 void setHighlighted(boolean highlighted);
447
448 /**
449 * Checks if the highlight flag for this primitive was set
450 * @return The highlight flag.
451 * @since 13664
452 */
453 boolean isHighlighted();
454
455 /**
456 * Determines if this object is considered "tagged". To be "tagged", an object
457 * must have one or more "interesting" tags. "created_by" and "source"
458 * are typically considered "uninteresting" and do not make an object "tagged".
459 * @return true if this object is considered "tagged"
460 * @since 13662
461 */
462 boolean isTagged();
463
464 /**
465 * Determines if this object is considered "annotated". To be "annotated", an object
466 * must have one or more "work in progress" tags, such as "note" or "fixme".
467 * @return true if this object is considered "annotated"
468 * @since 13662
469 */
470 boolean isAnnotated();
471
472 /**
473 * Determines if this object is a relation and behaves as a multipolygon.
474 * @return {@code true} if it is a real multipolygon or a boundary relation
475 * @since 13667
476 */
477 default boolean isMultipolygon() {
478 return false;
479 }
480
481 /**
482 * true if this object has direction dependent tags (e.g. oneway)
483 * @return {@code true} if this object has direction dependent tags
484 * @since 13662
485 */
486 boolean hasDirectionKeys();
487
488 /**
489 * true if this object has the "reversed direction" flag enabled
490 * @return {@code true} if this object has the "reversed direction" flag enabled
491 * @since 13662
492 */
493 boolean reversedDirection();
494
495 /**
496 * Fetches the bounding box of the primitive.
497 * Since 17752, the returned bounding box might be immutable, i.e., modifying calls throw an {@link UnsupportedOperationException}.
498 * @return Bounding box of the object
499 * @since 13764
500 */
501 @Override
502 BBox getBBox();
503
504 /**
505 * Gets a list of all primitives in the current dataset that reference this primitive.
506 * @return The referrers
507 * @since 13764
508 */
509 default List<? extends IPrimitive> getReferrers() {
510 return getReferrers(false);
511 }
512
513 /**
514 * Find primitives that reference this primitive. Returns only primitives that are included in the same
515 * dataset as this primitive. <br>
516 *
517 * For example following code will add wnew as referer to all nodes of existingWay, but this method will
518 * not return wnew because it's not part of the dataset <br>
519 *
520 * <code>Way wnew = new Way(existingWay)</code>
521 *
522 * @param allowWithoutDataset If true, method will return empty list if primitive is not part of the dataset. If false,
523 * exception will be thrown in this case
524 *
525 * @return a collection of all primitives that reference this primitive.
526 * @since 13808
527 */
528 List<? extends IPrimitive> getReferrers(boolean allowWithoutDataset);
529
530 /**
531 * Returns the parent data set of this primitive.
532 * @return OsmData this primitive is part of.
533 * @since 13807
534 */
535 OsmData<?, ?, ?, ?> getDataSet();
536
537 /**
538 * Returns {@link #getKeys()} for which {@code key} does not fulfill uninteresting criteria.
539 * @return A map of interesting tags
540 * @since 13809
541 */
542 Map<String, String> getInterestingTags();
543
544 /**
545 * Replies true if other isn't null and has the same interesting tags (key/value-pairs) as this.
546 *
547 * @param other the other object primitive
548 * @return true if other isn't null and has the same interesting tags (key/value-pairs) as this.
549 * @since 13809
550 */
551 default boolean hasSameInterestingTags(IPrimitive other) {
552 return (!hasKeys() && !other.hasKeys())
553 || getInterestingTags().equals(other.getInterestingTags());
554 }
555
556 /**
557 * Resets primitive children, if applicable.
558 * @param p primitive
559 * @since 17981
560 */
561 static void resetPrimitiveChildren(IPrimitive p) {
562 if (p instanceof IWay<?>) {
563 ((IWay<?>) p).setNodes(null);
564 } else if (p instanceof IRelation<?>) {
565 ((IRelation<?>) p).setMembers(null);
566 }
567 }
568
569 /**
570 * Get child primitives that are referred by this primitive.
571 * {@link Relation}: Members of the relation
572 * {@link Way}: Nodes used by the way
573 * {@link Node}: None
574 * @return List of child primitives
575 * @since 18814
576 */
577 default List<? extends IPrimitive> getChildren() {
578 return Collections.emptyList();
579 }
580}
Note: See TracBrowser for help on using the repository browser.