osm-server.url
+
+ /**
+ * Replies the {@link OsmApi} for the URL given by the preference osm-server.url
*
* @return the OsmApi
- * @exception IllegalStateException thrown, if the preference osm-server.url is not set
+ * @throws IllegalStateException thrown, if the preference osm-server.url is not set
*
*/
@@ -129,5 +139,5 @@
*
* @param serverUrl the server URL. Must not be null
- * @exception IllegalArgumentException thrown, if serverUrl is null
+ * @throws IllegalArgumentException thrown, if serverUrl is null
*/
protected OsmApi(String serverUrl) {
@@ -137,5 +147,5 @@
/**
- * Returns the OSM protocol version we use to talk to the server.
+ * Replies the OSM protocol version we use to talk to the server.
* @return protocol version, or null if not yet negotiated.
*/
@@ -144,4 +154,8 @@
}
+ /**
+ * Replies the host name of the server URL.
+ * @return the host name of the server URL, or null if the server URL is malformed.
+ */
public String getHost() {
String host = null;
@@ -163,22 +177,31 @@
this.fastFail = fastFail;
}
+
@Override
protected byte[] updateData() throws OsmTransferException {
- String s = sendRequest("GET", "capabilities", null, monitor, false, fastFail);
- return s.getBytes();
- }
- }
-
- public void initialize(ProgressMonitor monitor) throws OsmApiInitializationException, OsmTransferCanceledException {
+ return sendRequest("GET", "capabilities", null, monitor, false, fastFail).getBytes();
+ }
+ }
+
+ /**
+ * Initializes this component by negotiating a protocol version with the server.
+ *
+ * @param monitor the progress monitor
+ * @throws OsmTransferCanceledException If the initialisation has been cancelled by user.
+ * @throws OsmApiInitializationException If any other exception occurs. Use getCause() to get the original exception.
+ */
+ public void initialize(ProgressMonitor monitor) throws OsmTransferCanceledException, OsmApiInitializationException {
initialize(monitor, false);
}
- /**
- * Initializes this component by negotiating a protocol version with the server.
- *
- * @param monitor
+
+ /**
+ * Initializes this component by negotiating a protocol version with the server, with the ability to control the timeout.
+ *
+ * @param monitor the progress monitor
* @param fastFail true to request quick initialisation with a small timeout (more likely to throw exception)
- * @exception OsmApiInitializationException thrown, if an exception occurs
- */
- public void initialize(ProgressMonitor monitor, boolean fastFail) throws OsmApiInitializationException, OsmTransferCanceledException {
+ * @throws OsmTransferCanceledException If the initialisation has been cancelled by user.
+ * @throws OsmApiInitializationException If any other exception occurs. Use getCause() to get the original exception.
+ */
+ public void initialize(ProgressMonitor monitor, boolean fastFail) throws OsmTransferCanceledException, OsmApiInitializationException {
if (initialized)
return;
@@ -215,5 +238,5 @@
* to load the layers in the first place becuase they would have
* been disabled! */
- if (Main.main.isDisplayingMapView()) {
+ if (Main.isDisplayingMapView()) {
for (Layer l : Main.map.mapView.getLayersOfType(ImageryLayer.class)) {
if (((ImageryLayer) l).getInfo().isBlacklisted()) {
@@ -224,16 +247,7 @@
}
- } catch(IOException e) {
- initialized = false;
- throw new OsmApiInitializationException(e);
- } catch(SAXException e) {
- initialized = false;
- throw new OsmApiInitializationException(e);
- } catch(ParserConfigurationException e) {
- initialized = false;
- throw new OsmApiInitializationException(e);
- } catch(OsmTransferCanceledException e){
+ } catch (OsmTransferCanceledException e) {
throw e;
- } catch(OsmTransferException e) {
+ } catch (Exception e) {
initialized = false;
throw new OsmApiInitializationException(e);
@@ -299,4 +313,5 @@
*
* @param osm the primitive
+ * @param monitor the progress monitor
* @throws OsmTransferException if something goes wrong
*/
@@ -339,4 +354,5 @@
* Deletes an OSM primitive on the server.
* @param osm the primitive
+ * @param monitor the progress monitor
* @throws OsmTransferException if something goes wrong
*/
@@ -535,8 +551,4 @@
}
- private String sendRequest(String requestMethod, String urlSuffix,String requestBody, ProgressMonitor monitor, boolean doAuth) throws OsmTransferException {
- return sendRequest(requestMethod, urlSuffix, requestBody, monitor, doAuth, false);
- }
-
/**
* Generic method for sending requests to the OSM API.
@@ -555,5 +567,5 @@
*
* @return the body of the HTTP response, if and only if the response code was "200 OK".
- * @exception OsmTransferException if the HTTP return code was not 200 (and retries have
+ * @throws OsmTransferException if the HTTP return code was not 200 (and retries have
* been exhausted), or rewrapping a Java exception.
*/
@@ -684,7 +696,7 @@
/**
- * returns the API capabilities; null, if the API is not initialized yet
- *
- * @return the API capabilities
+ * Replies the API capabilities
+ *
+ * @return the API capabilities, or null, if the API is not initialized yet
*/
public Capabilities getCapabilities() {
@@ -704,4 +716,5 @@
throw new OsmTransferException(tr("ID of current changeset > 0 required. Current ID is {0}.", changeset.getId()));
}
+
/**
* Replies the changeset data uploads are currently directed to
Index: trunk/src/org/openstreetmap/josm/io/OsmApiException.java
===================================================================
--- trunk/src/org/openstreetmap/josm/io/OsmApiException.java (revision 5385)
+++ trunk/src/org/openstreetmap/josm/io/OsmApiException.java (revision 5386)
@@ -3,4 +3,8 @@
import static org.openstreetmap.josm.tools.I18n.tr;
+/**
+ * Exception thrown when a communication error occurs when accessing the OSM API.
+ * @see OsmApi
+ */
public class OsmApiException extends OsmTransferException {
@@ -10,8 +14,10 @@
private String accessedUrl;
- public OsmApiException() {
- super();
- }
-
+ /**
+ * Constructs an {@code OsmApiException} with the specified response code, error header and error body
+ * @param responseCode The HTTP response code replied by the OSM server. See {@link java.net.HttpURLConnection HttpURLConnection} for predefined HTTP response code values
+ * @param errorHeader The error header, as transmitted in the {@code Error} field of the HTTP response header
+ * @param errorBody The error body, as transmitted in the HTTP response body
+ */
public OsmApiException(int responseCode, String errorHeader, String errorBody) {
this.responseCode = responseCode;
@@ -20,36 +26,85 @@
}
+ /**
+ * Constructs an {@code OsmApiException} with the specified detail message.
+ * The cause is not initialized, and may subsequently be initialized by a call to {@link #initCause}.
+ *
+ * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method)
+ */
+ public OsmApiException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs an {@code OsmApiException} with the specified cause and a detail message of
+ * (cause==null ? null : cause.toString())
+ * (which typically contains the class and detail message of cause).
+ *
+ * @param cause the cause (which is saved for later retrieval by the {@link #getCause} method).
+ * A null value is permitted, and indicates that the cause is nonexistent or unknown.
+ */
+ public OsmApiException(Throwable cause) {
+ super(cause);
+ }
+
+ /**
+ * Constructs an {@code OsmApiException} with the specified detail message and cause.
+ *
+ * Note that the detail message associated with {@code cause} is not automatically incorporated + * into this exception's detail message. + * + * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) + * @param cause The cause (which is saved for later retrieval by the {@link #getCause} method). + * A null value is permitted, and indicates that the cause is nonexistent or unknown. + * + */ public OsmApiException(String message, Throwable cause) { super(message, cause); } - public OsmApiException(String message) { - super(message); - } - - public OsmApiException(Throwable cause) { - super(cause); - } - + /** + * Replies the HTTP response code. + * @return The HTTP response code replied by the OSM server. Refer to OSM API to see the list of response codes returned by the API for each call. + */ public int getResponseCode() { return responseCode; } + /** + * Sets the HTTP response code. + * @param responseCode The HTTP response code replied by the OSM server. See {@link java.net.HttpURLConnection HttpURLConnection} for predefined HTTP response code values + */ public void setResponseCode(int responseCode) { this.responseCode = responseCode; } + /** + * Replies the error header. + * @return the error header, as transmitted in the {@code Error} field of the HTTP response header + */ public String getErrorHeader() { return errorHeader; } + /** + * Sets the error header. + * @param errorHeader the error header, as transmitted in the {@code Error} field of the HTTP response header + */ public void setErrorHeader(String errorHeader) { this.errorHeader = errorHeader; } + /** + * Replies the error body. + * @return The error body, as transmitted in the HTTP response body + */ public String getErrorBody() { return errorBody; } + /** + * Sets the error body. + * @param errorBody The error body, as transmitted in the HTTP response body + */ public void setErrorBody(String errorBody) { this.errorBody = errorBody; @@ -73,4 +128,5 @@ } catch (Exception e) { + // Ignored } try @@ -84,4 +140,5 @@ } catch (Exception e) { + // Ignored } return sb.toString(); @@ -108,8 +165,16 @@ } + /** + * 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. + * @param url the complete URL accessed when this error occured. + */ public void setAccessedUrl(String url) { this.accessedUrl = url; } + /** + * 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. + * @return the complete URL accessed when this error occured. + */ public String getAccessedUrl() { return accessedUrl; Index: trunk/src/org/openstreetmap/josm/io/OsmApiInitializationException.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/OsmApiInitializationException.java (revision 5385) +++ trunk/src/org/openstreetmap/josm/io/OsmApiInitializationException.java (revision 5386) @@ -2,20 +2,45 @@ package org.openstreetmap.josm.io; +/** + * Exception thrown when a communication error occured with the OSM server during API initialization. + * @see OsmApi#initialize + */ public class OsmApiInitializationException extends OsmTransferException { - public OsmApiInitializationException() { - super(); - } - - public OsmApiInitializationException(String message, Throwable cause) { - super(message, cause); - } - + /** + * Constructs an {@code OsmApiInitializationException} with the specified detail message. + * The cause is not initialized, and may subsequently be initialized by a call to {@link #initCause}. + * + * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) + */ public OsmApiInitializationException(String message) { super(message); } + /** + * Constructs an {@code OsmApiInitializationException} with the specified cause and a detail message of + * (cause==null ? null : cause.toString()) + * (which typically contains the class and detail message of cause). + * + * @param cause the cause (which is saved for later retrieval by the {@link #getCause} method). + * A null value is permitted, and indicates that the cause is nonexistent or unknown. + */ public OsmApiInitializationException(Throwable cause) { super(cause); } + + /** + * Constructs an {@code OsmApiInitializationException} with the specified detail message and cause. + * + *
Note that the detail message associated with {@code cause} is not automatically incorporated + * into this exception's detail message. + * + * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) + * @param cause The cause (which is saved for later retrieval by the {@link #getCause} method). + * A null value is permitted, and indicates that the cause is nonexistent or unknown. + * + */ + public OsmApiInitializationException(String message, Throwable cause) { + super(message, cause); + } } Index: trunk/src/org/openstreetmap/josm/io/OsmTransferCanceledException.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/OsmTransferCanceledException.java (revision 5385) +++ trunk/src/org/openstreetmap/josm/io/OsmTransferCanceledException.java (revision 5386) @@ -2,4 +2,7 @@ package org.openstreetmap.josm.io; +/** + * Exception thrown when a communication with the OSM server has been cancelled by the user. + */ public class OsmTransferCanceledException extends OsmTransferException { Index: trunk/src/org/openstreetmap/josm/io/OsmTransferException.java =================================================================== --- trunk/src/org/openstreetmap/josm/io/OsmTransferException.java (revision 5385) +++ trunk/src/org/openstreetmap/josm/io/OsmTransferException.java (revision 5386) @@ -2,23 +2,59 @@ package org.openstreetmap.josm.io; +/** + * Exception thrown when a communication error with the OSM server occurs. + */ public class OsmTransferException extends Exception { private String url = OsmApi.getOsmApi().getBaseUrl(); + /** + * Constructs an {@code OsmTransferException} with {@code null} as its error detail message. + * The cause is not initialized, and may subsequently be initialized by a call to {@link #initCause}. + */ public OsmTransferException() { } + /** + * Constructs an {@code OsmTransferException} with the specified detail message. + * The cause is not initialized, and may subsequently be initialized by a call to {@link #initCause}. + * + * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) + */ public OsmTransferException(String message) { super(message); } + /** + * Constructs an {@code OsmTransferException} with the specified cause and a detail message of + * (cause==null ? null : cause.toString()) + * (which typically contains the class and detail message of cause). + * + * @param cause the cause (which is saved for later retrieval by the {@link #getCause} method). + * A null value is permitted, and indicates that the cause is nonexistent or unknown. + */ public OsmTransferException(Throwable cause) { super(cause); } + /** + * Constructs an {@code OsmTransferException} with the specified detail message and cause. + * + *
Note that the detail message associated with {@code cause} is not automatically incorporated + * into this exception's detail message. + * + * @param message The detail message (which is saved for later retrieval by the {@link #getMessage} method) + * @param cause The cause (which is saved for later retrieval by the {@link #getCause} method). + * A null value is permitted, and indicates that the cause is nonexistent or unknown. + * + */ public OsmTransferException(String message, Throwable cause) { super(message, cause); } + /** + * Sets the URL related to this error. + * @param url the URL related to this error (which is saved for later retrieval by the {@link #getUrl} method). + */ public void setUrl(String url) { this.url = url; @@ -26,10 +62,9 @@ /** - * - * @return Api base url or url set using setUrl method + * Gets the URL related to this error. + * @return API base URL or URL set using the {@link #setUrl} method */ public String getUrl() { return url; } - }