Add chat pagination management classes for improved user experience

Author: mzcydev

src/main/java/gg/nextforge/pagination/Pagination.java

@@ -0,0 +1,98 @@
+package gg.nextforge.pagination;
+
+import gg.nextforge.pagination.model.Page;
+import lombok.Getter;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * A utility class for managing pagination of a list of items.
+ * This class provides methods to divide a list of items into pages
+ * and retrieve specific pages based on the index.
+ *
+ * @param <T> the type of items to be paginated
+ */
+public class Pagination<T> {
+
+    // The list of items to be paginated
+    private final List<T> items = new ArrayList<>();
+    // The number of items per page
+    @Getter
+    private final int itemsPerPage;
+
+    /**
+     * Constructs a Pagination object with the specified number of items per page.
+     *
+     * @param itemsPerPage the number of items per page; must be greater than 0
+     * @throws IllegalArgumentException if itemsPerPage is less than or equal to 0
+     */
+    public Pagination(int itemsPerPage) {
+        if (itemsPerPage <= 0) throw new IllegalArgumentException("itemsPerPage must be > 0");
+        this.itemsPerPage = itemsPerPage;
+    }
+
+    /**
+     * Adds a single item to the pagination.
+     *
+     * @param item the item to add
+     */
+    public void addItem(T item) {
+        items.add(item);
+    }
+
+    /**
+     * Adds a list of items to the pagination.
+     *
+     * @param elements the list of items to add
+     */
+    public void addAll(List<T> elements) {
+        items.addAll(elements);
+    }
+
+    /**
+     * Retrieves a specific page of items based on the given index.
+     *
+     * @param index the index of the page to retrieve (0-based)
+     * @return a {@link Page} object containing the items for the specified page
+     * or an empty page if the index is out of bounds
+     */
+    public Page<T> getPage(int index) {
+        int totalPages = getTotalPages();
+        if (index < 0 || index >= totalPages) return new Page<>(index, totalPages, Collections.emptyList());
+
+        int start = index * itemsPerPage;
+        int end = Math.min(start + itemsPerPage, items.size());
+
+        List<T> sublist = items.subList(start, end);
+        return new Page<>(index, totalPages, new ArrayList<>(sublist));
+    }
+
+    /**
+     * Calculates the total number of pages based on the number of items and items per page.
+     *
+     * @return the total number of pages
+     */
+    public int getTotalPages() {
+        return (int) Math.ceil((double) items.size() / itemsPerPage);
+    }
+
+    /**
+     * Returns the total number of items in the pagination.
+     *
+     * @return the total number of items
+     */
+    public int getTotalItems() {
+        return items.size();
+    }
+
+    /**
+     * Checks if the pagination contains no items.
+     *
+     * @return true if there are no items, false otherwise
+     */
+    public boolean isEmpty() {
+        return items.isEmpty();
+    }
+}

src/main/java/gg/nextforge/pagination/chat/ChatPaginatorManager.java

@@ -0,0 +1,56 @@
+package gg.nextforge.pagination.chat;
+
+import gg.nextforge.pagination.session.PaginationSession;
+
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Manages chat pagination sessions for players.
+ * This class provides methods to set, get, remove, and check the existence of pagination sessions.
+ */
+public class ChatPaginatorManager {
+
+    // A thread-safe map to store pagination sessions keyed by player UUID.
+    private static final Map<UUID, PaginationSession<String>> sessions = new ConcurrentHashMap<>();
+
+    /**
+     * Sets a pagination session for a player.
+     *
+     * @param playerId The UUID of the player.
+     * @param session The pagination session to set for the player.
+     */
+    public static void setSession(UUID playerId, PaginationSession<String> session) {
+        sessions.put(playerId, session);
+    }
+
+    /**
+     * Retrieves the pagination session for a player.
+     *
+     * @param playerId The UUID of the player.
+     * @return The pagination session for the player, or null if no session exists.
+     */
+    public static PaginationSession<String> getSession(UUID playerId) {
+        return sessions.get(playerId);
+    }
+
+    /**
+     * Removes the pagination session for a player.
+     *
+     * @param playerId The UUID of the player.
+     */
+    public static void removeSession(UUID playerId) {
+        sessions.remove(playerId);
+    }
+
+    /**
+     * Checks if a pagination session exists for a player.
+     *
+     * @param playerId The UUID of the player.
+     * @return true if a session exists for the player, false otherwise.
+     */
+    public static boolean hasSession(UUID playerId) {
+        return sessions.containsKey(playerId);
+    }
+}

src/main/java/gg/nextforge/pagination/chat/DefaultChatPageRenderer.java

