org.openstreetmap.josm.io
Class OsmApi

java.lang.Object
  extended by org.openstreetmap.josm.io.OsmConnection
      extended by org.openstreetmap.josm.io.OsmApi

public class OsmApi
extends OsmConnection

Class that encapsulates the communications with the OSM API.

All interaction with the server-side OSM API should go through this class.

It is conceivable to extract this into an interface later and create various classes implementing the interface, to be able to talk to various kinds of servers.


Nested Class Summary
private  class OsmApi.CapabilitiesCache
           
private  class OsmApi.CapabilitiesParser
          A parser for the "capabilities" response XML
 
Field Summary
private  Capabilities capabilities
          the api capabilities
private  Changeset changeset
          Object describing current changeset
static java.lang.String DEFAULT_API_URL
          Default URL of the standard OSM API.
static int DEFAULT_MAX_NUM_RETRIES
          Maximum number of retries to send a request in case of HTTP 500 errors or timeouts
private  boolean initialized
          true if successfully initialized
private static java.util.HashMap<java.lang.String,OsmApi> instances
           
static int MAX_DOWNLOAD_THREADS
          Maximum number of concurrent download threads, imposed by OSM API usage policy.
private  java.lang.String serverUrl
          the server URL
private  java.lang.String version
          API version used for server communications
 
Fields inherited from class org.openstreetmap.josm.io.OsmConnection
activeConnection, cancel, oauthParameters
 
Constructor Summary
protected OsmApi(java.lang.String serverUrl)
          creates an OSM api for a specific server URL
 
Method Summary
 void closeChangeset(Changeset changeset, ProgressMonitor monitor)
          Closes a changeset on the server.
 void createPrimitive(IPrimitive osm, ProgressMonitor monitor)
          Creates an OSM primitive on the server.
 void deletePrimitive(IPrimitive osm, ProgressMonitor monitor)
          Deletes an OSM primitive on the server.
protected  void ensureValidChangeset()
          Ensures that the current changeset can be used for uploading data
 java.lang.String getBaseUrl()
          Returns the base URL for API requests, including the negotiated version number.
 Capabilities getCapabilities()
          Replies the API capabilities
 Changeset getChangeset()
          Replies the changeset data uploads are currently directed to
 java.lang.String getHost()
          Replies the host name of the server URL.
protected  int getMaxRetries()
          Replies the max.
static OsmApi getOsmApi()
          Replies the OsmApi for the URL given by the preference osm-server.url
static OsmApi getOsmApi(java.lang.String serverUrl)
          Replies the OsmApi for a given server URL
 java.lang.String getVersion()
          Replies the OSM protocol version we use to talk to the server.
 void initialize(ProgressMonitor monitor)
          Initializes this component by negotiating a protocol version with the server.
 void initialize(ProgressMonitor monitor, boolean fastFail)
          Initializes this component by negotiating a protocol version with the server, with the ability to control the timeout.
protected  boolean isUsingOAuth()
           
 void modifyPrimitive(IPrimitive osm, ProgressMonitor monitor)
          Modifies an OSM primitive on the server.
 void openChangeset(Changeset changeset, ProgressMonitor progressMonitor)
          Creates a new changeset based on the keys in changeset.
private  java.lang.String sendRequest(java.lang.String requestMethod, java.lang.String urlSuffix, java.lang.String requestBody, ProgressMonitor monitor)
           
private  java.lang.String sendRequest(java.lang.String requestMethod, java.lang.String urlSuffix, java.lang.String requestBody, ProgressMonitor monitor, boolean doAuthenticate, boolean fastFail)
          Generic method for sending requests to the OSM API.
 void setChangeset(Changeset changeset)
          Sets the changesets to which further data uploads are directed.
private  void sleepAndListen(int retry, ProgressMonitor monitor)
           
private  java.lang.String toXml(Changeset s)
          Makes an XML string from an OSM primitive.
private  java.lang.String toXml(IPrimitive o, boolean addBody)
          Makes an XML string from an OSM primitive.
 void updateChangeset(Changeset changeset, ProgressMonitor monitor)
          Updates a changeset with the keys in changesetUpdate.
 java.util.Collection<IPrimitive> uploadDiff(java.util.Collection<? extends IPrimitive> list, ProgressMonitor monitor)
          Uploads a list of changes in "diff" form to the server.
 
Methods inherited from class org.openstreetmap.josm.io.OsmConnection
addAuth, addBasicAuthorizationHeader, addOAuthAuthorizationHeader, cancel, isCanceled
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_MAX_NUM_RETRIES

public static final int DEFAULT_MAX_NUM_RETRIES
Maximum number of retries to send a request in case of HTTP 500 errors or timeouts

