feat: return custom exceptions

Author: nicholasM95

README.md

@@ -16,7 +16,7 @@ Add the Maven Dependency to your `pom.xml`
 <dependency>
     <groupId>be.nicholasmeyers</groupId>
     <artifactId>skoda-api-client</artifactId>
-    <version>1.1.0</version>
+    <version>1.2.0</version>
 </dependency>
 ```
 

src/main/java/be/nicholasmeyers/skoda/api/client/CarService.java

@@ -61,7 +61,7 @@ public CarService(String email, String password) {
      *
      * @param vin The VIN of the car.
      * @return A {@link CarCoolingInfo} object containing the cooling information of the car.
-     * @throws RuntimeException If an error occurs while retrieving the cooling status.
+     * @throws CarServiceException If an error occurs while retrieving the cooling status.
      */
     public CarCoolingInfo getCooling(String vin) {
         try {
@@ -71,7 +71,7 @@ public CarCoolingInfo getCooling(String vin) {
                     cooling.getClimatisationDuration(), cooling.getStartMode(), cooling.getHeaterMode(), mapToCarReport(cooling.getReport()),
                     cooling.getTimers().stream().map(this::mapToCarCoolingTimer).toList());
         } catch (ApiException e) {
-            throw new RuntimeException(e);
+            throw new CarServiceException("Failed to get cooling information", e.getMessage());
         }
     }
 
@@ -81,11 +81,11 @@ public CarCoolingInfo getCooling(String vin) {
      * @param vin      The VIN of the car.
      * @param duration The duration to flash the lights (in seconds).
      * @return The status of the request.
-     * @throws RuntimeException If the duration exceeds the maximum allowed or if an error occurs.
+     * @throws CarServiceException If the duration exceeds the maximum allowed or if an error occurs.
      */
     public String flash(String vin, Integer duration) {
         if (duration > 30) {
-            throw new RuntimeException("maximum duration is 30");
+            throw new CarServiceException("Failed to flash lights", "duration limit exceeded, max 30 minutes");
         }
         CarLocation location = getLocation(vin);
         FlashWebRequestResource flashWebRequestResource = new FlashWebRequestResource();
@@ -96,7 +96,7 @@ public String flash(String vin, Integer duration) {
         try {
             return flashApi.flash(vin, flashWebRequestResource).getStatus();
         } catch (ApiException e) {
-            throw new RuntimeException(e);
+            throw new CarServiceException("Failed to flash lights", e.getMessage());
         }
     }
 
@@ -106,11 +106,11 @@ public String flash(String vin, Integer duration) {
      * @param vin      The VIN of the car.
      * @param duration The duration to honk the horn (in seconds).
      * @return The status of the request.
-     * @throws RuntimeException If the duration exceeds the maximum allowed or if an error occurs.
+     * @throws CarServiceException If the duration exceeds the maximum allowed or if an error occurs.
      */
     public String honk(String vin, Integer duration) {
         if (duration > 30) {
-            throw new RuntimeException("maximum duration is 30");
+            throw new CarServiceException("Failed to honk horn", "duration limit exceeded, max 30 minutes");
         }
         CarLocation location = getLocation(vin);
         HonkWebRequestResource honkWebRequestResource = new HonkWebRequestResource();
@@ -121,7 +121,7 @@ public String honk(String vin, Integer duration) {
         try {
             return honkApi.honk(vin, honkWebRequestResource).getStatus();
         } catch (ApiException e) {
-            throw new RuntimeException(e);
+            throw new CarServiceException("Failed to honk horn", e.getMessage());
         }
     }
 
@@ -131,14 +131,14 @@ public String honk(String vin, Integer duration) {
      * @param vin The VIN of the car.
      * @param id  The id of the request.
      * @return The status of the request.
-     * @throws RuntimeException If an error occurs while retrieving the request status.
+     * @throws CarServiceException If an error occurs while retrieving the request status.
      */
     public String getRequest(String vin, String id) {
         try {
             RequestWebResponseResource request = requestApi.getRequest(vin, id);
             return request.getStatus();
         } catch (ApiException e) {
-            throw new RuntimeException(e);
+            throw new CarServiceException("Failed to get request", e.getMessage());
         }
     }
 
@@ -147,14 +147,14 @@ public String getRequest(String vin, String id) {
      *
      * @param vin The VIN of the car.
      * @return A {@link CarStatus} object containing the status information of the car.
-     * @throws RuntimeException If an error occurs while retrieving the car status.
+     * @throws CarServiceException If an error occurs while retrieving the car status.
      */
     public CarStatus getStatus(String vin) {
         try {
             StatusWebResponseResource status = statusApi.getStatus(vin);
             return new CarStatus(status.getVin(), status.getData().stream().map(this::mapToCarData).toList());
         } catch (ApiException e) {
-            throw new RuntimeException(e);
+            throw new CarServiceException("Failed to get status", e.getMessage());
         }
     }
 
@@ -165,11 +165,11 @@ public CarStatus getStatus(String vin) {
      * @param pin      The pin used to authenticate the ventilator action.
      * @param duration The duration to run the ventilator (in seconds).
      * @return The ventilator status ID.
-     * @throws RuntimeException If the duration exceeds the maximum allowed or if an error occurs.
+     * @throws CarServiceException If the duration exceeds the maximum allowed or if an error occurs.
      */
     public String startVentilator(String vin, String pin, Integer duration) {
         if (duration > 30) {
-            throw new RuntimeException("maximum duration is 30");
+            throw new CarServiceException("Failed to start ventilator", "duration limit exceeded, max 30 minutes");
         }
 
         VentilatorWebRequestResource ventilatorWebRequestResource = new VentilatorWebRequestResource();
@@ -180,7 +180,7 @@ public String startVentilator(String vin, String pin, Integer duration) {
             VentilatorWebResponseResource ventilatorStatus = ventilatorApi.startVentilator(vin, ventilatorWebRequestResource);
             return ventilatorStatus.getId();
         } catch (ApiException e) {
-            throw new RuntimeException(e);
+            throw new CarServiceException("Failed to start ventilator",  e.getMessage());
         }
     }
 
@@ -190,7 +190,7 @@ public String startVentilator(String vin, String pin, Integer duration) {
      * @param vin The VIN of the car.
      * @param pin The pin used to authenticate the ventilator action.
      * @return The ventilator status ID.
-     * @throws RuntimeException If an error occurs while stopping the ventilator.
+     * @throws CarServiceException If an error occurs while stopping the ventilator.
      */
     public String stopVentilator(String vin, String pin) {
         VentilatorWebRequestResource ventilatorWebRequestResource = new VentilatorWebRequestResource();
@@ -201,7 +201,7 @@ public String stopVentilator(String vin, String pin) {
             VentilatorWebResponseResource ventilatorStatus = ventilatorApi.stopVentilator(vin, ventilatorWebRequestResource);
             return ventilatorStatus.getId();
         } catch (ApiException e) {
-            throw new RuntimeException(e);
+            throw new CarServiceException("Failed to stop ventilator",  e.getMessage());
         }
     }
 
@@ -210,14 +210,14 @@ public String stopVentilator(String vin, String pin) {
      *
      * @param vin The VIN of the car.
      * @return A {@link CarLocation} object representing the car's location.
-     * @throws RuntimeException If an error occurs while retrieving the car location.
+     * @throws CarServiceException If an error occurs while retrieving the car location.
      */
     public CarLocation getLocation(String vin) {
         try {
             LocationWebResponseResource location = locationApi.getLocation(vin);
             return new CarLocation(location.getLatitude(), location.getLongitude());
         } catch (ApiException e) {
-            throw new RuntimeException(e);
+            throw new CarServiceException("Failed to get car location",  e.getMessage());
         }
     }
 

src/main/java/be/nicholasmeyers/skoda/api/client/CarServiceException.java

@@ -0,0 +1,34 @@
+package be.nicholasmeyers.skoda.api.client;
+
+/**
+ * Exception thrown to indicate a failure during car service operations.
+ * <p>
+ * This exception provides both a user-friendly message and the original message
+ * from a lower-level service or component, allowing for more detailed diagnostics.
+ * </p>
+ */
+public class CarServiceException extends RuntimeException {
+
+    private final String originalMessage;
+
+    /**
+     * Constructs a new {@code CarServiceException} with the specified detail message
+     * and the original message from the source of the error.
+     *
+     * @param message         a user-friendly message describing the exception
+     * @param originalMessage the original message from the underlying system or service
+     */
+    public CarServiceException(String message, String originalMessage) {
+        super(message);
+        this.originalMessage = originalMessage;
+    }
+
+    /**
+     * Returns the original message from the underlying system or service that caused the exception.
+     *
+     * @return the original error message
+     */
+    public String getOriginalMessage() {
+        return originalMessage;
+    }
+}