Changeset 5386 in josm


Ignore:
Timestamp:
2012-07-31T21:48:49+02:00 (13 years 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.