Ignore:
Timestamp:
2014-09-11T19:27:03+02:00 (10 years ago)
Author:
Don-vip
Message:

see #10462 - more debug stuff, improve javadoc

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/org/openstreetmap/josm/data/osm/history/History.java

    r7005 r7527  
    1717 * Represents the history of an OSM primitive. The history consists
    1818 * of a list of object snapshots with a specific version.
    19  *
     19 * @since 1670
    2020 */
    21 public class History{
     21public class History {
     22
    2223    private static interface FilterPredicate {
    2324        boolean matches(HistoryOsmPrimitive primitive);
    … …  
    3839    /** the object id */
    3940    private final long id;
     41    /** the object type */
    4042    private final OsmPrimitiveType type;
    4143
    4244    /**
    43      * Creates a new history for an OSM primitive
     45     * Creates a new history for an OSM primitive.
    4446     *
    4547     * @param id the id. > 0 required.
    … …  
    6264    }
    6365
     66    /**
     67     * Returns a new copy of this history, sorted in ascending order.
     68     * @return a new copy of this history, sorted in ascending order
     69     */
    6470    public History sortAscending() {
    6571        List<HistoryOsmPrimitive> copy = new ArrayList<>(versions);
    … …  
    7278                    }
    7379                }
    74                 );
     80            );
    7581        return new History(id, type, copy);
    7682    }
    7783
     84    /**
     85     * Returns a new copy of this history, sorted in descending order.
     86     * @return a new copy of this history, sorted in descending order
     87     */
    7888    public History sortDescending() {
    7989        List<HistoryOsmPrimitive> copy = new ArrayList<>(versions);
    … …  
    8696                    }
    8797                }
    88                 );
     98            );
    8999        return new History(id, type,copy);
    90100    }
    91101
     102    /**
     103     * Returns a new partial copy of this history, from the given date
     104     * @param fromDate the starting date
     105     * @return a new partial copy of this history, from the given date
     106     */
    92107    public History from(final Date fromDate) {
    93108        return filter(
    … …  
    99114                    }
    100115                }
    101                 );
    102     }
    103 
     116            );
     117    }
     118
     119    /**
     120     * Returns a new partial copy of this history, until the given date
     121     * @param untilDate the end date
     122     * @return a new partial copy of this history, until the given date
     123     */
    104124    public History until(final Date untilDate) {
    105125        return filter(
    … …  
    111131                    }
    112132                }
    113                 );
    114     }
    115 
     133            );
     134    }
     135
     136    /**
     137     * Returns a new partial copy of this history, between the given dates
     138     * @param fromDate the starting date
     139     * @param untilDate the end date
     140     * @return a new partial copy of this history, between the given dates
     141     */
    116142    public History between(Date fromDate, Date untilDate) {
    117143        return this.from(fromDate).until(untilDate);
    118144    }
    119145
     146    /**
     147     * Returns a new partial copy of this history, from the given version number
     148     * @param fromVersion the starting version number
     149     * @return a new partial copy of this history, from the given version number
     150     */
    120151    public History from(final long fromVersion) {
    121152        return filter(
    … …  
    127158                    }
    128159                }
    129                 );
    130     }
    131 
     160            );
     161    }
     162
     163    /**
     164     * Returns a new partial copy of this history, to the given version number
     165     * @param untilVersion the ending version number
     166     * @return a new partial copy of this history, to the given version number
     167     */
    132168    public History until(final long untilVersion) {
    133169        return filter(
    … …  
    139175                    }
    140176                }
    141                 );
    142     }
    143 
     177            );
     178    }
     179
     180    /**
     181     * Returns a new partial copy of this history, betwwen the given version numbers
     182     * @param fromVersion the starting version number
     183     * @param untilVersion the ending version number
     184     * @return a new partial copy of this history, between the given version numbers
     185     */
    144186    public History between(long fromVersion, long untilVersion) {
    145187        return this.from(fromVersion).until(untilVersion);
    146188    }
    147189
     190    /**
     191     * Returns a new partial copy of this history, for the given user id
     192     * @param uid the user id
     193     * @return a new partial copy of this history, for the given user id
     194     */
    148195    public History forUserId(final long uid) {
    149196        return filter(
    … …  
    155202                    }
    156203                }
    157                 );
    158     }
    159 
     204            );
     205    }
     206
     207    /**
     208     * Replies the primitive id for this history.
     209     *
     210     * @return the primitive id
     211     * @see #getPrimitiveId
     212     * @see #getType
     213     */
    160214    public long getId() {
    161215        return id;
    … …  
    166220     *
    167221     * @return the primitive id
     222     * @see #getId
    168223     */
    169224    public PrimitiveId getPrimitiveId() {
    … …  
    171226    }
    172227
    173     public boolean contains(long version){
     228    /**
     229     * Determines if this history contains a specific version number.
     230     * @param version the version number to look for
     231     * @return {@code true} if this history contains {@code version}, {@code false} otherwise
     232     */
     233    public boolean contains(long version) {
    174234        for (HistoryOsmPrimitive primitive: versions) {
    175235            if (primitive.matches(id,version))
    … …  
    194254    }
    195255
     256    /**
     257     * Replies the history primitive at given <code>date</code>. null,
     258     * if no such primitive exists.
     259     *
     260     * @param date the date
     261     * @return the history primitive at given <code>date</code>
     262     */
    196263    public HistoryOsmPrimitive getByDate(Date date) {
    197264        History h = sortAscending();
    … …  
    209276    }
    210277
     278    /**
     279     * Replies the history primitive at index <code>idx</code>.
     280     *
     281     * @param idx the index
     282     * @return the history primitive at index <code>idx</code>
     283     * @throws IndexOutOfBoundsException if index out or range
     284     */
    211285    public HistoryOsmPrimitive get(int idx) throws IndexOutOfBoundsException {
    212286        if (idx < 0 || idx >= versions.size())
    213             throw new IndexOutOfBoundsException(MessageFormat.format("Parameter ''{0}'' in range 0..{1} expected. Got ''{2}''.", "idx", versions.size()-1, idx));
     287            throw new IndexOutOfBoundsException(MessageFormat.format(
     288                    "Parameter ''{0}'' in range 0..{1} expected. Got ''{2}''.", "idx", versions.size()-1, idx));
    214289        return versions.get(idx);
    215290    }
    216291
     292    /**
     293     * Replies the earliest entry of this history.
     294     * @return the earliest entry of this history
     295     */
    217296    public HistoryOsmPrimitive getEarliest() {
    218297        if (isEmpty())
    … …  
    221300    }
    222301
     302    /**
     303     * Replies the latest entry of this history.
     304     * @return the latest entry of this history
     305     */
    223306    public HistoryOsmPrimitive getLatest() {
    224307        if (isEmpty())
    … …  
    227310    }
    228311
     312    /**
     313     * Replies the number of versions.
     314     * @return the number of versions
     315     */
    229316    public int getNumVersions() {
    230317        return versions.size();
    … …  
    239326    }
    240327
     328    /**
     329     * Replies the primitive type for this history.
     330     * @return the primitive type
     331     * @see #getId
     332     */
    241333    public OsmPrimitiveType getType() {
    242334        return type;
Note: See TracChangeset for help on using the changeset viewer.