Package org.openstreetmap.josm.io

Class 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.
    Since:
    1523

    • Constructor Detail

      • OsmApi

        protected OsmApi​(java.lang.String serverUrl)
        Constructs a new OsmApi for a specific server URL.
        Parameters:
        serverUrl - the server URL. Must not be null
        Throws:
        java.lang.IllegalArgumentException - 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 - 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

      • 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.

      • initializeCapabilities

        private void initializeCapabilities​(java.lang.String xml)
                             throws org.xml.sax.SAXException,
                                    java.io.IOException,
                                    javax.xml.parsers.ParserConfigurationException
        Throws:
        org.xml.sax.SAXException
        java.io.IOException
        javax.xml.parsers.ParserConfigurationException

      • toXml

        protected final 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

        protected final java.lang.String toXml​(Changeset s)
        Makes an XML string from an OSM primitive. Uses the OsmWriter class.
        Parameters:
        s - the changeset
        Returns:
        XML string

      • getBaseUrl

        private static java.lang.String getBaseUrl​(java.lang.String serverUrl,
                                           java.lang.String version)

      • getBaseUrl

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

      • getServerUrl

        public java.lang.String getServerUrl()
        Returns the server URL
        Returns:
        the server URL
        Since:
        9353

      • 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 - 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 - if changeset is null
        java.lang.IllegalArgumentException - if changeset.getId() <= 0

      • 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

        public static boolean isUsingOAuth()
        Determines if JOSM is configured to access OSM API via OAuth
        Returns:
        true if JOSM is configured to access OSM API via OAuth, false otherwise
        Since:
        6349

      • isUsingOAuth

        public static boolean isUsingOAuth​(OAuthVersion version)
        Determines if JOSM is configured to access OSM API via OAuth
        Parameters:
        version - The OAuth version
        Returns:
        true if JOSM is configured to access OSM API via OAuth, false otherwise
        Since:
        18650

      • isUsingOAuthAndOAuthSetUp

        public static boolean isUsingOAuthAndOAuthSetUp​(OsmApi api)
        Ensure that OAuth is set up
        Parameters:
        api - The api for which we need OAuth keys
        Returns:
        true if we are using OAuth and there are keys for the specified API

      • getAuthMethod

        public static java.lang.String getAuthMethod()
        Returns the authentication method set in the preferences
        Returns:
        the authentication method

      • getAuthMethodVersion

        @Nullable
public static OAuthVersion getAuthMethodVersion()
        Returns the authentication method set in the preferences
        Returns:
        the authentication method
        Since:
        18991

      • sendRequest

        protected final java.lang.String sendRequest​(java.lang.String requestMethod,
                                             java.lang.String urlSuffix,
                                             java.lang.String requestBody,
                                             ProgressMonitor monitor,
                                             java.lang.String contentType,
                                             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
        contentType - Content-Type to set for PUT/POST/DELETE requests. Can be set to null, in that case it means text/xml
        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

      • 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 - if changeset.getId() <= 0
        java.lang.IllegalArgumentException - if !changeset.isOpen()

      • createNote

        public Note createNote​(LatLon latlon,
                       java.lang.String text,
                       ProgressMonitor monitor)
                throws OsmTransferException
        Create a new note on the server.
        Parameters:
        latlon - Location of note
        text - Comment entered by user to open the note
        monitor - Progress monitor
        Returns:
        Note as it exists on the server after creation (ID assigned)
        Throws:
        OsmTransferException - if any error occurs during dialog with OSM API

      • addCommentToNote

        public Note addCommentToNote​(Note note,
                             java.lang.String comment,
                             ProgressMonitor monitor)
                      throws OsmTransferException
        Add a comment to an existing note.
        Parameters:
        note - The note to add a comment to
        comment - Text of the comment
        monitor - Progress monitor
        Returns:
        Note returned by the API after the comment was added
        Throws:
        OsmTransferException - if any error occurs during dialog with OSM API

      • closeNote

        public Note closeNote​(Note note,
                      java.lang.String closeMessage,
                      ProgressMonitor monitor)
               throws OsmTransferException
        Close a note.
        Parameters:
        note - Note to close. Must currently be open
        closeMessage - Optional message supplied by the user when closing the note
        monitor - Progress monitor
        Returns:
        Note returned by the API after the close operation
        Throws:
        OsmTransferException - if any error occurs during dialog with OSM API

      • reopenNote

        public Note reopenNote​(Note note,
                       java.lang.String reactivateMessage,
                       ProgressMonitor monitor)
                throws OsmTransferException
        Reopen a closed note
        Parameters:
        note - Note to reopen. Must currently be closed
        reactivateMessage - Optional message supplied by the user when reopening the note
        monitor - Progress monitor
        Returns:
        Note returned by the API after the reopen operation
        Throws:
        OsmTransferException - if any error occurs during dialog with OSM API

      • parseSingleNote

        private static Note parseSingleNote​(java.lang.String xml)
                             throws OsmTransferException
        Method for parsing API responses for operations on individual notes
        Parameters:
        xml - the API response as XML data
        Returns:
        the resulting Note
        Throws:
        OsmTransferException - if the API response cannot be parsed