Exclude waypoints from routing

[VysotskiVadim]

Description

Direction API provides a new feature "exclude waypoint". To exclude a coordinate form your route add it to the list of exclude like point(lon lat). For example if you want to exclude motorways and coordinate 1.0 1.0 use following exclude param: exclude=motorway,point(1.0%201.0)

You're reviewing a second iteration of the exclude waypoints implementation. First iteration is #1361.

[VysotskiVadim]

Attention ⚠️
How do you think, is that a logical breaking change? I have doubts about whether I need to filter out points from that filed. I think no. What do you think?

[LukasPaczos]

I wouldn't consider this a breaking change. It just reflects the state of the server-side API itself which wasn't considered breaking since the format is a generic string.

[Guardiola31337]

Overall is looking good @VysotskiVadim

Left some minor comments.

[Guardiola31337]

Why is this @Nullable?

[VysotskiVadim]

To let users cleanup the exclude.

  @Test
  public void cleanExcludes() {
    RouteOptions routeOptions = routeOptions().toBuilder()
        .excludeObject(null)
        .build();

    assertNull(routeOptions.exclude());
  }

[Guardiola31337]

I mean, if you don't want to include it you don't set it to RouteOptions right? Normally, fields added to a Builder are non-nullable.

[VysotskiVadim]

What if you build new route options from existing route options as on example ☝️

[Guardiola31337]

NIT Normally is good to structure the tests following the triple A 👀 https://speakerdeck.com/guardiola31337/elegant-unit-testing-mobilization-2016?slide=40 http://wiki.c2.com/?ArrangeActAssert

@Test
public void parseTwoPointsWithTwoCriteriaMixed() {
    // Arrange
    
    // Act
    
    // Assert
}

Note the empty lines between Arrange / Act and Act / Assert.

The same thing applies to the tests below 👇

[VysotskiVadim]

I agree, that AAA brings more clarity to tests. Sometimes tests are so complex that it's not easy to understand the border between setup and an act 🙂
I added empty lines to some tests from PR. But some of the tests I find too trivial and I'm not sure if highlighting of their AAA structure will bring some benefit. What do you think about AAA structure highlighting for trivial tests?

[Guardiola31337]

In such cases, I personally prefer to add it too, for consistency.

[LukasPaczos]

Let's remove these 2 cases and let the backend respond with an appropriate errors. We should only handle what we expect.

[LukasPaczos]

Sorry, now I see it's the other way around. Regardless, since the server-side API format is generic string, we cannot throw an exception on the parsing level ourselves. We probably need to remove that if-check.

[VysotskiVadim]

this line is about a case when you put a comma instead of the space in point

  @Test(expected = IllegalArgumentException.class)
  public void parsePointWithCommaDelimiter() {
    String invalidPoint = "point(5.0,7.0)";
    Exclude.fromUrlQueryParameter(invalidPoint);
  }

Do you suggest to ignore everything we can't parse? Like:

  @Test
  public void parsePointWithCommaDelimiter() {
    String invalidPoint = "point(5.0,7.0)";
    Exclude exclude = Exclude.fromUrlQueryParameter(invalidPoint);
    assertNull(exclude);
  }

[Guardiola31337]

Yeah, I agree with @LukasPaczos providing the right format should be managed by the end-user when integrating the API and check on the server side. I believe we should also remove the previous if #1362 (comment) If in the future Directions API adds new data formats for exclude, we'll accommodate YAGNI.

[VysotskiVadim]

@LukasPaczos , @Guardiola31337 , updated parsing with a new concept: Exclude is just a type-safe way of working with known excludes. All the unknown properties and flags are ignored now

[Guardiola31337]

Why even ignore it and return null from our side? Why can't we pass whatever we get from the client (assuming is well formed / formatted and let the server crash if not?

mapbox-java/services-directions-models/src/main/java/com/mapbox/api/directions/v5/models/Exclude.java

Line 184 in f2c3079

private static Point parsePointOrNull(String point) {

[VysotskiVadim]

@Guardiola31337 , the line 184 is for reading points, not for writing. You can write incorrect point like exclude("point(test)"), but you won't be able to read it as a Point because it can't be parsed

[VysotskiVadim]

Don't know any good solution for reusing an array between @StringDef and Exclude for validation. Please advice if you know 🙂

[LukasPaczos]

You could maybe iterate via available DirectionsCriteria fields using reflection and compare them against the array in the Exclude class. Not a blocker in my opinion.

[LukasPaczos]

You could maybe iterate via available DirectionsCriteria fields using reflection and compare them against the array in the Exclude class. Not a blocker in my opinion.