Changeset 5386 in josm


Ignore:
Timestamp:
Jul 31, 2012 9:48:49 PM (10 months ago)
Author:
Don-vip
Message:

see #7914 - Introduce OsmApi.MAX_DOWNLOAD_THREADS and improve javadoc in some classes of josm.io package

Location:
trunk/src/org/openstreetmap/josm/io
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/org/openstreetmap/josm/io/OsmApi.java

    r5266 r5386  
    2525import java.util.HashMap; 
    2626 
    27 import javax.xml.parsers.ParserConfigurationException; 
    2827import javax.xml.parsers.SAXParserFactory; 
    2928 
    … …  
    4342 
    4443/** 
    45  * Class that encapsulates the communications with the OSM API. 
     44 * Class that encapsulates the communications with the <a href="http://wiki.openstreetmap.org/wiki/API_v0.6">OSM API</a>.<br/><br/> 
    4645 * 
    47  * All interaction with the server-side OSM API should go through this class. 
     46 * All interaction with the server-side OSM API should go through this class.<br/><br/> 
    4847 * 
    4948 * It is conceivable to extract this into an interface later and create various 
    … …  
    5251 */ 
    5352public class OsmApi extends OsmConnection { 
    54     /** max number of retries to send a request in case of HTTP 500 errors or timeouts */ 
     53     
     54    /**  
     55     * Maximum number of retries to send a request in case of HTTP 500 errors or timeouts  
     56     */ 
    5557    static public final int DEFAULT_MAX_NUM_RETRIES = 5; 
    5658 
    57     /** the collection of instantiated OSM APIs */ 
     59    /** 
     60     * Maximum number of concurrent download threads, imposed by  
     61     * <a href="http://wiki.openstreetmap.org/wiki/API_usage_policy#Technical_Usage_Requirements"> 
     62     * OSM API usage policy.</a> 
     63     */ 
     64    static public final int MAX_DOWNLOAD_THREADS = 2; 
     65 
     66    // The collection of instantiated OSM APIs 
    5867    private static HashMap<String, OsmApi> instances = new HashMap<String, OsmApi>(); 
    5968 
    6069    /** 
    61      * replies the {@link OsmApi} for a given server URL 
     70     * Replies the {@link OsmApi} for a given server URL 
    6271     * 
    6372     * @param serverUrl  the server URL 
    … …  
    7483        return api; 
    7584    } 
    76     /** 
    77      * replies the {@link OsmApi} for the URL given by the preference <code>osm-server.url</code> 
     85     
     86    /** 
     87     * Replies the {@link OsmApi} for the URL given by the preference <code>osm-server.url</code> 
    7888     * 
    7989     * @return the OsmApi 
    80      * @exception IllegalStateException thrown, if the preference <code>osm-server.url</code> is not set 
     90     * @throws IllegalStateException thrown, if the preference <code>osm-server.url</code> is not set 
    8191     * 
    8292     */ 
    … …  
    129139     * 
    130140     * @param serverUrl the server URL. Must not be null 
    131      * @exception IllegalArgumentException thrown, if serverUrl is null 
     141     * @throws IllegalArgumentException thrown, if serverUrl is null 
    132142     */ 
    133143    protected OsmApi(String serverUrl)  { 
    … …  
    137147 
    138148    /** 
    139      * Returns the OSM protocol version we use to talk to the server. 
     149     * Replies the OSM protocol version we use to talk to the server. 
    140150     * @return protocol version, or null if not yet negotiated. 
    141151     */ 
    … …  
    144154    } 
    145155 
     156    /** 
     157     * Replies the host name of the server URL. 
     158     * @return the host name of the server URL, or null if the server URL is malformed. 
     159     */ 
    146160    public String getHost() { 
    147161        String host = null; 
    … …  
    163177            this.fastFail = fastFail; 
    164178        } 
     179         
    165180        @Override 
    166181        protected byte[] updateData() throws OsmTransferException { 
    167             String s = sendRequest("GET", "capabilities", null, monitor, false, fastFail); 
    168             return s.getBytes(); 
    169         } 
    170     } 
    171  
    172     public void initialize(ProgressMonitor monitor) throws OsmApiInitializationException, OsmTransferCanceledException { 
     182            return sendRequest("GET", "capabilities", null, monitor, false, fastFail).getBytes(); 
     183        } 
     184    } 
     185 
     186    /** 
     187     * Initializes this component by negotiating a protocol version with the server. 
     188     *  
     189     * @param monitor the progress monitor 
     190     * @throws OsmTransferCanceledException If the initialisation has been cancelled by user. 
     191     * @throws OsmApiInitializationException If any other exception occurs. Use getCause() to get the original exception. 
     192     */ 
     193    public void initialize(ProgressMonitor monitor) throws OsmTransferCanceledException, OsmApiInitializationException { 
    173194        initialize(monitor, false); 
    174195    } 
    175     /** 
    176      * Initializes this component by negotiating a protocol version with the server. 
    177      * 
    178      * @param monitor 
     196     
     197    /** 
     198     * Initializes this component by negotiating a protocol version with the server, with the ability to control the timeout.  
     199     * 
     200     * @param monitor the progress monitor 
    179201     * @param fastFail true to request quick initialisation with a small timeout (more likely to throw exception) 
    180      * @exception OsmApiInitializationException thrown, if an exception occurs 
    181      */ 
    182     public void initialize(ProgressMonitor monitor, boolean fastFail) throws OsmApiInitializationException, OsmTransferCanceledException { 
     202     * @throws OsmTransferCanceledException If the initialisation has been cancelled by user. 
     203     * @throws OsmApiInitializationException If any other exception occurs. Use getCause() to get the original exception. 
     204     */ 
     205    public void initialize(ProgressMonitor monitor, boolean fastFail) throws OsmTransferCanceledException, OsmApiInitializationException { 
    183206        if (initialized) 
    184207            return; 
    … …  
    215238             * to load the layers in the first place becuase they would have 
    216239             * been disabled! */ 
    217             if (Main.main.isDisplayingMapView()) { 
     240            if (Main.isDisplayingMapView()) { 
    218241                for (Layer l : Main.map.mapView.getLayersOfType(ImageryLayer.class)) { 
    219242                    if (((ImageryLayer) l).getInfo().isBlacklisted()) { 
    … …  
    224247            } 
    225248 
    226         } catch(IOException e) { 
    227             initialized = false; 
    228             throw new OsmApiInitializationException(e); 
    229         } catch(SAXException e) { 
    230             initialized = false; 
    231             throw new OsmApiInitializationException(e); 
    232         } catch(ParserConfigurationException e) { 
    233             initialized = false; 
    234             throw new OsmApiInitializationException(e); 
    235         } catch(OsmTransferCanceledException e){ 
     249        } catch (OsmTransferCanceledException e) { 
    236250            throw e; 
    237         } catch(OsmTransferException e) { 
     251        } catch (Exception e) { 
    238252            initialized = false; 
    239253            throw new OsmApiInitializationException(e); 
    … …  
    299313     * 
    300314     * @param osm the primitive 
     315     * @param monitor the progress monitor 
    301316     * @throws OsmTransferException if something goes wrong 
    302317     */ 
    … …  
    339354     * Deletes an OSM primitive on the server. 
    340355     * @param osm the primitive 
     356     * @param monitor the progress monitor 
    341357     * @throws OsmTransferException if something goes wrong 
    342358     */ 
    … …  
    535551    } 
    536552 
    537     private String sendRequest(String requestMethod, String urlSuffix,String requestBody, ProgressMonitor monitor, boolean doAuth) throws OsmTransferException { 
    538         return sendRequest(requestMethod, urlSuffix, requestBody, monitor, doAuth, false); 
    539     } 
    540  
    541553    /** 
    542554     * Generic method for sending requests to the OSM API. 
    … …  
    555567     * 
    556568     * @return the body of the HTTP response, if and only if the response code was "200 OK". 
    557      * @exception OsmTransferException if the HTTP return code was not 200 (and retries have 
     569     * @throws OsmTransferException if the HTTP return code was not 200 (and retries have 
    558570     *    been exhausted), or rewrapping a Java exception. 
    559571     */ 
    … …  
    684696 
    685697    /** 
    686      * returns the API capabilities; null, if the API is not initialized yet 
    687      * 
    688      * @return the API capabilities 
     698     * Replies the API capabilities 
     699     * 
     700     * @return the API capabilities, or null, if the API is not initialized yet 
    689701     */ 
    690702    public Capabilities getCapabilities() { 
    … …  
    704716            throw new OsmTransferException(tr("ID of current changeset > 0 required. Current ID is {0}.", changeset.getId())); 
    705717    } 
     718     
    706719    /** 
    707720     * Replies the changeset data uploads are currently directed to 

  • trunk/src/org/openstreetmap/josm/io/OsmApiException.java

    r3511 r5386  
    33import static org.openstreetmap.josm.tools.I18n.tr; 
    44 
     5/** 
     6 * Exception thrown when a communication error occurs when accessing the <a href="http://wiki.openstreetmap.org/wiki/API_v0.6">OSM API</a>. 
     7 * @see OsmApi 
     8 */ 
    59public class OsmApiException extends OsmTransferException { 
    610 
    … …  
    1014    private String accessedUrl; 
    1115 
    12     public OsmApiException() { 
    13         super(); 
    14     } 
    15  
     16    /** 
     17     * Constructs an {@code OsmApiException} with the specified response code, error header and error body 
     18     * @param responseCode The HTTP response code replied by the OSM server. See {@link java.net.HttpURLConnection HttpURLConnection} for predefined HTTP response code values 
     19     * @param errorHeader The error header, as transmitted in the {@code Error} field of the HTTP response header 
     20     * @param errorBody The error body, as transmitted in the HTTP response body 
     21     */ 
    1622    public OsmApiException(int responseCode, String errorHeader, String errorBody) { 
    1723        this.responseCode = responseCode; 
    … …  
    2026    } 
    2127 
     28    /** 
     29     * Constructs an {@code OsmApiException} with the specified detail message. 
     30     * The cause is not initialized, and may subsequently be initialized by a call to {@link #initCause}. 
     31     * 
     32     * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) 
     33     */ 
     34    public OsmApiException(String message) { 
     35        super(message); 
     36    } 
     37 
     38    /** 
     39     * Constructs an {@code OsmApiException} with the specified cause and a detail message of  
     40     * <tt>(cause==null ? null : cause.toString())</tt>  
     41     * (which typically contains the class and detail message of <tt>cause</tt>). 
     42     * 
     43     * @param cause the cause (which is saved for later retrieval by the {@link #getCause} method).  
     44     *              A <tt>null</tt> value is permitted, and indicates that the cause is nonexistent or unknown. 
     45     */ 
     46    public OsmApiException(Throwable cause) { 
     47        super(cause); 
     48    } 
     49 
     50    /** 
     51     * Constructs an {@code OsmApiException} with the specified detail message and cause. 
     52     * 
     53     * <p> Note that the detail message associated with {@code cause} is <i>not</i> automatically incorporated  
     54     * into this exception's detail message. 
     55     * 
     56     * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) 
     57     * @param cause   The cause (which is saved for later retrieval by the {@link #getCause} method). 
     58     *                A null value is permitted, and indicates that the cause is nonexistent or unknown. 
     59     * 
     60     */ 
    2261    public OsmApiException(String message, Throwable cause) { 
    2362        super(message, cause); 
    2463    } 
    2564 
    26     public OsmApiException(String message) { 
    27         super(message); 
    28     } 
    29  
    30     public OsmApiException(Throwable cause) { 
    31         super(cause); 
    32     } 
    33  
     65    /** 
     66     * Replies the HTTP response code. 
     67     * @return The HTTP response code replied by the OSM server. Refer to <a href="http://wiki.openstreetmap.org/wiki/API_v0.6">OSM API</a> to see the list of response codes returned by the API for each call. 
     68     */ 
    3469    public int getResponseCode() { 
    3570        return responseCode; 
    3671    } 
    3772 
     73    /** 
     74     * Sets the HTTP response code. 
     75     * @param responseCode The HTTP response code replied by the OSM server. See {@link java.net.HttpURLConnection HttpURLConnection} for predefined HTTP response code values 
     76     */ 
    3877    public void setResponseCode(int responseCode) { 
    3978        this.responseCode = responseCode; 
    4079    } 
    4180 
     81    /** 
     82     * Replies the error header. 
     83     * @return the error header, as transmitted in the {@code Error} field of the HTTP response header 
     84     */ 
    4285    public String getErrorHeader() { 
    4386        return errorHeader; 
    4487    } 
    4588 
     89    /** 
     90     * Sets the error header. 
     91     * @param errorHeader the error header, as transmitted in the {@code Error} field of the HTTP response header 
     92     */ 
    4693    public void setErrorHeader(String errorHeader) { 
    4794        this.errorHeader = errorHeader; 
    4895    } 
    4996 
     97    /** 
     98     * Replies the error body. 
     99     * @return The error body, as transmitted in the HTTP response body 
     100     */ 
    50101    public String getErrorBody() { 
    51102        return errorBody; 
    52103    } 
    53104 
     105    /** 
     106     * Sets the error body. 
     107     * @param errorBody The error body, as transmitted in the HTTP response body 
     108     */ 
    54109    public void setErrorBody(String errorBody) { 
    55110        this.errorBody = errorBody; 
    … …  
    73128        } 
    74129        catch (Exception e) { 
     130            // Ignored 
    75131        } 
    76132        try 
    … …  
    84140        } 
    85141        catch (Exception e) { 
     142            // Ignored 
    86143        } 
    87144        return sb.toString(); 
    … …  
    108165    } 
    109166 
     167    /** 
     168     * Sets the complete URL accessed when this error occured. This is distinct from the one set with {@link #setUrl}, which is generally only the base URL of the server. 
     169     * @param url the complete URL accessed when this error occured. 
     170     */ 
    110171    public void setAccessedUrl(String url) { 
    111172        this.accessedUrl = url; 
    112173    } 
    113174 
     175    /** 
     176     * Replies the complete URL accessed when this error occured. This is distinct from the one returned by {@link #getUrl}, which is generally only the base URL of the server. 
     177     * @return the complete URL accessed when this error occured. 
     178     */ 
    114179    public String getAccessedUrl() { 
    115180        return accessedUrl; 

  • trunk/src/org/openstreetmap/josm/io/OsmApiInitializationException.java

    r3083 r5386  
    22package org.openstreetmap.josm.io; 
    33 
     4/** 
     5 * Exception thrown when a communication error occured with the OSM server during API initialization. 
     6 * @see OsmApi#initialize 
     7 */ 
    48public class OsmApiInitializationException extends OsmTransferException { 
    59 
    6     public OsmApiInitializationException() { 
    7         super(); 
    8     } 
    9  
    10     public OsmApiInitializationException(String message, Throwable cause) { 
    11         super(message, cause); 
    12     } 
    13  
     10    /** 
     11     * Constructs an {@code OsmApiInitializationException} with the specified detail message. 
     12     * The cause is not initialized, and may subsequently be initialized by a call to {@link #initCause}. 
     13     * 
     14     * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) 
     15     */ 
    1416    public OsmApiInitializationException(String message) { 
    1517        super(message); 
    1618    } 
    1719 
     20    /** 
     21     * Constructs an {@code OsmApiInitializationException} with the specified cause and a detail message of  
     22     * <tt>(cause==null ? null : cause.toString())</tt>  
     23     * (which typically contains the class and detail message of <tt>cause</tt>). 
     24     * 
     25     * @param cause the cause (which is saved for later retrieval by the {@link #getCause} method).  
     26     *              A <tt>null</tt> value is permitted, and indicates that the cause is nonexistent or unknown. 
     27     */ 
    1828    public OsmApiInitializationException(Throwable cause) { 
    1929        super(cause); 
    2030    } 
     31 
     32    /** 
     33     * Constructs an {@code OsmApiInitializationException} with the specified detail message and cause. 
     34     * 
     35     * <p> Note that the detail message associated with {@code cause} is <i>not</i> automatically incorporated  
     36     * into this exception's detail message. 
     37     * 
     38     * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) 
     39     * @param cause   The cause (which is saved for later retrieval by the {@link #getCause} method). 
     40     *                A null value is permitted, and indicates that the cause is nonexistent or unknown. 
     41     * 
     42     */ 
     43    public OsmApiInitializationException(String message, Throwable cause) { 
     44        super(message, cause); 
     45    } 
    2146} 

  • trunk/src/org/openstreetmap/josm/io/OsmTransferCanceledException.java

    r4310 r5386  
    22package org.openstreetmap.josm.io; 
    33 
     4/** 
     5 * Exception thrown when a communication with the OSM server has been cancelled by the user. 
     6 */ 
    47public class OsmTransferCanceledException extends OsmTransferException { 
    58 

  • trunk/src/org/openstreetmap/josm/io/OsmTransferException.java

    r3255 r5386  
    22package org.openstreetmap.josm.io; 
    33 
     4/** 
     5 * Exception thrown when a communication error with the OSM server occurs. 
     6 */ 
    47public class OsmTransferException extends Exception { 
    58 
    69    private String url = OsmApi.getOsmApi().getBaseUrl(); 
    710 
     11    /** 
     12     * Constructs an {@code OsmTransferException} with {@code null} as its error detail message. 
     13     * The cause is not initialized, and may subsequently be initialized by a call to {@link #initCause}. 
     14     */ 
    815    public OsmTransferException() { 
    916    } 
    1017 
     18    /** 
     19     * Constructs an {@code OsmTransferException} with the specified detail message. 
     20     * The cause is not initialized, and may subsequently be initialized by a call to {@link #initCause}. 
     21     * 
     22     * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) 
     23     */ 
    1124    public OsmTransferException(String message) { 
    1225        super(message); 
    1326    } 
    1427 
     28    /** 
     29     * Constructs an {@code OsmTransferException} with the specified cause and a detail message of  
     30     * <tt>(cause==null ? null : cause.toString())</tt>  
     31     * (which typically contains the class and detail message of <tt>cause</tt>). 
     32     * 
     33     * @param cause the cause (which is saved for later retrieval by the {@link #getCause} method).  
     34     *              A <tt>null</tt> value is permitted, and indicates that the cause is nonexistent or unknown. 
     35     */ 
    1536    public OsmTransferException(Throwable cause) { 
    1637        super(cause); 
    1738    } 
    1839 
     40    /** 
     41     * Constructs an {@code OsmTransferException} with the specified detail message and cause. 
     42     * 
     43     * <p> Note that the detail message associated with {@code cause} is <i>not</i> automatically incorporated  
     44     * into this exception's detail message. 
     45     * 
     46     * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) 
     47     * @param cause   The cause (which is saved for later retrieval by the {@link #getCause} method). 
     48     *                A null value is permitted, and indicates that the cause is nonexistent or unknown. 
     49     * 
     50     */ 
    1951    public OsmTransferException(String message, Throwable cause) { 
    2052        super(message, cause); 
    2153    } 
    2254 
     55    /** 
     56     * Sets the URL related to this error. 
     57     * @param url the URL related to this error (which is saved for later retrieval by the {@link #getUrl} method). 
     58     */ 
    2359    public void setUrl(String url) { 
    2460        this.url = url; 
    … …  
    2662 
    2763    /** 
    28      * 
    29      * @return Api base url or url set using setUrl method 
     64     * Gets the URL related to this error. 
     65     * @return API base URL or URL set using the {@link #setUrl} method 
    3066     */ 
    3167    public String getUrl() { 
    3268        return url; 
    3369    } 
    34  
    3570} 
Note: See TracChangeset for help on using the changeset viewer.