See Also:
Constant Field Values

MAX_DOWNLOAD_THREADS

public static final int MAX_DOWNLOAD_THREADS
Maximum number of concurrent download threads, imposed by OSM API usage policy.

Since:
5386
See Also:
Constant Field Values

DEFAULT_API_URL

public static final java.lang.String DEFAULT_API_URL
Default URL of the standard OSM API.

Since:
5422
See Also:
Constant Field Values

instances

private static java.util.HashMap<java.lang.String,OsmApi> instances

serverUrl

private java.lang.String serverUrl
the server URL


changeset

private Changeset changeset
Object describing current changeset


version

private java.lang.String version
API version used for server communications


capabilities

private Capabilities capabilities
the api capabilities


initialized

private boolean initialized
true if successfully initialized

Constructor Detail

OsmApi

protected OsmApi(java.lang.String serverUrl)
creates an OSM api for a specific server URL

Parameters:
serverUrl - the server URL. Must not be null
Throws:
java.lang.IllegalArgumentException - thrown, if serverUrl is null
Method Detail

getOsmApi

public static OsmApi getOsmApi(java.lang.String serverUrl)
Replies the OsmApi for a given server URL

Parameters:
serverUrl - the server URL
Returns:
the OsmApi
Throws:
java.lang.IllegalArgumentException - thrown, if serverUrl is null

getOsmApi

public static OsmApi getOsmApi()
Replies the OsmApi for the URL given by the preference osm-server.url

Returns:
the OsmApi
Throws:
java.lang.IllegalStateException - thrown, if the preference osm-server.url is not set

getVersion

public java.lang.String getVersion()
Replies the OSM protocol version we use to talk to the server.

Returns:
protocol version, or null if not yet negotiated.

getHost

public java.lang.String getHost()
Replies the host name of the server URL.

Returns:
the host name of the server URL, or null if the server URL is malformed.

initialize

public void initialize(ProgressMonitor monitor)
                throws OsmTransferCanceledException,
                       OsmApiInitializationException
Initializes this component by negotiating a protocol version with the server.

Parameters:
monitor - the progress monitor
Throws:
OsmTransferCanceledException - If the initialisation has been cancelled by user.
OsmApiInitializationException - If any other exception occurs. Use getCause() to get the original exception.

initialize

public void initialize(ProgressMonitor monitor,
                       boolean fastFail)
                throws OsmTransferCanceledException,
                       OsmApiInitializationException
Initializes this component by negotiating a protocol version with the server, with the ability to control the timeout.

Parameters:
monitor - the progress monitor
fastFail - true to request quick initialisation with a small timeout (more likely to throw exception)
Throws:
OsmTransferCanceledException - If the initialisation has been cancelled by user.
OsmApiInitializationException - If any other exception occurs. Use getCause() to get the original exception.

toXml

private java.lang.String toXml(IPrimitive o,
                               boolean addBody)
Makes an XML string from an OSM primitive. Uses the OsmWriter class.

Parameters:
o - the OSM primitive
addBody - true to generate the full XML, false to only generate the encapsulating tag
Returns:
XML string

toXml

private java.lang.String toXml(Changeset s)
Makes an XML string from an OSM primitive. Uses the OsmWriter class.

Parameters:
o - the OSM primitive
addBody - true to generate the full XML, false to only generate the encapsulating tag
Returns:
XML string

getBaseUrl

public java.lang.String getBaseUrl()
Returns the base URL for API requests, including the negotiated version number.

Returns:
base URL string

createPrimitive

public void createPrimitive(IPrimitive osm,
                            ProgressMonitor monitor)
                     throws OsmTransferException
Creates an OSM primitive on the server. The OsmPrimitive object passed in is modified by giving it the server-assigned id.

Parameters:
osm - the primitive
monitor - the progress monitor
Throws:
OsmTransferException - if something goes wrong

modifyPrimitive

public void modifyPrimitive(IPrimitive osm,
                            ProgressMonitor monitor)
                     throws OsmTransferException
Modifies an OSM primitive on the server.

Parameters:
osm - the primitive. Must not be null.
monitor - the progress monitor
Throws:
OsmTransferException - if something goes wrong

deletePrimitive

public void deletePrimitive(IPrimitive osm,
                            ProgressMonitor monitor)
                     throws OsmTransferException
Deletes an OSM primitive on the server.

Parameters:
osm - the primitive
monitor - the progress monitor
Throws:
OsmTransferException - if something goes wrong

openChangeset

public void openChangeset(Changeset changeset,
                          ProgressMonitor progressMonitor)
                   throws OsmTransferException
