From 56882c1c4640a33f7656600f69a637277f6f31aa Mon Sep 17 00:00:00 2001 From: Davide Polonio Date: Fri, 31 Mar 2023 18:51:35 +0200 Subject: [PATCH] docs: add missing Javadoc --- src/etc/stork/stork.yml | 2 +- .../i18n/LocalizedMessageFactory.java | 21 ++++++++++++++++ .../orm/model/CallbackQueryContext.java | 4 ++++ .../telegram/callbackquery/Dispatcher.java | 19 +++++++++++++++ .../EventProcessorNotFoundException.java | 6 +++++ .../telegram/callbackquery/Processor.java | 24 +++++++++++++++++++ 6 files changed, 75 insertions(+), 1 deletion(-) diff --git a/src/etc/stork/stork.yml b/src/etc/stork/stork.yml index 09dd917..ee568c7 100644 --- a/src/etc/stork/stork.yml +++ b/src/etc/stork/stork.yml @@ -35,7 +35,7 @@ max_java_memory: 512 #min_java_memory_pct: 10 #max_java_memory_pct: 20 -# Try to createVelocityToolManager a symbolic link to java executable in /run with +# Try to create a symbolic link to java executable in /run with # the name of "-java" so that commands like "ps" will make it # easier to find your app symlink_java: true diff --git a/src/main/java/com/github/polpetta/mezzotre/i18n/LocalizedMessageFactory.java b/src/main/java/com/github/polpetta/mezzotre/i18n/LocalizedMessageFactory.java index df124db..97a0c8b 100644 --- a/src/main/java/com/github/polpetta/mezzotre/i18n/LocalizedMessageFactory.java +++ b/src/main/java/com/github/polpetta/mezzotre/i18n/LocalizedMessageFactory.java @@ -12,6 +12,13 @@ import org.apache.velocity.tools.config.FactoryConfiguration; import org.apache.velocity.tools.config.ToolConfiguration; import org.apache.velocity.tools.config.ToolboxConfiguration; +/** + * This class provides utility to create {@link ToolManager} for {@link VelocityEngine} or to + * retrieve simple localized strings from the system. + * + * @author Davide Polonio + * @since 1.0 + */ public class LocalizedMessageFactory { private final VelocityEngine velocityEngine; @@ -21,6 +28,14 @@ public class LocalizedMessageFactory { this.velocityEngine = velocityEngine; } + /** + * Provide a {@link ToolManager} completely setup. Localization will be taken from jar resources, + * and {@link LocalizedTool} can be used in Velocity templates to automatically access them. + * + * @param locale the language needed + * @return a {@link ToolManager} ready with the desired locale, if it exists. Fallback to english + * otherwise + */ public ToolManager createVelocityToolManager(Locale locale) { final ToolManager toolManager = new ToolManager(); @@ -39,6 +54,12 @@ public class LocalizedMessageFactory { return toolManager; } + /** + * Creates a {@link ResourceBundle} object that can be used to access single localized strings + * + * @param locale the language desired to retrieve the translated strings + * @return a {@link ResourceBundle} with the provided locale + */ public ResourceBundle createResourceBundle(Locale locale) { return ResourceBundle.getBundle("i18n/message", locale); } diff --git a/src/main/java/com/github/polpetta/mezzotre/orm/model/CallbackQueryContext.java b/src/main/java/com/github/polpetta/mezzotre/orm/model/CallbackQueryContext.java index 8cf1ef7..3687d12 100644 --- a/src/main/java/com/github/polpetta/mezzotre/orm/model/CallbackQueryContext.java +++ b/src/main/java/com/github/polpetta/mezzotre/orm/model/CallbackQueryContext.java @@ -28,6 +28,10 @@ public class CallbackQueryContext extends Base { @Length(36) private final String id; + /** + * Each callback can belong to a particular group. In that case, this variable will be the same + * for all the related {@link CallbackQueryMetadata} + */ @NotNull @Length(36) private final String entryGroup; diff --git a/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/Dispatcher.java b/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/Dispatcher.java index 91037ee..a27d181 100644 --- a/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/Dispatcher.java +++ b/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/Dispatcher.java @@ -11,6 +11,14 @@ import javax.inject.Inject; import javax.inject.Named; import javax.inject.Singleton; +/** + * This class dispatches incoming {@link Update} containing a {@link + * com.pengrad.telegrambot.model.CallbackQuery} entry to the right {@link Processor} that will take + * care of processing them. + * + * @author Davide Polonio + * @since 1.0 + */ @Singleton public class Dispatcher { @@ -25,6 +33,17 @@ public class Dispatcher { this.threadPool = threadPool; } + /** + * This method searches for the right {@link Processor} installed in the system. A {@link + * CallbackQueryContext} has to be previously saved in the database in order for this method to + * find the right event to process. Once the corresponding {@link Processor} is found, the + * computation is delegated to it + * + * @param callbackQueryContext the context coming from the database storage - cannot be null + * @param update the incoming {@link Update} coming from Telegram + * @return a {@link CompletableFuture} containing an {@link Optional} that may or not have a + * {@link BaseRequest} response to send back to Telegram. + */ public CompletableFuture>> dispatch( CallbackQueryContext callbackQueryContext, Update update) { return CompletableFuture.completedFuture(update) diff --git a/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/EventProcessorNotFoundException.java b/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/EventProcessorNotFoundException.java index 16f2b8e..dbb23cf 100644 --- a/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/EventProcessorNotFoundException.java +++ b/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/EventProcessorNotFoundException.java @@ -1,5 +1,11 @@ package com.github.polpetta.mezzotre.telegram.callbackquery; +/** + * Wrapper exception when a valid {@link Processor} is not found in the system + * + * @author Davide Polonio + * @since 1.0 + */ public class EventProcessorNotFoundException extends RuntimeException { public EventProcessorNotFoundException() {} diff --git a/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/Processor.java b/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/Processor.java index e37bbb1..021a177 100644 --- a/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/Processor.java +++ b/src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/Processor.java @@ -6,9 +6,33 @@ import com.pengrad.telegrambot.request.BaseRequest; import java.util.Optional; import java.util.concurrent.CompletableFuture; +/** + * A processor is an object which is able to process an incoming Telegram {@link Update} containing + * a {@link com.pengrad.telegrambot.model.CallbackQuery}. Any event of this type is related to a + * previous message. + * + * @author Davide Polonio + * @since 1.0 + */ public interface Processor { + + /** + * The even name this processor is able to process + * + * @return a {@link String} containig the name of the event supported + */ String getEventName(); + /** + * Process the current event + * + * @param callbackQueryContext the corresponding even {@link CallbackQueryContext} previously + * stored in the database + * @param update the Telegram {@link Update} containing a {@link + * com.pengrad.telegrambot.model.CallbackQuery} incoming Telegram + * @return a {@link CompletableFuture} containing an {@link Optional} that may or maybe not have a + * {@link BaseRequest}, that is the response that will be sent back to Telegram + */ CompletableFuture>> process( CallbackQueryContext callbackQueryContext, Update update); }