Rating: return null instead of crashing for invalid values

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Next release
+
+* When parsing a `Rating` with an unknown value, return `null` instead of throwing `ArrayIndexOutOfBoundsException`. Background: the Trakt API was seen returning `0` as a rating value.
+
 ## 6.20.0 - 2026-05-21
 
 * Add variants of watched methods that have an option to include special episodes. Deprecated the original variants.

src/main/java/com/uwetrottmann/trakt5/enums/Audio.java

@@ -16,6 +16,7 @@
 
 package com.uwetrottmann.trakt5.enums;
 
+import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -55,6 +56,7 @@ public enum Audio implements TraktEnum {
         }
     }
 
+    @Nullable
     public static Audio fromValue(String value) {
         return STRING_MAPPING.get(value);
     }

src/main/java/com/uwetrottmann/trakt5/enums/AudioChannels.java

@@ -16,6 +16,7 @@
 
 package com.uwetrottmann.trakt5.enums;
 
+import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -53,6 +54,7 @@ public enum AudioChannels implements TraktEnum {
         }
     }
 
+    @Nullable
     public static AudioChannels fromValue(String value) {
         return STRING_MAPPING.get(value);
     }

src/main/java/com/uwetrottmann/trakt5/enums/Hdr.java

@@ -16,6 +16,7 @@
 
 package com.uwetrottmann.trakt5.enums;
 
+import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -40,6 +41,7 @@ public enum Hdr implements TraktEnum {
         }
     }
 
+    @Nullable
     public static Hdr fromValue(String value) {
         return STRING_MAPPING.get(value);
     }

src/main/java/com/uwetrottmann/trakt5/enums/MediaType.java

@@ -16,6 +16,7 @@
 
 package com.uwetrottmann.trakt5.enums;
 
+import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -44,6 +45,7 @@ public enum MediaType implements TraktEnum {
         }
     }
 
+    @Nullable
     public static MediaType fromValue(String value) {
         return STRING_MAPPING.get(value);
     }

src/main/java/com/uwetrottmann/trakt5/enums/ProgressLastActivity.java

@@ -16,6 +16,7 @@
 
 package com.uwetrottmann.trakt5.enums;
 
+import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.Locale;
 import java.util.Map;
@@ -39,6 +40,7 @@ public enum ProgressLastActivity implements TraktEnum {
         }
     }
 
+    @Nullable
     public static ProgressLastActivity fromValue(String value) {
         return STRING_MAPPING.get(value.toUpperCase(Locale.ROOT));
     }

src/main/java/com/uwetrottmann/trakt5/enums/Rating.java

@@ -16,6 +16,8 @@
 
 package com.uwetrottmann.trakt5.enums;
 
+import javax.annotation.Nullable;
+
 public enum Rating implements TraktEnum {
 
     WEAKSAUCE(1),
@@ -29,14 +31,20 @@ public enum Rating implements TraktEnum {
     SUPERB(9),
     TOTALLYNINJA(10);
 
-    public int value;
+    public final int value;
 
     Rating(int value) {
         this.value = value;
     }
 
+    @Nullable
     public static Rating fromValue(int value) {
-        return Rating.values()[value - 1];
+        for (Rating rating : Rating.values()) {
+            if (rating.value == value) {
+                return rating;
+            }
+        }
+        return null; // Return null instead of an unknown enum value
     }
 
     @Override

src/main/java/com/uwetrottmann/trakt5/enums/Resolution.java

@@ -16,6 +16,7 @@
 
 package com.uwetrottmann.trakt5.enums;
 
+import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -44,6 +45,7 @@ public enum Resolution implements TraktEnum {
         }
     }
 
+    @Nullable
     public static Resolution fromValue(String value) {
         return STRING_MAPPING.get(value);
     }

src/main/java/com/uwetrottmann/trakt5/enums/Status.java

@@ -16,6 +16,7 @@
 
 package com.uwetrottmann.trakt5.enums;
 
+import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.Locale;
 import java.util.Map;
@@ -41,6 +42,7 @@ public enum Status implements TraktEnum {
         }
     }
 
+    @Nullable
     public static Status fromValue(String value) {
         return STRING_MAPPING.get(value.toUpperCase(Locale.ROOT));
     }

src/test/java/com/uwetrottmann/trakt5/enums/EnumTest.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2026 Uwe Trottmann <uwe@uwetrottmann.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.uwetrottmann.trakt5.enums;
+
+import org.junit.Test;
+
+import java.util.function.Function;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class EnumTest {
+
+    private static final String TEST_VALUE_INVALID = "invalid";
+
+    // Note: E extends TraktEnum is not technically necessary, but somewhat guarantees that toString is equal to value
+    private <E extends Enum<E> & TraktEnum> void testStringEnumFromValue(E[] values, Function<String, E> fromValue) {
+        for (E value : values) {
+            assertThat(fromValue.apply(value.toString())).isEqualTo(value);
+        }
+
+        assertThat(fromValue.apply(TEST_VALUE_INVALID)).isNull();
+    }
+
+    @Test
+    public void audio_fromValue() {
+        testStringEnumFromValue(Audio.values(), Audio::fromValue);
+    }
+
+    @Test
+    public void audioChannels_fromValue() {
+        testStringEnumFromValue(AudioChannels.values(), AudioChannels::fromValue);
+    }
+
+    @Test
+    public void hdr_fromValue() {
+        testStringEnumFromValue(Hdr.values(), Hdr::fromValue);
+    }
+
+    @Test
+    public void mediaType_fromValue() {
+        testStringEnumFromValue(MediaType.values(), MediaType::fromValue);
+    }
+
+    @Test
+    public void progressLastActivity_fromValue() {
+        testStringEnumFromValue(ProgressLastActivity.values(), ProgressLastActivity::fromValue);
+    }
+
+    @Test
+    public void rating_fromValue() {
+        Rating[] values = Rating.values();
+        for (Rating rating : values) {
+            assertThat(Rating.fromValue(rating.value)).isEqualTo(rating);
+        }
+
+        assertThat(Rating.fromValue(0)).isNull();
+        assertThat(Rating.fromValue(11)).isNull();
+    }
+
+    @Test
+    public void resolution_fromValue() {
+        testStringEnumFromValue(Resolution.values(), Resolution::fromValue);
+    }
+
+    @Test
+    public void status_fromValue() {
+        testStringEnumFromValue(Status.values(), Status::fromValue);
+    }
+}