Add people support (#389)

README.md

@@ -101,8 +101,10 @@ RelatedAnime[] relatedAnime = anime.getRelatedAnime();
 AnimeRecommendation[] recs = anime.getRecommendations();
 OpeningTheme[] op = anime.getOpeningThemes();
 Video[] PV = anime.getVideos();
+List<Character> characters = anime.getCharacters().search();
 
 Character character = mal.getCharacter(61371);
+Person person = mal.getPerson(10765);
 ```
 
 <p align="right">(<a href="#top">back to top</a>)</p>

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>dev.katsute</groupId>
     <artifactId>mal4j</artifactId>
-    <version>3.1.1-SNAPSHOT</version>
+    <version>3.2.0-SNAPSHOT</version>
 
     <profiles>
         <profile>

readme.bbcode

@@ -54,8 +54,10 @@ RelatedAnime[] relatedAnime = anime.getRelatedAnime();
 AnimeRecommendation[] recs = anime.getRecommendations();
 OpeningTheme[] op = anime.getOpeningThemes();
 Video[] PV = anime.getVideos();
+List<Character> characters = anime.getCharacters().search();
 
 Character character = mal.getCharacter(61371);
+Person person = mal.getPerson(10765);
 [/code]
 
 [center][size=200][url=https://github.com/KatsuteDev/Mal4J#readme]View on GitHub[/url][/size][/center]

src/main/java/dev/katsute/mal4j/Fields.java

@@ -22,7 +22,7 @@
  * The fields class holds all possible fields for a request. Usable in any methods that ask for fields.
  *
  * @since 1.1.0
- * @version 3.1.0
+ * @version 3.2.0
  * @author Katsute
  */
 public abstract class Fields {
@@ -600,6 +600,41 @@ private Character(){}
         Character.animeography
     );
 
+    // person
+
+    /**
+     * All possible fields for a person.
+     *
+     * @see #people
+     * @since 3.2.0
+     */
+    public static class People {
+
+        private People(){}
+
+        public static final String first_name = "first_name";
+
+        public static final String last_name = "last_name";
+
+        public static final String birthday = "birthday";
+
+        public static final String main_picture = "main_picture";
+
+    }
+
+    /**
+     * Returns all people fields as a comma separated string.
+     *
+     * @see People
+     * @since 3.2.0
+     */
+    public static final String people = String.join(",",
+        People.first_name,
+        People.last_name,
+        People.birthday,
+        People.main_picture
+    );
+
     // user
 
     /**
@@ -625,7 +660,7 @@ private User(){ }
     }
 
     /**
-     * Returns all User fields as a comma separated string.
+     * Returns all user fields as a comma separated string.
      *
      * @see User
      * @since 1.1.0

src/main/java/dev/katsute/mal4j/MyAnimeList.java

@@ -28,6 +28,7 @@
 import dev.katsute.mal4j.manga.Manga;
 import dev.katsute.mal4j.manga.MangaRanking;
 import dev.katsute.mal4j.manga.property.MangaRankingType;
+import dev.katsute.mal4j.people.Person;
 import dev.katsute.mal4j.property.ExperimentalFeature;
 import dev.katsute.mal4j.query.*;
 import dev.katsute.mal4j.user.User;
@@ -45,7 +46,7 @@
  * </ul>
  *
  * @since 1.0.0
- * @version 3.1.0
+ * @version 3.2.0
  * @author Katsute
  */
 public abstract class MyAnimeList {
@@ -345,6 +346,33 @@ public static MyAnimeList withOAuth2(final MyAnimeListAuthenticator authenticato
      */
     public abstract Character getCharacter(final long id, final String... fields);
 
+// person
+
+    /**
+     * Returns a person.
+     *
+     * @param id person id
+     * @return person
+     *
+     * @see Person
+     * @see #getPerson(long, String...)
+     * @since 3.2.0
+     */
+    public abstract Person getPerson(final long id);
+
+    /**
+     * Returns a person.
+     *
+     * @param id person id
+     * @param fields a string array of the fields that should be returned
+     * @return person
+     *
+     * @see Person
+     * @see #getPerson(long)
+     * @since 3.2.0
+     */
+    public abstract Person getPerson(final long id, final String... fields);
+
 // forum board
 
     /**

src/main/java/dev/katsute/mal4j/MyAnimeListImpl.java

@@ -36,6 +36,7 @@
 import dev.katsute.mal4j.manga.MangaListStatus;
 import dev.katsute.mal4j.manga.MangaRanking;
 import dev.katsute.mal4j.manga.property.MangaRankingType;
+import dev.katsute.mal4j.people.Person;
 import dev.katsute.mal4j.property.ExperimentalFeature;
 import dev.katsute.mal4j.query.*;
 import dev.katsute.mal4j.user.User;
@@ -56,6 +57,7 @@
 import static dev.katsute.mal4j.MyAnimeListSchema_Character.*;
 import static dev.katsute.mal4j.MyAnimeListSchema_Forum.*;
 import static dev.katsute.mal4j.MyAnimeListSchema_Manga.*;
+import static dev.katsute.mal4j.MyAnimeListSchema_People.*;
 import static dev.katsute.mal4j.MyAnimeListSchema_User.*;
 
 final class MyAnimeListImpl extends MyAnimeList {
@@ -868,6 +870,24 @@ public final PaginatedIterator<MangaListStatus> searchAll(){
         };
     }
 
+    @Override
+    public final Person getPerson(final long id){
+        return getPerson(id, (String[]) null);
+    }
+
+    @Override
+    public final Person getPerson(final long id, final String... fields){
+        checkExperimentalFeatureEnabled(ExperimentalFeature.PEOPLE);
+        return asPerson(this, handleResponse(
+            () -> service.getPerson(
+                isTokenAuth ? token : null,
+                !isTokenAuth ? client_id : null,
+                id,
+                convertFields(Fields.people, fields)
+            )
+        ));
+    }
+
     @Override
     public final User getAuthenticatedUser(){
         return getUser("@me", (String[]) null);

src/main/java/dev/katsute/mal4j/MyAnimeListSchema_Character.java

@@ -25,7 +25,7 @@
 
 import java.util.Arrays;
 
-@SuppressWarnings({"unused", "SpellCheckingInspection"})
+@SuppressWarnings("SpellCheckingInspection")
 abstract class MyAnimeListSchema_Character extends MyAnimeListSchema {
 
     static Character asCharacter(final MyAnimeList mal, final JsonObject schema){

src/main/java/dev/katsute/mal4j/MyAnimeListSchema_People.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright (C) 2023 Katsute <https://github.com/Katsute>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+package dev.katsute.mal4j;
+
+import dev.katsute.mal4j.Json.JsonObject;
+import dev.katsute.mal4j.people.Person;
+import dev.katsute.mal4j.property.Picture;
+
+import java.util.Date;
+
+abstract class MyAnimeListSchema_People extends MyAnimeListSchema {
+
+    static Person asPerson(final MyAnimeList mal, final JsonObject schema){
+        return schema == null ? null : new Person(){
+
+            private final Long id = schema.getLong("id");
+
+            private final String firstName    = schema.getString("first_name");
+            private final String lastName     = schema.getString("last_name");
+            private final Long birthday       = parseDate(schema.getString("birthday"));
+            private final Picture mainPicture = MyAnimeListSchema_Common.asPicture(mal, schema.getJsonObject("main_picture"));
+
+            @Override
+            public final Long getID(){
+                return id;
+            }
+
+            @Override
+            public final String getFirstName(){
+                return firstName;
+            }
+
+            @Override
+            public final String getLastName(){
+                return lastName;
+            }
+
+            @Override
+            public final Date getBirthday(){
+                return birthday == null ? null : new Date(birthday);
+            }
+
+            @Override
+            public final Picture getMainPicture(){
+                return mainPicture;
+            }
+
+            // additional methods
+
+            @Override
+            public final String toString(){
+                return "Person{" +
+                       "id=" + id +
+                       ", firstName='" + firstName + '\'' +
+                       ", lastName='" + lastName + '\'' +
+                       ", birthday=" + birthday +
+                       ", mainPicture=" + mainPicture +
+                       '}';
+            }
+
+        };
+    }
+
+}

src/main/java/dev/katsute/mal4j/MyAnimeListService.java

@@ -255,6 +255,16 @@ Response<JsonObject> getUserMangaListing(
         @Query("nsfw")                              final Boolean nsfw
     );
 
+    // people
+
+    @Endpoint(method="GET", value="people/{person_id}")
+    Response<JsonObject> getPerson(
+        @Header("Authorization")                    final String token,
+        @Header("X-MAL-CLIENT-ID")                  final String client_id,
+        @Path(value = "person_id")                  final Long person_id,
+        @Query(value = "fields", encoded = true)    final String fields
+    );
+
     // user
 
     @Endpoint(method="GET", value="users/{user_name}")

src/main/java/dev/katsute/mal4j/people/Person.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright (C) 2023 Katsute <https://github.com/Katsute>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+package dev.katsute.mal4j.people;
+
+import dev.katsute.mal4j.property.ID;
+import dev.katsute.mal4j.property.Picture;
+
+import java.util.Date;
+
+/**
+ * Represents a person.
+ *
+ * @since 3.2.0
+ * @version 3.2.0
+ * @author Katsute
+ */
+public abstract class Person implements ID {
+
+    /**
+     * Returns the first name.
+     *
+     * @return first name
+     *
+     * @see #getLastName()
+     * @since 3.2.0
+     */
+    public abstract String getFirstName();
+
+    /**
+     * Returns the last name.
+     *
+     * @return last name
+     *
+     * @see #getFirstName()
+     * @since 3.2.0
+     */
+    public abstract String getLastName();
+
+    /**
+     * Returns the birthday.
+     *
+     * @return birthday
+     *
+     * @since 3.2.0
+     */
+    public abstract Date getBirthday();
+
+    /**
+     * Returns the main picture.
+     *
+     * @return main picture
+     *
+     * @see Picture
+     * @since 3.2.0
+     */
+    public abstract Picture getMainPicture();
+
+}

src/main/java/dev/katsute/mal4j/people/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Contains {@link dev.katsute.mal4j.people.Person} classes.
+ */
+package dev.katsute.mal4j.people;

src/main/java/dev/katsute/mal4j/property/ExperimentalFeature.java

@@ -26,7 +26,7 @@
  *
  * @see dev.katsute.mal4j.MyAnimeList#enableExperimentalFeature(ExperimentalFeature)
  * @since 2.3.0
- * @version 3.1.0
+ * @version 3.2.0
  * @author Katsute
  */
 public enum ExperimentalFeature {
@@ -62,6 +62,12 @@ public enum ExperimentalFeature {
      * @see dev.katsute.mal4j.MyAnimeList#getCharacter(long)
      * @see dev.katsute.mal4j.MyAnimeList#getCharacter(long, String...)
      */
-    CHARACTERS
+    CHARACTERS,
+
+    /**
+     * @see dev.katsute.mal4j.MyAnimeList#getPerson(long)
+     * @see dev.katsute.mal4j.MyAnimeList#getPerson(long, String...)
+     */
+    PEOPLE;
 
 }