From 79db47459a9483424279d18801aa83d6f9a6a077 Mon Sep 17 00:00:00 2001 From: js0ny Date: Sat, 18 Oct 2025 21:38:02 +0100 Subject: [PATCH] doc: add javadoc to `*dto.java` --- .../data/DistanceRequestDto.java | 9 +++++ .../js0ny/ilp_coursework/data/LngLatDto.java | 8 ++++- .../data/MovementRequestDto.java | 9 ++++- .../data/RegionCheckRequestDto.java | 13 ++++++- .../js0ny/ilp_coursework/data/RegionDto.java | 34 ++++++++++++++++--- .../exception/GlobalExceptionHandler.java | 6 ---- 6 files changed, 65 insertions(+), 14 deletions(-) diff --git a/src/main/java/io/github/js0ny/ilp_coursework/data/DistanceRequestDto.java b/src/main/java/io/github/js0ny/ilp_coursework/data/DistanceRequestDto.java index e9956ea..7ba3f79 100644 --- a/src/main/java/io/github/js0ny/ilp_coursework/data/DistanceRequestDto.java +++ b/src/main/java/io/github/js0ny/ilp_coursework/data/DistanceRequestDto.java @@ -1,4 +1,13 @@ package io.github.js0ny.ilp_coursework.data; +/** + * Represents the data transfer object for a distance operation request. + *

+ * 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 vertices) { + /** + * Magic number 4: For a polygon, 3 edges is required. + *

+ * 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 handleNullPointerException(NullPointerException - // ex) { - // return Map.of("error", "Invalid JSON request body."); - // } }