move Java code from API documentation to code (graphhopper#2180)

* move to code

* the sync endpoint makes more sense now as default

Author: karussell

client-hc/README.md

@@ -1,7 +1,8 @@
 # Handcrafted Java and Android client for the GraphHopper Directions API
 
-We have a hand-crafted API client (`client-hc`) for the Matrix and Routing API that is more memory efficient e.g. for large matrices
-than the autogenerated client below. The Maven snippet for the handcrafted client is:
+We have a hand-crafted API client (`client-hc`) for several API parts like the Matrix and Routing API that is more memory efficient 
+e.g. for large matrices than the autogenerated client. To use this project
+include the following Maven snippet:
 
 ```xml
 <dependency>
@@ -13,131 +14,30 @@ than the autogenerated client below. The Maven snippet for the handcrafted clien
 
 ## Usage
 
-```java
-// Hint: create this thread safe instance only once in your application to allow the underlying library to cache the costly initial https handshake
-GraphHopperWeb gh = new GraphHopperWeb();
-// insert your key here
-gh.setKey("YOUR_KEY");
-// change timeout, default is 5 seconds
-gh.setDownloader(new OkHttpClient.Builder().
-                connectTimeout(5, TimeUnit.SECONDS).
-                readTimeout(5, TimeUnit.SECONDS).build());
-
-// specify at least two coordinates
-GHRequest req = new GHRequest().
-   addPoint(new GHPoint(49.6724, 11.3494)).
-   addPoint(new GHPoint(49.6550, 11.4180));
-// Set vehicle like car, bike, foot, ...
-req.setVehicle("bike");
-// Optionally enable/disable elevation in output PointList, currently bike and foot support elevation, default is false
-req.getHints().put("elevation", false);
-// Optionally enable/disable turn instruction information, defaults is true
-req.getHints().put("instructions", true);
-// Optionally enable/disable path geometry information, default is true
-req.getHints().put("calc_points", true);
-// note: turn off instructions and calcPoints if you just need the distance or time 
-// information to make calculation and transmission faster
-//
-// Optionally set specific locale for instruction information, supports already over 25 languages,
-// defaults to English
-req.setLocale(Locale.GERMAN);
-
-GHResponse fullRes = gh.route(req);
-        
-if(res.hasErrors()) {
-   // handle or throw exceptions res.getErrors()
-   return;
-}
-
-ResponsePath res = fullRes.getBest();
-// get path geometry information (latitude, longitude and optionally elevation)
-PointList pl = res.getPoints();
-// distance of the full path, in meter
-double distance = res.getDistance();
-// time of the full path, in milliseconds
-long millis = res.getTime();
-// get information per turn instruction
-InstructionList il = res.getInstructions();
-```
-
-### Matrix API
-
-```java
-// Hint: create this thread safe instance only once in your application to allow the underlying library to cache the costly initial https handshake
-GraphHopperMatrixWeb matrixClient = new GraphHopperMatrixWeb();
-matrixClient.setKey("[YOUR_KEY]");
-
-GHMRequest ghmRequest = new GHMRequest();
-ghmRequest.addOutArray("distances");
-ghmRequest.addOutArray("times");
-ghmRequest.setVehicle("car");
-
-// init points for a symmetric matrix
-List<GHPoint> allPoints = ...;
-ghmRequest.addAllPoints(allPoints);
-
-// or init e.g. a one-to-many matrix:
-ghmRequest.addFromPoint(from);
-for(GHPoint to : toList) {
-   ghmRequest.addToPoint(to);
-}
-
-MatrixResponse response = matrixClient.route(ghmRequest);
-GHMResponse singleRsp = response.get(fromIndex, toIndex);
-singleRsp.getDistance();
-...
-```
-
-For small matrices like 20x20 or less locations you can use synchronous calls to reduce latency:
-
-```java
-GraphHopperMatrixWeb ghMatrix = new GraphHopperMatrixWeb(new GHMatrixSyncRequester());
-```
-
-## Build Latest Development Version
-
-```bash
-git clone https://github.com/graphhopper/directions-api-java-client/
-cd client
-mvn -DskipTests=true clean install
-
-# now execute the test and set your key
-mvn -Dgraphhopper.key=[YOUR_KEY] clean test verify
-```
-
-## Android 
-
-It is important to use this client not on the main thread of Android as it could block the app. 
-See [issue 7](https://github.com/graphhopper/directions-api-java-client/issues/7) for more information.
-
-# Autogenerated Client
-
-The autogenerated client is available [here](https://github.com/graphhopper/directions-api-clients) and you can refer to this client in your pom.xml via
-```xml
-<dependency>
-  <groupId>com.graphhopper</groupId>
-  <artifactId>directions-api-client</artifactId>
-  <version>[CURRENT-VERSION]</version>
-</dependency>
-```
-
-Please [search maven](https://search.maven.org/#search%7Cga%7C1%7Cdirections-api-client-parent) for the latest version.
+A real world example for the Routing and Matrix API can be found
+[here](./src/test/java/com/graphhopper/api/Examples.java).
 
 ## License
 
 Apache License 2.0
 
 ## Usage
 
-You can use the API client for many API parts like:
+You can use the API client for many API parts:
 
  * the Geocoding API
  * the Route Optimization API
  * the Routing API
  * the Matrix API
  * the Isochrone API
 
-Please see the [examples](https://github.com/graphhopper/directions-api-java-client/tree/master/client-examples/src/main/java/com/graphhopper/directions/api/examples) for specific and up-to-date Java code. This client was auto created via a swagger configuration. You can easily do so on your own too with [this repository](https://github.com/graphhopper/directions-api-clients).
+For the Route Optimization API you can create the sources from our OpenAPI spec. 
+See [this repository](https://github.com/graphhopper/directions-api-clients#deprecated-notice) for more details about it.
+
+## Android 
+
+It is important to use this client not on the main thread of Android as it could block the app. 
+See [issue 7](https://github.com/graphhopper/directions-api-java-client/issues/7) for more information.
 
 ### Android Alternative
 

client-hc/pom.xml

@@ -41,7 +41,7 @@
         <dependency>
             <groupId>com.squareup.okhttp3</groupId>
             <artifactId>okhttp</artifactId>
-            <version>3.14.2</version>
+            <version>3.14.9</version>
         </dependency>
         <dependency>
             <groupId>org.slf4j</groupId>

client-hc/src/main/java/com/graphhopper/api/GraphHopperMatrixWeb.java

@@ -15,11 +15,11 @@ public class GraphHopperMatrixWeb {
     private String key;
 
     public GraphHopperMatrixWeb() {
-        this(new GHMatrixBatchRequester());
+        this(new GHMatrixSyncRequester());
     }
 
     public GraphHopperMatrixWeb(String serviceUrl) {
-        this(new GHMatrixBatchRequester(serviceUrl));
+        this(new GHMatrixSyncRequester(serviceUrl));
     }
 
     public GraphHopperMatrixWeb(GHMatrixAbstractRequester requester) {

client-hc/src/test/java/com/graphhopper/api/Examples.java

@@ -0,0 +1,101 @@
+package com.graphhopper.api;
+
+import com.graphhopper.GHRequest;
+import com.graphhopper.GHResponse;
+import com.graphhopper.ResponsePath;
+import com.graphhopper.util.Instruction;
+import com.graphhopper.util.InstructionList;
+import com.graphhopper.util.PointList;
+import com.graphhopper.util.shapes.GHPoint;
+import okhttp3.OkHttpClient;
+import org.junit.Ignore;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Locale;
+import java.util.concurrent.TimeUnit;
+
+@Ignore
+public class Examples {
+
+    String apiKey = "<YOUR_API_KEY>";
+
+    @Test
+    public void routing() {
+        // Hint: create this thread safe instance only once in your application to allow the underlying library to cache the costly initial https handshake
+        GraphHopperWeb gh = new GraphHopperWeb();
+        // insert your key here
+        gh.setKey(apiKey);
+        // change timeout, default is 5 seconds
+        gh.setDownloader(new OkHttpClient.Builder().connectTimeout(5, TimeUnit.SECONDS).readTimeout(5, TimeUnit.SECONDS).build());
+
+        // specify at least two coordinates
+        GHRequest req = new GHRequest().
+                addPoint(new GHPoint(49.6724, 11.3494)).
+                addPoint(new GHPoint(49.6550, 11.4180));
+        // Set vehicle like car, bike, foot, ...
+        req.putHint("vehicle", "bike");
+        // Optionally enable/disable elevation in output PointList, currently bike and foot support elevation, default is false
+        req.putHint("elevation", false);
+        // Optionally enable/disable turn instruction information, defaults is true
+        req.putHint("instructions", true);
+        // Optionally enable/disable path geometry information, default is true
+        req.putHint("calc_points", true);
+        // note: turn off instructions and calcPoints if you just need the distance or time
+        // information to make calculation and transmission faster
+
+        // Optionally set specific locale for instruction information, supports already over 25 languages,
+        // defaults to English
+        req.setLocale(Locale.GERMAN);
+
+        GHResponse fullRes = gh.route(req);
+
+        if (fullRes.hasErrors())
+            throw new RuntimeException(fullRes.getErrors().toString());
+
+        // get best path (you will get more than one path here if you requested algorithm=alternative_route)
+        ResponsePath res = fullRes.getBest();
+        // get path geometry information (latitude, longitude and optionally elevation)
+        PointList pl = res.getPoints();
+        // distance of the full path, in meter
+        double distance = res.getDistance();
+        // time of the full path, in milliseconds
+        long millis = res.getTime();
+        // get information per turn instruction
+        InstructionList il = res.getInstructions();
+        for (Instruction i : il) {
+            // System.out.println(i.getName());
+        }
+    }
+
+    @Test
+    public void matrix() {
+        // Hint: create this thread safe instance only once in your application to allow the underlying library to cache the costly initial https handshake
+        GraphHopperMatrixWeb matrixClient = new GraphHopperMatrixWeb();
+        // for very large matrices you need:
+        // GraphHopperMatrixWeb matrixClient = new GraphHopperMatrixWeb(new GHMatrixBatchRequester());
+        matrixClient.setKey(apiKey);
+
+        GHMRequest ghmRequest = new GHMRequest();
+        ghmRequest.addOutArray("distances");
+        ghmRequest.addOutArray("times");
+        ghmRequest.putHint("vehicle", "car");
+
+        // init points for a symmetric matrix
+        // List<GHPoint> allPoints = Arrays.asList(new GHPoint(49.6724, 11.3494), new GHPoint(49.6550, 11.4180));
+        // ghmRequest.addAllPoints(allPoints);
+
+        // or init e.g. a one-to-many matrix:
+        ghmRequest.addFromPoint(new GHPoint(49.6724, 11.3494));
+        for (GHPoint to : Arrays.asList(new GHPoint(49.6724, 11.3494), new GHPoint(49.6550, 11.4180))) {
+            ghmRequest.addToPoint(to);
+        }
+
+        MatrixResponse response = matrixClient.route(ghmRequest);
+        if (response.hasErrors())
+            throw new RuntimeException(response.getErrors().toString());
+
+        // get time from first to second point:
+        // System.out.println(response.getTime(0, 1));
+    }
+}

core/files/changelog.txt

@@ -1,4 +1,5 @@
 3.0
+    default for GraphHopperMatrixWeb (client for Matrix API) is now the sync POST request without the artificial polling delay in most cases
     refactored TransportationMode to better reflect the usage in source data parsing only
     CustomWeighting requires LinkedHashMap throw exception if this is not provided
     removed Dockerfile