docs: update java docs

Author: Drednote

src/main/java/io/github/drednote/telegram/core/annotation/HasRole.java

@@ -1,23 +1,71 @@
 package io.github.drednote.telegram.core.annotation;
 
+import io.github.drednote.telegram.response.ForbiddenTelegramResponse;
+import io.github.drednote.telegram.response.GenericTelegramResponse;
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Annotation for specifying required roles for a Telegram handler method.
+ * <p>
+ * The method annotated with {@code @HasRole} will be checked during request processing, and access will be granted only
+ * if the current user has the required roles according to the specified matching strategy.
+ * </p>
+ *
+ * <p>Supported matching strategies:
+ * <ul>
+ *   <li>{@link StrategyMatching#INTERSECTION} – at least one required role must be present.</li>
+ *   <li>{@link StrategyMatching#COMPLETE_MATCH} – all specified roles must be present.</li>
+ * </ul>
+ * </p>
+ * <p>
+ * If validation fails, the request is blocked and a response is added, either a {@link ForbiddenTelegramResponse} or a
+ * {@link GenericTelegramResponse} based on the annotation's {@code description} field.
+ *
+ * @author Ivan Galushko
+ */
 @Target({ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
 public @interface HasRole {
 
-  String[] value();
+    /**
+     * One or more required roles that the current user must have.
+     *
+     * @return the array of role names
+     */
+    String[] value();
 
-  String description() default "";
+    /**
+     * Optional description that will be sent to the user in case of access denial.
+     *
+     * @return a textual description or message
+     */
+    String description() default "";
 
-  StrategyMatching strategyMatching() default StrategyMatching.INTERSECTION;
+    /**
+     * Strategy used to match the user's roles against the required ones. Defaults to
+     * {@link StrategyMatching#INTERSECTION}.
+     *
+     * @return the matching strategy
+     */
+    StrategyMatching strategyMatching() default StrategyMatching.INTERSECTION;
 
-  enum StrategyMatching {
-    INTERSECTION, COMPLETE_MATCH
-  }
+    /**
+     * Role matching strategy for evaluating the user's permissions.
+     */
+    enum StrategyMatching {
+        /**
+         * Requires at least one of the specified roles to be present.
+         */
+        INTERSECTION,
+
+        /**
+         * Requires all specified roles to be present.
+         */
+        COMPLETE_MATCH
+    }
 }

src/main/java/io/github/drednote/telegram/core/request/DefaultTelegramRequest.java

@@ -6,6 +6,9 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * Default implementation.
+ */
 @Data
 public class DefaultTelegramRequest implements TelegramRequest {
 

src/main/java/io/github/drednote/telegram/datasource/kryo/KryoSerializationService.java

@@ -2,9 +2,34 @@
 
 import java.io.IOException;
 
+/**
+ * Generic interface for serializing and deserializing objects using Kryo.
+ * <p>
+ * Implementations of this interface are expected to provide Kryo-based binary serialization for a specific type
+ * {@code T}.
+ * </p>
+ *
+ * <p>Serialization errors during encoding are propagated as {@link IOException}.</p>
+ *
+ * @param <T> the type of object to serialize and deserialize
+ * @author Ivan Galushko
+ */
 public interface KryoSerializationService<T> {
 
+    /**
+     * Serializes the given object into a byte array using Kryo.
+     *
+     * @param context the object to serialize
+     * @return the serialized byte array
+     * @throws IOException if serialization fails
+     */
     byte[] serialize(T context) throws IOException;
 
+    /**
+     * Deserializes the given byte array into an object of type {@code T} using Kryo.
+     *
+     * @param bytes the byte array to deserialize
+     * @return the deserialized object
+     */
     T deserialize(byte[] bytes);
 }

src/main/java/io/github/drednote/telegram/datasource/permission/Permission.java

@@ -1,27 +1,62 @@
 package io.github.drednote.telegram.datasource.permission;
 
+import io.github.drednote.telegram.filter.pre.PreUpdateFilter;
 import java.util.Set;
 import org.springframework.lang.Nullable;
 
+/**
+ * Represents a permission model that contains a unique identifier and a set of roles.
+ * <p>
+ * This abstraction is typically used to describe the roles associated with a specific user or context in the request
+ * pipeline.
+ * </p>
+ *
+ * <p>Implementations may vary, but the typical usage includes associating permissions
+ * with access control filters such as {@link PreUpdateFilter}.</p>
+ *
+ * @author Ivan Galushko
+ */
 public interface Permission {
 
-  Long getId();
+    /**
+     * Returns the unique identifier of the permission object, typically associated with a user or session.
+     *
+     * @return the permission ID
+     */
+    Long getId();
 
-  @Nullable
-  Set<String> getRoles();
+    /**
+     * Returns the set of roles associated with this permission.
+     * <p>
+     * Can return {@code null} if no roles are assigned.
+     * </p>
+     *
+     * @return a set of role names or {@code null}
+     */
+    @Nullable
+    Set<String> getRoles();
 
-  record DefaultPermission(
-      Long id, Set<String> roles
-  ) implements Permission {
+    /**
+     * Default implementation of {@link Permission} as an immutable Java record.
+     * <p>
+     * Provides a simple container for permission data with {@code id} and {@code roles}.
+     * </p>
+     *
+     * @param id    the permission identifier
+     * @param roles the associated roles
+     */
+    record DefaultPermission(
+        Long id, Set<String> roles
+    ) implements Permission {
 
-    @Override
-    public Long getId() {
-      return id;
-    }
+        @Override
+        public Long getId() {
+            return id;
+        }
 
-    @Override
-    public Set<String> getRoles() {
-      return roles;
+        @Override
+        public Set<String> getRoles() {
+            return roles;
+        }
     }
-  }
 }

src/main/java/io/github/drednote/telegram/datasource/permission/PermissionRepositoryAdapter.java

@@ -3,8 +3,23 @@
 import io.github.drednote.telegram.datasource.DataSourceAdapter;
 import org.springframework.lang.Nullable;
 
+/**
+ * Adapter interface for retrieving permission information from an external data source.
+ * <p>
+ * Used to fetch {@link Permission} objects for a given {@code chatId}, typically during request processing to determine
+ * user access rights.
+ * </p>
+ *
+ * @author Ivan Galushko
+ */
 public interface PermissionRepositoryAdapter extends DataSourceAdapter {
 
-  @Nullable
-  Permission findPermission(Long chatId);
+    /**
+     * Retrieves the {@link Permission} associated with the given chat ID.
+     *
+     * @param chatId the Telegram chat ID of the user
+     * @return the corresponding {@link Permission}, or {@code null} if none found
+     */
+    @Nullable
+    Permission findPermission(Long chatId);
 }

src/main/java/io/github/drednote/telegram/datasource/scenarioid/ScenarioId.java

@@ -1,13 +1,41 @@
 package io.github.drednote.telegram.datasource.scenarioid;
 
+/**
+ * Provides a link between the user and the currently active scenario.
+ * <p>
+ * Used to determine which {@code scenarioId} is currently assigned to the user (or other entity), identified by
+ * {@code id}. At the same time, {@code scenarioId} can change during the interaction, reflecting a change in context,
+ * stage or business flow.
+ *
+ * <p>For example, if the user goes through a sequence of steps (registration scenario, order placement, etc.),
+ * then this entity allows you to understand which scenarios he is currently in.</p>
+ *
+ * <p>As a rule, they are used by storages and routing logic in Telegram bots.</p>
+ *
+ * @author Ivan Galushko
+ */
 public interface ScenarioId {
 
+    /**
+     * Returns a unique identifier for the user or other entity that the scenario is attached to.
+     *
+     * @return a unique identifier (e.g. chatId)
+     */
     String getId();
 
+    /**
+     * Returns the identifier of the scenario associated with the entity.
+     *
+     * @return the scenario ID
+     */
     String getScenarioId();
 
-//    void setScenarioId(String scenarioId);
-
+    /**
+     * Default immutable implementation of {@link ScenarioId} using Java record.
+     *
+     * @param id         the entity identifier (e.g. chatId)
+     * @param scenarioId the scenario identifier
+     */
     record DefaultScenarioId(String id, String scenarioId) implements ScenarioId {
 
         @Override

src/main/java/io/github/drednote/telegram/datasource/session/AbstractUpdateInboxRepositoryAdapter.java

@@ -3,7 +3,6 @@
 import io.github.drednote.telegram.core.request.ParsedUpdateRequest;
 import io.github.drednote.telegram.session.SessionProperties;
 import io.github.drednote.telegram.utils.Assert;
-import java.lang.reflect.InvocationTargetException;
 import java.time.Instant;
 import java.time.temporal.ChronoUnit;
 import java.util.List;
@@ -13,6 +12,26 @@
 import org.springframework.dao.DataIntegrityViolationException;
 import org.telegram.telegrambots.meta.api.objects.Update;
 
+/**
+ * Abstract base class for implementing {@link UpdateInboxRepositoryAdapter} backed by a repository.
+ * <p>
+ * Handles core logic for persisting, retrieving, and updating {@link UpdateInbox} entities. The strategy for selecting
+ * and managing inbox records is delegated to abstract methods.
+ * </p>
+ *
+ * <p>This class expects subclasses to define how to:
+ * <ul>
+ *   <li>Find idle entities for timeout processing</li>
+ *   <li>Retrieve the next update based on concurrency limits</li>
+ *   <li>Persist a single entity to the underlying storage</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Entity creation is handled reflectively via {@link Class#getDeclaredConstructor(Class[])}}.</p>
+ *
+ * @param <T> the inbox entity type
+ * @author Ivan Galushko
+ */
 public abstract class AbstractUpdateInboxRepositoryAdapter<T extends UpdateInbox>
     implements UpdateInboxRepositoryAdapter<T> {
 
@@ -22,6 +41,13 @@ public abstract class AbstractUpdateInboxRepositoryAdapter<T extends UpdateInbox
     private final UpdateInboxRepository<T> repository;
     private final Class<T> clazz;
 
+    /**
+     * Constructs the adapter with required dependencies.
+     *
+     * @param properties configuration for session control and threading
+     * @param repository the inbox repository implementation
+     * @param clazz      the class type of the inbox entity
+     */
     protected AbstractUpdateInboxRepositoryAdapter(
         SessionProperties properties, UpdateInboxRepository<T> repository, Class<T> clazz
     ) {
@@ -34,12 +60,35 @@ protected AbstractUpdateInboxRepositoryAdapter(
         this.properties = properties;
     }
 
+    /**
+     * Must return a list of entities that have been in {@link UpdateInboxStatus#IN_PROGRESS} state longer than the
+     * configured threshold.
+     *
+     * @param date cutoff instant for detecting idle entries
+     * @return list of idle entities
+     */
     protected abstract List<T> getIdleEntities(Instant date);
 
+    /**
+     * Retrieves the next update respecting the max threads per user limit.
+     *
+     * @param maxThreadsPerUser maximum number of simultaneous updates per user
+     * @return optional inbox entity to process
+     */
     protected abstract Optional<T> findWithMaxThreadsPerUser(int maxThreadsPerUser);
 
+    /**
+     * Retrieves the next available update without thread restrictions.
+     *
+     * @return optional inbox entity
+     */
     protected abstract Optional<T> findNextWithoutLimit();
 
+    /**
+     * Persists the given inbox entity to the repository.
+     *
+     * @param entity the inbox entity to save
+     */
     protected abstract void persist(T entity);
 
     @Override
@@ -57,8 +106,7 @@ public void persist(List<Update> updates) {
                 log.warn("Cannot persist update inbox with id '{}'. Cause: {}",
                     update.getUpdateId(), e.getMessage());
                 log.debug(e.getMessage(), e);
-            } catch (InvocationTargetException | InstantiationException | IllegalAccessException |
-                     NoSuchMethodException e) {
+            } catch (Exception e) {
                 log.error("Cannot persist update inbox with id '{}'. Cause: ", update.getUpdateId(), e);
             }
         }