001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.data.osm;
003
004import java.util.Collection;
005import java.util.Map;
006
007/**
008 * Objects implement Tagged if they provide a map of key/value pairs.
009 *
010 * @since 2115
011 */
012// FIXME: better naming? setTags(), getTags(), getKeys() instead of keySet() ?
013//
014public interface Tagged {
015
016    /**
017     * The maximum tag length allowed by OSM API
018     * @since 13414
019     */
020    int MAX_TAG_LENGTH = 255;
021
022    /**
023     * Sets the map of key/value pairs
024     *
025     * @param keys the map of key value pairs. If null, reset to the empty map.
026     */
027    void setKeys(Map<String, String> keys);
028
029    /**
030     * Replies the map of key/value pairs. Never null, but may be the empty map.
031     *
032     * @return the map of key/value pairs
033     */
034    Map<String, String> getKeys();
035
036    /**
037     * Sets a key/value pairs
038     *
039     * @param key the key
040     * @param value the value. If null, removes the key/value pair.
041     */
042    void put(String key, String value);
043
044    /**
045     * Sets a key/value pairs
046     *
047     * @param tag The tag to set.
048     * @since 10736
049     */
050    default void put(Tag tag) {
051        put(tag.getKey(), tag.getValue());
052    }
053
054    /**
055     * Replies the value of the given key; null, if there is no value for this key
056     *
057     * @param key the key
058     * @return the value
059     */
060    String get(String key);
061
062    /**
063     * Removes a given key/value pair
064     *
065     * @param key the key
066     */
067    void remove(String key);
068
069    /**
070     * Replies true, if there is at least one key/value pair; false, otherwise
071     *
072     * @return true, if there is at least one key/value pair; false, otherwise
073     */
074    boolean hasKeys();
075
076    /**
077     * Replies true if there is a tag with key <code>key</code>.
078     * The value could however be empty. See {@link #hasTag(String)} to check for non-empty tags.
079     *
080     * @param key the key
081     * @return true, if there is a tag with key <code>key</code>
082     * @see #hasTag(String)
083     * @since 11608
084     */
085    default boolean hasKey(String key) {
086        return get(key) != null;
087    }
088
089    /**
090     * Replies true if there is a non-empty tag with key <code>key</code>.
091     *
092     * @param key the key
093     * @return true, if there is a non-empty tag with key <code>key</code>
094     * @see Tagged#hasKey(String)
095     * @since 13430
096     */
097    default boolean hasTag(String key) {
098        String v = get(key);
099        return v != null && !v.isEmpty();
100    }
101
102    /**
103     * Replies the set of keys
104     *
105     * @return the set of keys
106     */
107    Collection<String> keySet();
108
109    /**
110     * Removes all tags
111     */
112    void removeAll();
113}