|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.openstreetmap.josm.io.OsmConnection
org.openstreetmap.josm.io.OsmApi
public class OsmApi
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 |
---|
public static final int DEFAULT_MAX_NUM_RETRIES
public static final int MAX_DOWNLOAD_THREADS
public static final java.lang.String DEFAULT_API_URL
private static java.util.HashMap<java.lang.String,OsmApi> instances
private java.lang.String serverUrl
private Changeset changeset
private java.lang.String version
private Capabilities capabilities
private boolean initialized
Constructor Detail |
---|
protected OsmApi(java.lang.String serverUrl)
serverUrl
- the server URL. Must not be null
java.lang.IllegalArgumentException
- thrown, if serverUrl is nullMethod Detail |
---|
public static OsmApi getOsmApi(java.lang.String serverUrl)
OsmApi
for a given server URL
serverUrl
- the server URL
java.lang.IllegalArgumentException
- thrown, if serverUrl is nullpublic static OsmApi getOsmApi()
OsmApi
for the URL given by the preference osm-server.url
java.lang.IllegalStateException
- thrown, if the preference osm-server.url
is not setpublic java.lang.String getVersion()
public java.lang.String getHost()
public void initialize(ProgressMonitor monitor) throws OsmTransferCanceledException, OsmApiInitializationException
monitor
- the progress monitor
OsmTransferCanceledException
- If the initialisation has been cancelled by user.
OsmApiInitializationException
- If any other exception occurs. Use getCause() to get the original exception.public void initialize(ProgressMonitor monitor, boolean fastFail) throws OsmTransferCanceledException, OsmApiInitializationException
monitor
- the progress monitorfastFail
- true to request quick initialisation with a small timeout (more likely to throw exception)
OsmTransferCanceledException
- If the initialisation has been cancelled by user.
OsmApiInitializationException
- If any other exception occurs. Use getCause() to get the original exception.private java.lang.String toXml(IPrimitive o, boolean addBody)
o
- the OSM primitiveaddBody
- true to generate the full XML, false to only generate the encapsulating tag
private java.lang.String toXml(Changeset s)
o
- the OSM primitiveaddBody
- true to generate the full XML, false to only generate the encapsulating tag
public java.lang.String getBaseUrl()
public void createPrimitive(IPrimitive osm, ProgressMonitor monitor) throws OsmTransferException
osm
- the primitivemonitor
- the progress monitor
OsmTransferException
- if something goes wrongpublic void modifyPrimitive(IPrimitive osm, ProgressMonitor monitor) throws OsmTransferException
osm
- the primitive. Must not be null.monitor
- the progress monitor
OsmTransferException
- if something goes wrongpublic void deletePrimitive(IPrimitive osm, ProgressMonitor monitor) throws OsmTransferException
osm
- the primitivemonitor
- the progress monitor
OsmTransferException
- if something goes wrongpublic void openChangeset(Changeset changeset, ProgressMonitor progressMonitor) throws OsmTransferException
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.
changeset
- the changeset toe be created. Must not be null.progressMonitor
- the progress monitor
OsmTransferException
- signifying a non-200 return code, or connection errors
java.lang.IllegalArgumentException
- thrown if changeset is nullpublic void updateChangeset(Changeset changeset, ProgressMonitor monitor) throws OsmTransferException
changesetUpdate
. The changeset must not
be null and id > 0 must be true.
changeset
- the changeset to update. Must not be null.monitor
- the progress monitor. If null, uses the NullProgressMonitor.INSTANCE
.
OsmTransferException
- if something goes wrong.
java.lang.IllegalArgumentException
- if changeset is null
java.lang.IllegalArgumentException
- if changeset.getId() <= 0public void closeChangeset(Changeset changeset, ProgressMonitor monitor) throws OsmTransferException
changeset
- the changeset to be closed. Must not be null. changeset.getId() > 0 required.monitor
- the progress monitor. If null, uses NullProgressMonitor.INSTANCE
OsmTransferException
- if something goes wrong.
java.lang.IllegalArgumentException
- thrown if changeset is null
java.lang.IllegalArgumentException
- thrown if changeset.getId() <= 0public java.util.Collection<IPrimitive> uploadDiff(java.util.Collection<? extends IPrimitive> list, ProgressMonitor monitor) throws OsmTransferException
list
- the list of changed OSM Primitivesmonitor
- the progress monitor
OsmTransferException
- if something is wrongprivate void sleepAndListen(int retry, ProgressMonitor monitor) throws OsmTransferCanceledException
OsmTransferCanceledException
protected int getMaxRetries()
protected boolean isUsingOAuth()
private java.lang.String sendRequest(java.lang.String requestMethod, java.lang.String urlSuffix, java.lang.String requestBody, ProgressMonitor monitor) throws OsmTransferException
OsmTransferException
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
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 monitordoAuthenticate
- set to true, if the request sent to the server shall include authentication
credentials;fastFail
- true to request a short timeout
OsmTransferException
- if the HTTP return code was not 200 (and retries have
been exhausted), or rewrapping a Java exception.public Capabilities getCapabilities()
protected void ensureValidChangeset() throws OsmTransferException
OsmTransferException
- thrown if the current changeset can't be used for
uploading datapublic Changeset getChangeset()
public void setChangeset(Changeset changeset)
changeset
- the changeset
java.lang.IllegalArgumentException
- thrown if changeset.getId() <= 0
java.lang.IllegalArgumentException
- thrown if !changeset.isOpen()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |