feat: add api client for brouter

Author: derklaro

external-api-client/src/main/java/tools/simrail/backend/external/FeignClientProvider.java

@@ -37,12 +37,13 @@
 import feign.ExceptionPropagationPolicy;
 import feign.Feign;
 import feign.Logger;
-import feign.http2client.Http2Client;
 import feign.jackson.JacksonDecoder;
 import feign.jackson.JacksonEncoder;
 import feign.slf4j.Slf4jLogger;
 import java.util.Set;
 import org.jetbrains.annotations.NotNull;
+import tools.simrail.backend.external.feign.CustomFieldQueryMapEncoder;
+import tools.simrail.backend.external.feign.FeignJava11Client;
 
 public final class FeignClientProvider {
 
@@ -56,9 +57,10 @@ private FeignClientProvider() {
   public static @NotNull Feign.Builder prepareFeignInstance() {
     var callingClass = CLASS_REF_RETAINING_STACK_WALKER.getCallerClass();
     return Feign.builder()
-      .client(new Http2Client())
       .logLevel(Logger.Level.FULL)
+      .client(new FeignJava11Client())
       .logger(new Slf4jLogger(callingClass))
+      .queryMapEncoder(new CustomFieldQueryMapEncoder())
       .exceptionPropagationPolicy(ExceptionPropagationPolicy.NONE);
   }
 
@@ -81,11 +83,12 @@ private FeignClientProvider() {
     // create base feign instance
     var callingClass = CLASS_REF_RETAINING_STACK_WALKER.getCallerClass();
     return Feign.builder()
-      .client(new Http2Client())
       .logLevel(Logger.Level.FULL)
+      .client(new FeignJava11Client())
       .logger(new Slf4jLogger(callingClass))
       .encoder(new JacksonEncoder(bodyMapper))
       .decoder(new JacksonDecoder(bodyMapper))
+      .queryMapEncoder(new CustomFieldQueryMapEncoder())
       .exceptionPropagationPolicy(ExceptionPropagationPolicy.NONE);
   }
 }

external-api-client/src/main/java/tools/simrail/backend/external/brouter/BRouterApiClient.java

@@ -0,0 +1,50 @@
+/*
+ * This file is part of simrail-tools-backend, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) 2024-2025 Pasqual Koschmieder and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package tools.simrail.backend.external.brouter;
+
+import feign.QueryMap;
+import feign.RequestLine;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+import tools.simrail.backend.external.FeignClientProvider;
+import tools.simrail.backend.external.brouter.request.BRouterRouteRequest;
+
+public interface BRouterApiClient {
+
+  @Contract("-> new")
+  static @NotNull BRouterApiClient create() {
+    return FeignClientProvider.prepareFeignInstance()
+      .target(BRouterApiClient.class, "https://brouter.de");
+  }
+
+  /**
+   * Requests the routing along the given waypoints.
+   *
+   * @param request the request holding the routing options.
+   * @return a stream of the routing output data.
+   */
+  @RequestLine("GET /brouter")
+  String route(@QueryMap BRouterRouteRequest request);
+}

external-api-client/src/main/java/tools/simrail/backend/external/brouter/feign/BRouterAlternativeModeExpander.java

@@ -0,0 +1,41 @@
+/*
+ * This file is part of simrail-tools-backend, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) 2024-2025 Pasqual Koschmieder and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package tools.simrail.backend.external.brouter.feign;
+
+import feign.Param;
+import org.jetbrains.annotations.NotNull;
+import tools.simrail.backend.external.brouter.request.BRouterRouteRequest;
+
+/**
+ * Expander for the alternative routing mode.
+ */
+public final class BRouterAlternativeModeExpander implements Param.Expander {
+
+  @Override
+  public @NotNull String expand(@NotNull Object value) {
+    var mode = (BRouterRouteRequest.AlternativeMode) value;
+    return Integer.toString(mode.ordinal());
+  }
+}

external-api-client/src/main/java/tools/simrail/backend/external/brouter/feign/BRouterLonLatExpander.java

@@ -0,0 +1,50 @@
+/*
+ * This file is part of simrail-tools-backend, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) 2024-2025 Pasqual Koschmieder and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package tools.simrail.backend.external.brouter.feign;
+
+import feign.Param;
+import java.util.List;
+import java.util.StringJoiner;
+import org.jetbrains.annotations.NotNull;
+import tools.simrail.backend.external.brouter.request.BRouterRouteRequest;
+
+/**
+ * Param expander for a list of geo positions.
+ */
+public final class BRouterLonLatExpander implements Param.Expander {
+
+  @Override
+  @SuppressWarnings("unchecked")
+  public @NotNull String expand(@NotNull Object value) {
+    var positionsJoiner = new StringJoiner("|");
+    var positionsList = (List<BRouterRouteRequest.GeoPosition>) value;
+    for (var position : positionsList) {
+      var formattedPosition = String.format("%s,%s", position.longitude(), position.latitude());
+      positionsJoiner.add(formattedPosition);
+    }
+
+    return positionsJoiner.toString();
+  }
+}

external-api-client/src/main/java/tools/simrail/backend/external/brouter/feign/BRouterOutputFormatExpander.java

@@ -0,0 +1,45 @@
+/*
+ * This file is part of simrail-tools-backend, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) 2024-2025 Pasqual Koschmieder and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package tools.simrail.backend.external.brouter.feign;
+
+import feign.Param;
+import org.jetbrains.annotations.NotNull;
+import tools.simrail.backend.external.brouter.request.BRouterRouteRequest;
+
+/**
+ * Expander for the output format of a routing request.
+ */
+public final class BRouterOutputFormatExpander implements Param.Expander {
+
+  @Override
+  public @NotNull String expand(@NotNull Object value) {
+    var format = (BRouterRouteRequest.OutputFormat) value;
+    return switch (format) {
+      case GPX -> "gpx";
+      case KML -> "kml";
+      case GEOJSON -> "geojson";
+    };
+  }
+}

external-api-client/src/main/java/tools/simrail/backend/external/brouter/request/BRouterRouteRequest.java

@@ -0,0 +1,118 @@
+/*
+ * This file is part of simrail-tools-backend, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) 2024-2025 Pasqual Koschmieder and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package tools.simrail.backend.external.brouter.request;
+
+import feign.Param;
+import java.util.List;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.With;
+import tools.simrail.backend.external.brouter.feign.BRouterAlternativeModeExpander;
+import tools.simrail.backend.external.brouter.feign.BRouterLonLatExpander;
+import tools.simrail.backend.external.brouter.feign.BRouterOutputFormatExpander;
+
+@Data
+@With
+@AllArgsConstructor
+@NoArgsConstructor(staticName = "create")
+public final class BRouterRouteRequest {
+
+  /**
+   * The positions of the waypoints on the route.
+   */
+  @Param(value = "lonlats", expander = BRouterLonLatExpander.class)
+  private List<GeoPosition> positions;
+
+  /**
+   * The profile to use for routing.
+   */
+  @Param(value = "profile")
+  private String profile;
+
+  /**
+   * The alternative routing engine to use for the request.
+   */
+  @Param(value = "alternativeidx", expander = BRouterAlternativeModeExpander.class)
+  private AlternativeMode alternativeMode = AlternativeMode.DEFAULT;
+
+  /**
+   * The format to return the data in.
+   */
+  @Param(value = "format", expander = BRouterOutputFormatExpander.class)
+  private OutputFormat outputFormat = OutputFormat.GEOJSON;
+
+  /**
+   * A geo position.
+   *
+   * @param latitude  the latitude of the position.
+   * @param longitude the longitude of the position.
+   */
+  public record GeoPosition(double latitude, double longitude) {
+
+  }
+
+  /**
+   * The output format of the routing data.
+   */
+  public enum OutputFormat {
+
+    /**
+     * Output the data in Keyhole Markup Language.
+     */
+    KML,
+    /**
+     * Output the data in GPS Exchange Format.
+     */
+    GPX,
+    /**
+     * Output the data in GeoJson format.
+     */
+    GEOJSON,
+  }
+
+  /**
+   * Which alternative routing mode to use.
+   */
+  public enum AlternativeMode {
+
+    /**
+     * Default routing engine.
+     */
+    DEFAULT,
+    /**
+     * First alternative routing engine.
+     */
+    FIRST_ALTERNATIVE,
+    /**
+     * Second alternative routing engine.
+     */
+    SECOND_ALTERNATIVE,
+    /**
+     * Third alternative routing engine.
+     */
+    THIRD_ALTERNATIVE,
+  }
+}