Creates a new changeset based on the keys in changeset. If this method succeeds, changeset.getId() replies the id the server assigned to the new changeset The changeset must not be null, but its key/value-pairs may be empty.

Parameters:
changeset - the changeset toe be created. Must not be null.
progressMonitor - the progress monitor
Throws:
OsmTransferException - signifying a non-200 return code, or connection errors
java.lang.IllegalArgumentException - thrown if changeset is null

updateChangeset

public void updateChangeset(Changeset changeset,
                            ProgressMonitor monitor)
                     throws OsmTransferException
Updates a changeset with the keys in changesetUpdate. The changeset must not be null and id > 0 must be true.

Parameters:
changeset - the changeset to update. Must not be null.
monitor - the progress monitor. If null, uses the NullProgressMonitor.INSTANCE.
Throws:
OsmTransferException - if something goes wrong.
java.lang.IllegalArgumentException - if changeset is null
java.lang.IllegalArgumentException - if changeset.getId() <= 0

closeChangeset

public void closeChangeset(Changeset changeset,
                           ProgressMonitor monitor)
                    throws OsmTransferException
Closes a changeset on the server. Sets changeset.setOpen(false) if this operation succeeds.

Parameters:
changeset - the changeset to be closed. Must not be null. changeset.getId() > 0 required.
monitor - the progress monitor. If null, uses NullProgressMonitor.INSTANCE
Throws:
OsmTransferException - if something goes wrong.
java.lang.IllegalArgumentException - thrown if changeset is null
java.lang.IllegalArgumentException - thrown if changeset.getId() <= 0

uploadDiff

public java.util.Collection<IPrimitive> uploadDiff(java.util.Collection<? extends IPrimitive> list,
                                                   ProgressMonitor monitor)
                                            throws OsmTransferException
Uploads a list of changes in "diff" form to the server.

Parameters:
list - the list of changed OSM Primitives
monitor - the progress monitor
Returns:
list of processed primitives
Throws:
OsmTransferException - if something is wrong

sleepAndListen

private void sleepAndListen(int retry,
                            ProgressMonitor monitor)
                     throws OsmTransferCanceledException
Throws:
OsmTransferCanceledException

getMaxRetries

protected int getMaxRetries()
Replies the max. number of retries in case of 5XX errors on the server

Returns:
the max number of retries

isUsingOAuth

protected boolean isUsingOAuth()

sendRequest

private java.lang.String sendRequest(java.lang.String requestMethod,
                                     java.lang.String urlSuffix,
                                     java.lang.String requestBody,
                                     ProgressMonitor monitor)
                              throws OsmTransferException
Throws:
OsmTransferException

sendRequest

private java.lang.String sendRequest(java.lang.String requestMethod,
                                     java.lang.String urlSuffix,
                                     java.lang.String requestBody,
                                     ProgressMonitor monitor,
                                     boolean doAuthenticate,
                                     boolean fastFail)
                              throws OsmTransferException
Generic method for sending requests to the OSM API. This method will automatically re-try any requests that are answered with a 5xx error code, or that resulted in a timeout exception from the TCP layer.

Parameters:
requestMethod - The http method used when talking with the server.
urlSuffix - The suffix to add at the server url, not including the version number, but including any object ids (e.g. "/way/1234/history").
requestBody - the body of the HTTP request, if any.
monitor - the progress monitor
doAuthenticate - set to true, if the request sent to the server shall include authentication credentials;
fastFail - true to request a short timeout
Returns:
the body of the HTTP response, if and only if the response code was "200 OK".
Throws:
OsmTransferException - if the HTTP return code was not 200 (and retries have been exhausted), or rewrapping a Java exception.

getCapabilities

public Capabilities getCapabilities()
Replies the API capabilities

Returns:
the API capabilities, or null, if the API is not initialized yet

ensureValidChangeset

protected void ensureValidChangeset()
                             throws OsmTransferException
Ensures that the current changeset can be used for uploading data

Throws:
OsmTransferException - thrown if the current changeset can't be used for uploading data

getChangeset

public Changeset getChangeset()
Replies the changeset data uploads are currently directed to

Returns:
the changeset data uploads are currently directed to

setChangeset

public void setChangeset(Changeset changeset)
Sets the changesets to which further data uploads are directed. The changeset can be null. If it isn't null it must have been created, i.e. id > 0 is required. Furthermore, it must be open.

Parameters:
changeset - the changeset
Throws:
java.lang.IllegalArgumentException - thrown if changeset.getId() <= 0
java.lang.IllegalArgumentException - thrown if !changeset.isOpen()


JOSM