Changeset 7395 in josm for trunk/src/org


Ignore:
Timestamp:
2014-08-14T15:33:52+02:00 (10 years ago)
Author:
Don-vip
Message:

javadoc update/cleanup

Location:
trunk/src/org/openstreetmap/josm
Files:
6 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/org/openstreetmap/josm/data/osm/DataSet.java

    r7073 r7395  
    122122    private final Object selectionLock = new Object();
    123123
     124    /**
     125     * Constructs a new {@code DataSet}.
     126     */
    124127    public DataSet() {
    125128        /*
    … …  
    130133    }
    131134
     135    /**
     136     * Returns the lock used for reading.
     137     * @return the lock used for reading
     138     */
    132139    public Lock getReadLock() {
    133140        return lock.readLock();
    … …  
    165172
    166173    /**
    167      * Maintain a list of used tags for autocompletion
     174     * Maintains a list of used tags for autocompletion.
    168175     */
    169176    private AutoCompletionManager autocomplete;
    170177
     178    /**
     179     * Returns the autocompletion manager, which maintains a list of used tags for autocompletion.
     180     * @return the autocompletion manager
     181     */
    171182    public AutoCompletionManager getAutoCompletionManager() {
    172183        if (autocomplete == null) {
    … …  
    200211    }
    201212
     213    /**
     214     * Determines if upload is being discouraged (i.e. this dataset contains private data which should not be uploaded)
     215     * @return {@code true} if upload is being discouraged, {@code false} otherwise
     216     * @see #setUploadDiscouraged
     217     */
    202218    public final boolean isUploadDiscouraged() {
    203219        return uploadDiscouraged;
    204220    }
    205221
     222    /**
     223     * Sets the "upload discouraged" flag.
     224     * @param uploadDiscouraged {@code true} if this dataset contains private data which should not be uploaded
     225     * @see #isUploadDiscouraged
     226     */
    206227    public final void setUploadDiscouraged(boolean uploadDiscouraged) {
    207228        this.uploadDiscouraged = uploadDiscouraged;
    … …  
    213234    private Map<String, String> changeSetTags = new HashMap<>();
    214235
     236    /**
     237     * Replies the set of changeset tags to be applied when or if this is ever uploaded.
     238     * @return the set of changeset tags
     239     * @see #addChangeSetTag
     240     */
    215241    public Map<String, String> getChangeSetTags() {
    216242        return changeSetTags;
    217243    }
    218244
     245    /**
     246     * Adds a new changeset tag.
     247     * @param k Key
     248     * @param v Value
     249     * @see #getChangeSetTags
     250     */
    219251    public void addChangeSetTag(String k, String v) {
    220252        this.changeSetTags.put(k,v);
    … …  
    240272    }
    241273
     274    /**
     275     * Searches for nodes in the given bounding box.
     276     * @param bbox the bounding box
     277     * @return List of nodes in the given bbox. Can be empty but not null
     278     */
    242279    public List<Node> searchNodes(BBox bbox) {
    243280        lock.readLock().lock();
    … …  
    265302    }
    266303
     304    /**
     305     * Searches for ways in the given bounding box.
     306     * @param bbox the bounding box
     307     * @return List of ways in the given bbox. Can be empty but not null
     308     */
    267309    public List<Way> searchWays(BBox bbox) {
    268310        lock.readLock().lock();
    … …  
    288330    }
    289331
     332    /**
     333     * Searches for relations in the given bounding box.
     334     * @param bbox the bounding box
     335     * @return List of relations in the given bbox. Can be empty but not null
     336     */
    290337    public List<Relation> searchRelations(BBox bbox) {
    291338        lock.readLock().lock();
    … …  
    310357
    311358    /**
    312      * @return A collection containing all primitives of the dataset. Data are not ordered
     359     * Returns a collection containing all primitives of the dataset.
     360     * @return A collection containing all primitives of the dataset. Data is not ordered
    313361     */
    314362    public Collection<OsmPrimitive> allPrimitives() {
    … …  
    317365
    318366    /**
    319      * @return A collection containing all not-deleted primitives (except keys).
     367     * Returns a collection containing all not-deleted primitives.
     368     * @return A collection containing all not-deleted primitives.
     369     * @see OsmPrimitive#isDeleted
    320370     */
    321371    public Collection<OsmPrimitive> allNonDeletedPrimitives() {
    … …  
    323373    }
    324374
     375    /**
     376     * Returns a collection containing all not-deleted complete primitives.
     377     * @return A collection containing all not-deleted complete primitives.
     378     * @see OsmPrimitive#isDeleted
     379     * @see OsmPrimitive#isIncomplete
     380     */
    325381    public Collection<OsmPrimitive> allNonDeletedCompletePrimitives() {
    326382        return getPrimitives(OsmPrimitive.nonDeletedCompletePredicate);
    327383    }
    328384
     385    /**
     386     * Returns a collection containing all not-deleted complete physical primitives.
     387     * @return A collection containing all not-deleted complete physical primitives (nodes and ways).
     388     * @see OsmPrimitive#isDeleted
     389     * @see OsmPrimitive#isIncomplete
     390     */
    329391    public Collection<OsmPrimitive> allNonDeletedPhysicalPrimitives() {
    330392        return getPrimitives(OsmPrimitive.nonDeletedPhysicalPredicate);
    331393    }
    332394
     395    /**
     396     * Returns a collection containing all modified primitives.
     397     * @return A collection containing all modified primitives.
     398     * @see OsmPrimitive#isModified
     399     */
    333400    public Collection<OsmPrimitive> allModifiedPrimitives() {
    334401        return getPrimitives(OsmPrimitive.modifiedPredicate);
    … …  
    336403
    337404    /**
    338      * Adds a primitive to the dataset
     405     * Adds a primitive to the dataset.
    339406     *
    340407     * @param primitive the primitive.
    … …  
    414481    private static final Collection<SelectionChangedListener> selListeners = new CopyOnWriteArrayList<>();
    415482
     483    /**
     484     * Adds a new selection listener.
     485     * @param listener The selection listener to add
     486     */
    416487    public static void addSelectionListener(SelectionChangedListener listener) {
    417488        ((CopyOnWriteArrayList<SelectionChangedListener>)selListeners).addIfAbsent(listener);
    418489    }
    419490
     491    /**
     492     * Removes a selection listener.
     493     * @param listener The selection listener to remove
     494     */
    420495    public static void removeSelectionListener(SelectionChangedListener listener) {
    421496        selListeners.remove(listener);
    … …  
    437512    private Collection<OsmPrimitive> selectionSnapshot;
    438513
     514    /**
     515     * Returns selected nodes and ways.
     516     * @return selected nodes and ways
     517     */
    439518    public Collection<OsmPrimitive> getSelectedNodesAndWays() {
    440519        return new FilteredCollection<>(getSelected(), new Predicate<OsmPrimitive>() {
    … …  
    447526
    448527    /**
    449      * returns an unmodifiable collection of *WaySegments* whose virtual
     528     * Returns an unmodifiable collection of *WaySegments* whose virtual
    450529     * nodes should be highlighted. WaySegments are used to avoid having
    451530     * to create a VirtualNode class that wouldn't have much purpose otherwise.
    … …  
    458537
    459538    /**
    460      * returns an unmodifiable collection of WaySegments that should be
    461      * highlighted.
     539     * Returns an unmodifiable collection of WaySegments that should be highlighted.
    462540     *
    463541     * @return unmodifiable collection of WaySegments
    … …  
    495573
    496574    /**
    497      * Return selected nodes.
     575     * Returns selected nodes.
     576     * @return selected nodes
    498577     */
    499578    public Collection<Node> getSelectedNodes() {
    … …  
    502581
    503582    /**
    504      * Return selected ways.
     583     * Returns selected ways.
     584     * @return selected ways
    505585     */
    506586    public Collection<Way> getSelectedWays() {
    … …  
    509589
    510590    /**
    511      * Return selected relations.
     591     * Returns selected relations.
     592     * @return selected relations
    512593     */
    513594    public Collection<Relation> getSelectedRelations() {
    … …  
    516597
    517598    /**
     599     * Determines whether the selection is empty or not
    518600     * @return whether the selection is empty or not
    519601     */
    … …  
    522604    }
    523605
     606    /**
     607     * Determines whether the given primitive is selected or not
     608     * @param osm the primitive
     609     * @return whether {@code osm} is selected or not
     610     */
    524611    public boolean isSelected(OsmPrimitive osm) {
    525612        return selectedPrimitives.contains(osm);
    526613    }
    527614
     615    /**
     616     * Toggles the selected state of the given collection of primitives.
     617     * @param osm The primitives to toggle
     618     */
    528619    public void toggleSelected(Collection<? extends PrimitiveId> osm) {
    529620        boolean changed = false;
    … …  
    540631        }
    541632    }
     633
     634    /**
     635     * Toggles the selected state of the given collection of primitives.
     636     * @param osm The primitives to toggle
     637     */
    542638    public void toggleSelected(PrimitiveId... osm) {
    543639        toggleSelected(Arrays.asList(osm));
    544640    }
     641
    545642    private boolean __toggleSelected(PrimitiveId primitiveId) {
    546643        OsmPrimitive primitive = getPrimitiveByIdChecked(primitiveId);
    … …  
    617714    }
    618715
     716    /**
     717     * Sets the current selection to the primitives in <code>osm</code>
     718     * and notifies all {@link SelectionChangedListener}.
     719     *
     720     * @param osm the primitives to set
     721     */
    619722    public void setSelected(PrimitiveId... osm) {
    620723        if (osm.length == 1 && osm[0] == null) {
    … …  
    627730
    628731    /**
    629      * Adds   the primitives in <code>selection</code> to the current selection
     732     * Adds the primitives in <code>selection</code> to the current selection
    630733     * and notifies all {@link SelectionChangedListener}.
    631734     *
    … …  
    636739    }
    637740
     741    /**
     742     * Adds the primitives in <code>osm</code> to the current selection
     743     * and notifies all {@link SelectionChangedListener}.
     744     *
     745     * @param osm the primitives to add
     746     */
    638747    public void addSelected(PrimitiveId... osm) {
    639748        addSelected(Arrays.asList(osm));
    … …  
    682791
    683792    /**
    684      * Remove the selection from every value in the collection.
     793     * Removes the selection from every value in the collection.
    685794     * @param osm The collection of ids to remove the selection from.
    686795     */
    … …  
    688797        clearSelection(Arrays.asList(osm));
    689798    }
     799
     800    /**
     801     * Removes the selection from every value in the collection.
     802     * @param list The collection of ids to remove the selection from.
     803     */
    690804    public void clearSelection(Collection<? extends PrimitiveId> list) {
    691805        boolean changed = false;
    … …  
    705819        }
    706820    }
     821
     822    /**
     823     * Clears the current selection.
     824     */
    707825    public void clearSelection() {
    708826        if (!selectedPrimitives.isEmpty()) {
    … …  
    715833    }
    716834
    717     @Override public DataSet clone() {
     835    @Override
     836    public DataSet clone() {
    718837        getReadLock().lock();
    719838        try {
    … …  
    776895
    777896    /**
    778      * returns a  primitive with a given id from the data set. null, if no such primitive
    779      * exists
     897     * Returns a primitive with a given id from the data set. null, if no such primitive exists
    780898     *
    781899     * @param id  uniqueId of the primitive. Might be &lt; 0 for newly created primitives
    … …  
    788906    }
    789907
     908    /**
     909     * Returns a primitive with a given id from the data set. null, if no such primitive exists
     910     *
     911     * @param primitiveId type and uniqueId of the primitive. Might be &lt; 0 for newly created primitives
     912     * @return the primitive
     913     */
    790914    public OsmPrimitive getPrimitiveById(PrimitiveId primitiveId) {
    791915        return primitivesMap.get(primitiveId);
    … …  
    9491073    }
    9501074
     1075    /**
     1076     * Adds a new data set listener.
     1077     * @param dsl The data set listener to add
     1078     */
    9511079    public void addDataSetListener(DataSetListener dsl) {
    9521080        listeners.addIfAbsent(dsl);
    9531081    }
    9541082
     1083    /**
     1084     * Removes a data set listener.
     1085     * @param dsl The data set listener to remove
     1086     */
    9551087    public void removeDataSetListener(DataSetListener dsl) {
    9561088        listeners.remove(dsl);
    … …  
    10781210    }
    10791211
     1212    /**
     1213     * Cleanups all deleted primitives (really delete them from the dataset).
     1214     */
    10801215    public void cleanupDeletedPrimitives() {
    10811216        beginUpdate();
    … …  
    11691304
    11701305    /**
    1171      * Moves all primitives and datasources from DataSet "from" to this DataSet
     1306     * Moves all primitives and datasources from DataSet "from" to this DataSet.
    11721307     * @param from The source DataSet
    11731308     */
    … …  
    11771312
    11781313    /**
    1179      * Moves all primitives and datasources from DataSet "from" to this DataSet
     1314     * Moves all primitives and datasources from DataSet "from" to this DataSet.
    11801315     * @param from The source DataSet
     1316     * @param progressMonitor The progress monitor
    11811317     */
    11821318    public void mergeFrom(DataSet from, ProgressMonitor progressMonitor) {

  • trunk/src/org/openstreetmap/josm/data/osm/MultipolygonBuilder.java

    r7392 r7395  
    285285                } else if (intersection == PolygonIntersection.SECOND_INSIDE_FIRST) {
    286286                    innerCandidates.add(innerWay);
    287                 }
    288                 else if (intersection == PolygonIntersection.CROSSING) {
     287                } else if (intersection == PolygonIntersection.CROSSING) {
    289288                    //ways intersect
    290289                    return null;

  • trunk/src/org/openstreetmap/josm/data/osm/visitor/paint/relations/Multipolygon.java

    r7295 r7395  
    2828import org.openstreetmap.josm.data.osm.visitor.paint.relations.Multipolygon.PolyData.Intersection;
    2929
     30/**
     31 * Multipolygon data used to represent complex areas, see <a href="https://wiki.openstreetmap.org/wiki/Relation:multipolygon">wiki</a>.
     32 * @since 2788
     33 */
    3034public class Multipolygon {
     35
    3136    /** preference key for a collection of roles which indicate that the respective member belongs to an
    3237     * <em>outer</em> polygon. Default is <tt>outer</tt>.
    3338     */
    3439    public static final String PREF_KEY_OUTER_ROLES = "mappaint.multipolygon.outer.roles";
     40
    3541    /** preference key for collection of role prefixes which indicate that the respective
    3642     *  member belongs to an <em>outer</em> polygon. Default is empty.
    3743     */
    3844    public static final String PREF_KEY_OUTER_ROLE_PREFIXES = "mappaint.multipolygon.outer.role-prefixes";
     45
    3946    /** preference key for a collection of roles which indicate that the respective member belongs to an
    4047     * <em>inner</em> polygon. Default is <tt>inner</tt>.
    4148     */
    4249    public static final String PREF_KEY_INNER_ROLES = "mappaint.multipolygon.inner.roles";
     50
    4351    /** preference key for collection of role prefixes which indicate that the respective
    4452     *  member belongs to an <em>inner</em> polygon. Default is empty.
    … …  
    5361     * <p>The decision is taken based on preference settings, see the four preference keys
    5462     * above.</p>
    55      *
    56      */
    57     private static class MultipolygonRoleMatcher implements PreferenceChangedListener{
     63     */
     64    private static class MultipolygonRoleMatcher implements PreferenceChangedListener {
    5865        private final List<String> outerExactRoles = new ArrayList<>();
    5966        private final List<String> outerRolePrefixes = new ArrayList<>();
    … …  
    7077        }
    7178
    72         private void setNormalized(Collection<String> literals, List<String> target){
     79        private void setNormalized(Collection<String> literals, List<String> target) {
    7380            target.clear();
    74             for(String l: literals) {
     81            for (String l: literals) {
    7582                if (l == null) {
    7683                    continue;
    … …  
    115122        }
    116123
    117         public boolean isOuterRole(String role){
     124        public boolean isOuterRole(String role) {
    118125            if (role == null) return false;
    119126            for (String candidate: outerExactRoles) {
    … …  
    126133        }
    127134
    128         public boolean isInnerRole(String role){
     135        public boolean isInnerRole(String role) {
    129136            if (role == null) return false;
    130137            for (String candidate: innerExactRoles) {
    … …  
    139146
    140147    /*
    141      * Init a private global matcher object which will listen to preference
    142      * changes.
     148     * Init a private global matcher object which will listen to preference changes.
    143149     */
    144150    private static MultipolygonRoleMatcher roleMatcher;
    … …  
    493499            }
    494500
    495             if (nodes == null) {
     501            if (nodes == null && w != null) {
    496502                nodes = w.getNodes();
    497503                wayIds.add(w.getUniqueId());
    … …  
    568574    }
    569575
     576    /**
     577     * Replies the list of outer ways.
     578     * @return the list of outer ways
     579     */
    570580    public List<Way> getOuterWays() {
    571581        return outerWays;
    572582    }
    573583
     584    /**
     585     * Replies the list of inner ways.
     586     * @return the list of inner ways
     587     */
    574588    public List<Way> getInnerWays() {
    575589        return innerWays;

  • trunk/src/org/openstreetmap/josm/data/osm/visitor/paint/relations/MultipolygonCache.java

    r7005 r7395  
    3535
    3636/**
    37  * A memory cache for Multipolygon objects.
     37 * A memory cache for {@link Multipolygon} objects.
    3838 * @since 4623
    3939 */
    4040public final class MultipolygonCache implements DataSetListener, LayerChangeListener, ProjectionChangeListener, SelectionChangedListener {
    4141
    42     private static final MultipolygonCache INSTANCE = new MultipolygonCache(); 
    43    
     42    private static final MultipolygonCache INSTANCE = new MultipolygonCache();
     43
    4444    private final Map<NavigatableComponent, Map<DataSet, Map<Relation, Multipolygon>>> cache;
    45    
     45
    4646    private final Collection<PolyData> selectedPolyData;
    47    
     47
    4848    private MultipolygonCache() {
    4949        this.cache = new HashMap<>();
    … …  
    6262    }
    6363
     64    /**
     65     * Gets a multipolygon from cache.
     66     * @param nc The navigatable component
     67     * @param r The multipolygon relation
     68     * @return A multipolygon object for the given relation, or {@code null}
     69     */
    6470    public final Multipolygon get(NavigatableComponent nc, Relation r) {
    6571        return get(nc, r, false);
    6672    }
    6773
     74    /**
     75     * Gets a multipolygon from cache.
     76     * @param nc The navigatable component
     77     * @param r The multipolygon relation
     78     * @param forceRefresh if {@code true}, a new object will be created even of present in cache
     79     * @return A multipolygon object for the given relation, or {@code null}
     80     */
    6881    public final Multipolygon get(NavigatableComponent nc, Relation r, boolean forceRefresh) {
    6982        Multipolygon multipolygon = null;
    … …  
    89102        return multipolygon;
    90103    }
    91    
     104
     105    /**
     106     * Clears the cache for the given navigatable component.
     107     * @param nc the navigatable component
     108     */
    92109    public final void clear(NavigatableComponent nc) {
    93110        Map<DataSet, Map<Relation, Multipolygon>> map = cache.remove(nc);
    … …  
    98115    }
    99116
     117    /**
     118     * Clears the cache for the given dataset.
     119     * @param ds the data set
     120     */
    100121    public final void clear(DataSet ds) {
    101122        for (Map<DataSet, Map<Relation, Multipolygon>> map1 : cache.values()) {
    … …  
    108129    }
    109130
     131    /**
     132     * Clears the whole cache.
     133     */
    110134    public final void clear() {
    111135        cache.clear();
    112136    }
    113    
     137
    114138    private final Collection<Map<Relation, Multipolygon>> getMapsFor(DataSet ds) {
    115139        List<Map<Relation, Multipolygon>> result = new ArrayList<>();
    … …  
    122146        return result;
    123147    }
    124    
     148
    125149    private static final boolean isMultipolygon(OsmPrimitive p) {
    126150        return p instanceof Relation && ((Relation) p).isMultipolygon();
    127151    }
    128    
     152
    129153    private final void updateMultipolygonsReferringTo(AbstractDatasetChangedEvent event) {
    130154        updateMultipolygonsReferringTo(event, event.getPrimitives(), event.getDataset());
    … …  
    135159        updateMultipolygonsReferringTo(event, primitives, ds, null);
    136160    }
    137    
     161
    138162    private final Collection<Map<Relation, Multipolygon>> updateMultipolygonsReferringTo(
    139             AbstractDatasetChangedEvent event, Collection<? extends OsmPrimitive> primitives, 
     163            AbstractDatasetChangedEvent event, Collection<? extends OsmPrimitive> primitives,
    140164            DataSet ds, Collection<Map<Relation, Multipolygon>> initialMaps) {
    141165        Collection<Map<Relation, Multipolygon>> maps = initialMaps;
    … …  
    147171                    }
    148172                    processEvent(event, (Relation) p, maps);
    149                    
     173
    150174                } else if (p instanceof Way && p.getDataSet() != null) {
    151175                    for (OsmPrimitive ref : p.getReferrers()) {
    … …  
    164188        return maps;
    165189    }
    166    
     190
    167191    private final void processEvent(AbstractDatasetChangedEvent event, Relation r, Collection<Map<Relation, Multipolygon>> maps) {
    168192        if (event instanceof NodeMovedEvent || event instanceof WayNodesChangedEvent) {
    … …  
    173197            }
    174198        } else {
    175             // Default (non-optimal) action: remove multipolygon from cache 
     199            // Default (non-optimal) action: remove multipolygon from cache
    176200            removeMultipolygonFrom(r, maps);
    177201        }
    178202    }
    179    
     203
    180204    private final void dispatchEvent(AbstractDatasetChangedEvent event, Relation r, Collection<Map<Relation, Multipolygon>> maps) {
    181205        for (Map<Relation, Multipolygon> map : maps) {
    … …  
    192216        }
    193217    }
    194    
     218
    195219    private final void removeMultipolygonFrom(Relation r, Collection<Map<Relation, Multipolygon>> maps) {
    196220        for (Map<Relation, Multipolygon> map : maps) {
    … …  
    236260    @Override
    237261    public void dataChanged(DataChangedEvent event) {
    238         // Do not call updateMultipolygonsReferringTo as getPrimitives() 
     262        // Do not call updateMultipolygonsReferringTo as getPrimitives()
    239263        // can return all the data set primitives for this event
    240264        Collection<Map<Relation, Multipolygon>> maps = null;
    … …  
    280304    @Override
    281305    public void selectionChanged(Collection<? extends OsmPrimitive> newSelection) {
    282        
     306
    283307        for (Iterator<PolyData> it = selectedPolyData.iterator(); it.hasNext();) {
    284308            it.next().selected = false;
    285309            it.remove();
    286310        }
    287        
     311
    288312        DataSet ds = null;
    289313        Collection<Map<Relation, Multipolygon>> maps = null;

  • trunk/src/org/openstreetmap/josm/tools/FilteredCollection.java

    r3802 r7395  
    77 * The same as SubclassFilteredCollection, but does not restrict the type
    88 * of the collection to a certain subclass.
     9 * @param <T> element type of the underlying collection
     10 * @since 3802
    911 */
    1012public class FilteredCollection<T> extends SubclassFilteredCollection<T, T> {
    1113
     14    /**
     15     * Constructs a new {@code FilteredCollection}.
     16     * @param collection The base collection to filter
     17     * @param predicate The predicate to use as filter
     18     */
    1219    public FilteredCollection(Collection<? extends T> collection, Predicate<? super T> predicate) {
    1320        super(collection, predicate);
    1421    }
    15 
    1622}

  • trunk/src/org/openstreetmap/josm/tools/SubclassFilteredCollection.java

    r6792 r7395  
    1414 * @param <T> element type of filtered collection (and subclass of S). The predicate
    1515 *      must accept only objects of type T.
     16 * @since 3147
    1617 */
    1718public class SubclassFilteredCollection<S, T extends S> extends AbstractCollection<T> {
    … …  
    6364    }
    6465
     66    /**
     67     * Constructs a new {@code SubclassFilteredCollection}.
     68     * @param collection The base collection to filter
     69     * @param predicate The predicate to use as filter
     70     */
    6571    public SubclassFilteredCollection(Collection<? extends S> collection, Predicate<? super S> predicate) {
    6672        this.collection = collection;
    … …  
    9096        return !iterator().hasNext();
    9197    }
    92 
    9398}
Note: See TracChangeset for help on using the changeset viewer.