@@ -0,0 +1,46 @@
+package gg.nextforge.pagination.chat;
+
+import gg.nextforge.pagination.model.Page;
+import gg.nextforge.pagination.renderer.PageRenderer;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Default implementation of {@link PageRenderer} for rendering chat pages.
+ * @param <T> the type of items in the page
+ */
+public class DefaultChatPageRenderer<T> implements PageRenderer<T> {
+
+    // Header and footer templates for the chat page
+    private final String header;
+    private final String footer;
+
+    /**
+     * Creates a new DefaultChatPageRenderer with the specified header and footer.
+     * @param header the header template, which should contain placeholders for page index and total pages
+     * @param footer the footer template
+     */
+    public DefaultChatPageRenderer(String header, String footer) {
+        this.header = header;
+        this.footer = footer;
+    }
+
+    /**
+     * Renders the given page into a list of strings suitable for chat display.
+     * @param page the page to render
+     * @return a list of strings representing the rendered page
+     */
+    @Override
+    public List<String> render(Page<T> page) {
+        List<String> lines = new ArrayList<>();
+        lines.add(String.format(header, page.index() + 1, page.totalPages()));
+
+        for (T item : page.content()) {
+            lines.add(item.toString());
+        }
+
+        lines.add(footer);
+        return lines;
+    }
+}

src/main/java/gg/nextforge/pagination/model/Page.java

@@ -0,0 +1,21 @@
+package gg.nextforge.pagination.model;
+
+import java.util.List;
+
+/**
+ * Represents a paginated result set.
+ * @param index the current page index (0-based)
+ * @param totalPages the total number of pages available
+ * @param content the list of items on the current page
+ * @param <T> the type of items in the page
+ */
+public record Page<T>(int index, int totalPages, List<T> content) {
+
+    /**
+     * Checks if the page is empty.
+     * @return true if the page has no content, false otherwise
+     */
+    public boolean isEmpty() {
+        return content.isEmpty();
+    }
+}

src/main/java/gg/nextforge/pagination/renderer/PageRenderer.java

@@ -0,0 +1,19 @@
+package gg.nextforge.pagination.renderer;
+
+import gg.nextforge.pagination.model.Page;
+
+import java.util.List;
+
+/**
+ * Functional interface for rendering a page of items.
+ * @param <T> the type of items in the page
+ */
+@FunctionalInterface
+public interface PageRenderer<T> {
+    /**
+     * Render a page of items.
+     * @param page the page to render
+     * @return a list of strings representing the rendered items
+     */
+    List<String> render(Page<T> page);
+}

src/main/java/gg/nextforge/pagination/session/PaginationSession.java

@@ -0,0 +1,81 @@
+package gg.nextforge.pagination.session;
+
+import gg.nextforge.pagination.Pagination;
+import gg.nextforge.pagination.model.Page;
+
+/**
+ * A session for managing pagination state.
+ * This class allows navigating through pages of a {@link Pagination} object.
+ *
+ * @param <T> the type of items in the pagination
+ */
+public class PaginationSession<T> {
+
+    // The Pagination object that holds the items and pagination logic
+    private final Pagination<T> pagination;
+    // The current page index, starting from 0
+    private int currentPage = 0;
+
+    /**
+     * Constructs a PaginationSession with the given Pagination object.
+     *
+     * @param pagination the Pagination object to manage
+     */
+    public PaginationSession(Pagination<T> pagination) {
+        this.pagination = pagination;
+    }
+
+    /**
+     * Moves to the next page if available and returns it.
+     *
+     * @return the next {@link Page} of items
+     */
+    public Page<T> next() {
+        if (currentPage + 1 < pagination.getTotalPages()) currentPage++;
+        return pagination.getPage(currentPage);
+    }
+
+    /**
+     * Moves to the previous page if available and returns it.
+     *
+     * @return the previous {@link Page} of items
+     */
+    public Page<T> previous() {
+        if (currentPage > 0) currentPage--;
+        return pagination.getPage(currentPage);
+    }
+
+    /**
+     * Returns the current page without changing the state.
+     *
+     * @return the current {@link Page} of items
+     */
+    public Page<T> current() {
+        return pagination.getPage(currentPage);
+    }
+
+    /**
+     * Checks if there is a next page available.
+     *
+     * @return true if a next page exists, false otherwise
+     */
+    public boolean hasNext() {
+        return currentPage + 1 < pagination.getTotalPages();
+    }
+
+    /**
+     * Checks if there is a previous page available.
+     *
+     * @return true if a previous page exists, false otherwise
+     */
+    public boolean hasPrevious() {
+        return currentPage > 0;
+    }
+
+    /**
+     * Resets the session to the first page.
+     */
+    public void reset() {
+        currentPage = 0;
+    }
+}