001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.data.osm;
003
004import java.util.Date;
005
006import org.openstreetmap.josm.data.osm.visitor.PrimitiveVisitor;
007import org.openstreetmap.josm.tools.LanguageInfo;
008
009/**
010 * IPrimitive captures the common functions of {@link OsmPrimitive} and {@link PrimitiveData}.
011 * @since 4098
012 */
013public interface IPrimitive extends Tagged, PrimitiveId {
014
015    /**
016     * Replies <code>true</code> if the object has been modified since it was loaded from
017     * the server. In this case, on next upload, this object will be updated.
018     *
019     * Deleted objects are deleted from the server. If the objects are added (id=0),
020     * the modified is ignored and the object is added to the server.
021     *
022     * @return <code>true</code> if the object has been modified since it was loaded from
023     * the server
024     */
025    boolean isModified();
026
027    /**
028     * Marks this primitive as being modified.
029     *
030     * @param modified true, if this primitive is to be modified
031     */
032    void setModified(boolean modified);
033
034    /**
035     * Checks if object is known to the server.
036     * Replies true if this primitive is either unknown to the server (i.e. its id
037     * is 0) or it is known to the server and it hasn't be deleted on the server.
038     * Replies false, if this primitive is known on the server and has been deleted
039     * on the server.
040     *
041     * @return <code>true</code>, if the object is visible on server.
042     * @see #setVisible(boolean)
043     */
044    boolean isVisible();
045
046    /**
047     * Sets whether this primitive is visible, i.e. whether it is known on the server
048     * and not deleted on the server.
049     * @param visible {@code true} if this primitive is visible
050     *
051     * @throws IllegalStateException if visible is set to false on an primitive with id==0
052     * @see #isVisible()
053     */
054    void setVisible(boolean visible);
055
056    /**
057     * Replies <code>true</code>, if the object has been deleted.
058     *
059     * @return <code>true</code>, if the object has been deleted.
060     * @see #setDeleted(boolean)
061     */
062    boolean isDeleted();
063
064    /**
065     * Sets whether this primitive is deleted or not.
066     *
067     * Also marks this primitive as modified if deleted is true.
068     *
069     * @param deleted  true, if this primitive is deleted; false, otherwise
070     */
071    void setDeleted(boolean deleted);
072
073    /**
074     * Determines if this primitive is incomplete.
075     * @return {@code true} if this primitive is incomplete, {@code false} otherwise
076     */
077    boolean isIncomplete();
078
079    /**
080     * Replies <code>true</code> if the object has been deleted on the server and was undeleted by the user.
081     * @return <code>true</code> if the object has been undeleted
082     */
083    boolean isUndeleted();
084
085    /**
086     * Replies <code>true</code>, if the object is usable
087     * (i.e. complete and not deleted).
088     *
089     * @return <code>true</code>, if the object is usable.
090     * @see #setDeleted(boolean)
091     */
092    boolean isUsable();
093
094    /**
095     * Determines if this primitive is new or undeleted.
096     * @return True if primitive is new or undeleted
097     * @see #isNew()
098     * @see #isUndeleted()
099     */
100    boolean isNewOrUndeleted();
101
102    /**
103     * Replies the id of this primitive.
104     *
105     * @return the id of this primitive.
106     */
107    long getId();
108
109    /**
110     * Replies the unique primitive id for this primitive
111     *
112     * @return the unique primitive id for this primitive
113     */
114    PrimitiveId getPrimitiveId();
115
116    /**
117     * Replies the version number as returned by the API. The version is 0 if the id is 0 or
118     * if this primitive is incomplete.
119     * @return the version number as returned by the API
120     *
121     * @see PrimitiveData#setVersion(int)
122     */
123    int getVersion();
124
125    /**
126     * Sets the id and the version of this primitive if it is known to the OSM API.
127     *
128     * Since we know the id and its version it can't be incomplete anymore. incomplete
129     * is set to false.
130     *
131     * @param id the id. &gt; 0 required
132     * @param version the version &gt; 0 required
133     * @throws IllegalArgumentException if id &lt;= 0
134     * @throws IllegalArgumentException if version &lt;= 0
135     * @throws DataIntegrityProblemException if id is changed and primitive was already added to the dataset
136     */
137    void setOsmId(long id, int version);
138
139    /**
140     * Replies the user who has last touched this object. May be null.
141     *
142     * @return the user who has last touched this object. May be null.
143     */
144    User getUser();
145
146    /**
147     * Sets the user who has last touched this object.
148     *
149     * @param user the user
150     */
151    void setUser(User user);
152
153    /**
154     * Time of last modification to this object. This is not set by JOSM but
155     * read from the server and delivered back to the server unmodified. It is
156     * used to check against edit conflicts.
157     *
158     * @return date of last modification
159     * @see #setTimestamp
160     */
161    Date getTimestamp();
162
163    /**
164     * Time of last modification to this object. This is not set by JOSM but
165     * read from the server and delivered back to the server unmodified. It is
166     * used to check against edit conflicts.
167     *
168     * @return last modification as timestamp
169     * @see #setRawTimestamp
170     */
171    int getRawTimestamp();
172
173    /**
174     * Sets time of last modification to this object
175     * @param timestamp date of last modification
176     * @see #getTimestamp
177     */
178    void setTimestamp(Date timestamp);
179
180    /**
181     * Sets time of last modification to this object
182     * @param timestamp date of last modification
183     * @see #getRawTimestamp
184     */
185    void setRawTimestamp(int timestamp);
186
187    /**
188     * Determines if this primitive has no timestam information.
189     * @return {@code true} if this primitive has no timestam information
190     * @see #getTimestamp
191     * @see #getRawTimestamp
192     */
193    boolean isTimestampEmpty();
194
195    /**
196     * Replies the id of the changeset this primitive was last uploaded to.
197     * 0 if this primitive wasn't uploaded to a changeset yet or if the
198     * changeset isn't known.
199     *
200     * @return the id of the changeset this primitive was last uploaded to.
201     */
202    int getChangesetId();
203
204    /**
205     * Sets the changeset id of this primitive. Can't be set on a new primitive.
206     *
207     * @param changesetId the id. &gt;= 0 required.
208     * @throws IllegalStateException if this primitive is new.
209     * @throws IllegalArgumentException if id &lt; 0
210     */
211    void setChangesetId(int changesetId);
212
213    /**
214     * Makes the given visitor visit this primitive.
215     * @param visitor visitor
216     */
217    void accept(PrimitiveVisitor visitor);
218
219    /**
220     * Replies the name of this primitive. The default implementation replies the value
221     * of the tag <tt>name</tt> or null, if this tag is not present.
222     *
223     * @return the name of this primitive
224     */
225    String getName();
226
227    /**
228     * Replies a localized name for this primitive given by the value of the name tags
229     * accessed from very specific (language variant) to more generic (default name).
230     *
231     * @return the name of this primitive, <code>null</code> if no name exists
232     * @see LanguageInfo#getLanguageCodes
233     */
234    String getLocalName();
235}