diff --git a/src/main/java/me/goudham/APIWrapper.java b/src/main/java/me/goudham/APIWrapper.java index 56c5ad3..a7fca8a 100644 --- a/src/main/java/me/goudham/APIWrapper.java +++ b/src/main/java/me/goudham/APIWrapper.java @@ -11,6 +11,7 @@ import me.goudham.domain.waifu.WaifuImage; import me.goudham.exception.APIMapperException; import me.goudham.exception.APIResponseException; import me.goudham.util.Season; +import me.goudham.util.WaifuListType; import java.io.IOException; import java.net.URI; @@ -91,86 +92,239 @@ public class APIWrapper { } } + /** + * Retrieve detailed information about the {@link Waifu} by sending request to API + * + * @param waifuId The id of the {@link Waifu} + * @return {@link Response} of {@link Waifu} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response getWaifu(String waifuId) throws APIResponseException, APIMapperException { Result waifuResult = sendRequest("waifu/" + waifuId); return apiMapper.deserialize(waifuResult, Waifu.class); } + /** + * Retrieve paginated images from the gallery, in sets of 10, by sending request to API + * + * @param waifuId The id of the {@link Waifu} + * @param pageNum The page number of the gallery + * @return {@link Response} of {@link WaifuImage} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getWaifuImages(String waifuId, String pageNum) throws APIResponseException, APIMapperException { Result waifuImagesResult = sendRequest("waifu/" + waifuId + "/images?page=" + pageNum); return apiMapper.deserializeToPaginationData(waifuImagesResult, paginationData(WaifuImage.class)); } + /** + * Retrieve an array of {@link FilteredWaifu}'s, sorted alphabetically, by sending request to API + * + * @param pageNum The page number of the gallery + * @return {@link Response} of {@link PaginationData} with {@link FilteredWaifu} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getWaifusByPage(String pageNum) throws APIResponseException, APIMapperException { Result waifusByPageResult = sendRequest("waifu?page=" + pageNum); return apiMapper.deserializeToPaginationData(waifusByPageResult, paginationData(FilteredWaifu.class)); } + /** + * Retrieve the Waifu of the Day by sending request to API + * + * @return {@link Response} of {@link FilteredWaifu} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response getDailyWaifu() throws APIResponseException, APIMapperException { Result dailyWaifuResult = sendRequest("meta/daily"); return apiMapper.deserialize(dailyWaifuResult, FilteredWaifu.class); } + /** + * Retrieve a Random Waifu from the Website by sending request to API + * + * @return {@link Response} of {@link FilteredWaifu} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response getRandomWaifu() throws APIResponseException, APIMapperException { Result randomWaifuResult = sendRequest("meta/random"); return apiMapper.deserialize(randomWaifuResult, FilteredWaifu.class); } + /** + * Retrieve a List of Currently Airing Anim by sending request to API + * + * @return {@link Response} of {@link List} with {@link FilteredSeries} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getSeasonalAnime() throws APIResponseException, APIMapperException { Result seasonalAnimeResult = sendRequest("airing"); return apiMapper.deserializeToList(seasonalAnimeResult, listOf(FilteredSeries.class)); } + /** + * Retrieve the Best Waifus of the Current Season by sending request to API + * + * @return {@link Response} of {@link List} with {@link FilteredWaifu} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getBestWaifus() throws APIResponseException, APIMapperException { Result waifuResults = sendRequest("airing/best"); return apiMapper.deserializeToList(waifuResults, listOf(FilteredWaifu.class)); } + /** + * Retrieve a List of Popular Waifus (Raw Count of Total Votes) of the Current Season + * by sending request to API + * + * @return {@link Response} of {@link List} with {@link FilteredWaifu} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getPopularWaifus() throws APIResponseException, APIMapperException { Result waifuResults = sendRequest("airing/popular"); return apiMapper.deserializeToList(waifuResults, listOf(FilteredWaifu.class)); } + /** + * Retrieve the Most Disliked Waifus of the Current Season by sending request to API + * + * @return {@link Response} of {@link List} with {@link FilteredWaifu} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getTrashWaifus() throws APIResponseException, APIMapperException { Result waifuResults = sendRequest("airing/trash"); return apiMapper.deserializeToList(waifuResults, listOf(FilteredWaifu.class)); } + /** + * Retrieve detailed information about a given {@link Series} by sending request to API + * + * @param seriesId The id of the {@link Series} + * @return {@link Response} of {@link Series} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response getSeries(String seriesId) throws APIResponseException, APIMapperException { Result seriesResult = sendRequest("series/" + seriesId); return apiMapper.deserialize(seriesResult, Series.class); } + /** + * Retrieve paginated information about a Series by sending request to API + * + * @param pageNum The page number of the gallery + * @return {@link Response} of {@link PaginationData} with {@link FilteredSeries} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getSeriesByPage(String pageNum) throws APIResponseException, APIMapperException { Result seriesPageResult = sendRequest("series?page=" + pageNum); return apiMapper.deserializeToPaginationData(seriesPageResult, paginationData(FilteredSeries.class)); } + /** + * Retrieve the List of Anime that Aired in a given Season and Year by sending request to API + * + * @param season The specified season from {@link Season} + * @param year The specified year + * @return {@link Response} of {@link List} with {@link FilteredSeries} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getAllSeries(Season season, Integer year) throws APIResponseException, APIMapperException { Result allSeriesResult = sendRequest("airing/" + season.getSeason() + "/" + year); return apiMapper.deserializeToList(allSeriesResult, listOf(FilteredSeries.class)); } + /** + * Retrieve a set of Waifus for a given {@link Series} by sending request to API + * + * @param seriesId The id of the {@link Series} + * @return {@link Response} of {@link List} with {@link FilteredWaifu} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getSeriesWaifus(String seriesId) throws APIResponseException, APIMapperException { Result allWaifusFromSeriesResults = sendRequest("series/" + seriesId + "/waifus"); return apiMapper.deserializeToList(allWaifusFromSeriesResults, listOf(FilteredWaifu.class)); } + /** + * Retrieve information about the {@link User} by sending request to API + * + * @param userId The id of the {@link User} + * @return {@link Response} of {@link User} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response getUserProfile(String userId) throws APIResponseException, APIMapperException { Result userProfileResult = sendRequest("user/" + userId); return apiMapper.deserialize(userProfileResult, User.class); } + /** + * Retrieve the Waifus Created, Liked, or Trashed for the given {@link User} id by sending request to API + * + * @param userId The id of the {@link User} + * @param listType The specified action E.g {@link WaifuListType#LIKED} + * @param pageNum The page number of the gallery + * @return {@link Response} of {@link PaginationData} with {@link FilteredWaifu} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getUserWaifus(String userId, String listType, String pageNum) throws APIResponseException, APIMapperException { Result userWaifusResult = sendRequest("user/" + userId + "/" + listType + "?page=" + pageNum); return apiMapper.deserializeToPaginationData(userWaifusResult, paginationData(FilteredWaifu.class)); } + /** + * Retrieve a List of all {@link UserList}'s shown by sending request to API + * + * @param userId The id of the {@link User} + * @return {@link Response} of {@link List} with {@link UserList} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response> getUserLists(String userId) throws APIResponseException, APIMapperException { Result userProfileResult = sendRequest("user/" + userId + "/lists"); return apiMapper.deserializeToList(userProfileResult, listOf(UserList.class)); } + /** + * Retrieve the Specific {@link UserList}, with {@link Waifu}'s by sending request to API + * + * @param userId The id of the {@link User} + * @param listId The id of the {@link UserList} + * @return {@link Response} of {@link UserList} + * @throws APIResponseException If {@link APIWrapper} could not return information properly + * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model + * + */ Response getUserList(String userId, String listId) throws APIResponseException, APIMapperException { Result userProfileResult = sendRequest("user/" + userId + "/lists/" + listId); return apiMapper.deserialize(userProfileResult, UserList.class);