+ * This record encapsulates the data for several endpoints that involves two {@code LngLatDto} + * and serves as the data contract for those API operation + * + * @param position1 Nested object of {@link LngLatDto} + * @param position2 Nested object of {@link LngLatDto} + */ public record DistanceRequestDto(LngLatDto position1, LngLatDto position2) { } diff --git a/src/main/java/io/github/js0ny/ilp_coursework/data/LngLatDto.java b/src/main/java/io/github/js0ny/ilp_coursework/data/LngLatDto.java index 95679e9..c3997ec 100644 --- a/src/main/java/io/github/js0ny/ilp_coursework/data/LngLatDto.java +++ b/src/main/java/io/github/js0ny/ilp_coursework/data/LngLatDto.java @@ -1,5 +1,11 @@ package io.github.js0ny.ilp_coursework.data; +/** + * Represents the data transfer object for a point or coordinate + * that defines by a longitude and latitude + * + * @param lng longitude of the coordinate/point + * @param lat latitude of the coordinate/point + */ public record LngLatDto(double lng, double lat) { - } diff --git a/src/main/java/io/github/js0ny/ilp_coursework/data/MovementRequestDto.java b/src/main/java/io/github/js0ny/ilp_coursework/data/MovementRequestDto.java index e9b87ab..ddfd5eb 100644 --- a/src/main/java/io/github/js0ny/ilp_coursework/data/MovementRequestDto.java +++ b/src/main/java/io/github/js0ny/ilp_coursework/data/MovementRequestDto.java @@ -2,7 +2,14 @@ package io.github.js0ny.ilp_coursework.data; /** * Represents the data transfer object for a movement action request. - * Used for endpoint: `/api/v1/nextPosition` + *
+ * This record encapsulates the data for endpoint /api/v1/nextPosition and serves as the data contract for + * this API operation + * + * @param start The starting coordinate of the movement + * @param angle The angle to movement in degree. This corresponds to compass directions. + * For example: 0 for East, 90 for North + * @see io.github.js0ny.ilp_coursework.controller.ApiController#getNextPosition(MovementRequestDto) */ public record MovementRequestDto(LngLatDto start, double angle) { } diff --git a/src/main/java/io/github/js0ny/ilp_coursework/data/RegionCheckRequestDto.java b/src/main/java/io/github/js0ny/ilp_coursework/data/RegionCheckRequestDto.java index aabf752..11ab0c3 100644 --- a/src/main/java/io/github/js0ny/ilp_coursework/data/RegionCheckRequestDto.java +++ b/src/main/java/io/github/js0ny/ilp_coursework/data/RegionCheckRequestDto.java @@ -1,5 +1,16 @@ package io.github.js0ny.ilp_coursework.data; +/** + * Represents the data transfer object for a region check request. + *
+ * This record encapsulates the data for endpoint /api/v1/isInRegion and serves as the data contract for + * this API operation + *
+ * + * @param position The coordinate to be checked + * @param region The region for the check. + * This is a nested object represented by {@link RegionDto} + * @see io.github.js0ny.ilp_coursework.controller.ApiController#getIsInRegion(RegionCheckRequestDto) + */ public record RegionCheckRequestDto(LngLatDto position, RegionDto region) { - } diff --git a/src/main/java/io/github/js0ny/ilp_coursework/data/RegionDto.java b/src/main/java/io/github/js0ny/ilp_coursework/data/RegionDto.java index 31c99ef..181899a 100644 --- a/src/main/java/io/github/js0ny/ilp_coursework/data/RegionDto.java +++ b/src/main/java/io/github/js0ny/ilp_coursework/data/RegionDto.java @@ -3,16 +3,40 @@ package io.github.js0ny.ilp_coursework.data; import java.util.List; import java.util.Objects; +/** + * Represents the data transfer object for a region definition + *
+ * This record encapsulates the data for calculating if a coordinate is inside the region + *
+ * A built-in method isClosedTo is defined to check this DTO is valid or not in the mean of closing polygon
+ *
+ * @param name The human-readable name for the region
+ * @param vertices list of coordinates that forms a polygon as a region.
+ *
+ * In order to define a valid region, the last element of the list should be the same as the first, or
+ * known as closed
+ * @see RegionCheckRequestDto
+ * @see io.github.js0ny.ilp_coursework.service.GpsCalculationService#checkIsInRegion(LngLatDto, RegionDto)
+ */
public record RegionDto(String name, List
+ * In this dto, edges + 1 vertices is required.
+ */
+ private static final int MINIMUM_VERTICES = 4;
+ /**
+ * Method to check if the region has a valid polygon by checking if the vertices forms a closed polygon
+ *
+ * @return {@code true} if the vertices are able to form a polygon and form a closed polygon
+ */
public boolean isClosed() {
- // Magic number 4: For a polygon, 3 edges is required.
- // In this dto, edges + 1 vertices is required.
- if (vertices == null || vertices.size() < 4) {
+ if (vertices == null || vertices.size() < MINIMUM_VERTICES) {
return false;
}
- LngLatDto first = vertices.get(0);
- LngLatDto last = vertices.get(vertices.size() - 1);
+ LngLatDto first = vertices.getFirst();
+ LngLatDto last = vertices.getLast();
return Objects.equals(last, first);
}
diff --git a/src/main/java/io/github/js0ny/ilp_coursework/exception/GlobalExceptionHandler.java b/src/main/java/io/github/js0ny/ilp_coursework/exception/GlobalExceptionHandler.java
index 0db8f12..0d54d23 100644
--- a/src/main/java/io/github/js0ny/ilp_coursework/exception/GlobalExceptionHandler.java
+++ b/src/main/java/io/github/js0ny/ilp_coursework/exception/GlobalExceptionHandler.java
@@ -25,10 +25,4 @@ public class GlobalExceptionHandler {
return Map.of("status", "400", "error", errorMessage);
}
- // @ExceptionHandler(NullPointerException.class)
- // @ResponseStatus(HttpStatus.BAD_REQUEST)
- // public Map