From 70428e6e03db88fec88cbafda0d54426dcd4598b Mon Sep 17 00:00:00 2001 From: Sheldan <5037282+Sheldan@users.noreply.github.com> Date: Mon, 11 May 2020 20:46:14 +0200 Subject: [PATCH] added a first version of java doc for the templating module --- .../config/FreemarkerConfiguration.java | 9 +++++ .../config/TemplateSeedDataLoader.java | 8 ++++ .../loading/DatabaseTemplateLoader.java | 15 ++++++++ .../templating/methods/DurationMethod.java | 17 +++++++++ .../templating/methods/InstantMethod.java | 10 ++++- .../templating/model/EmbedAuthor.java | 15 +++++++- .../templating/model/EmbedColor.java | 15 +++++++- .../templating/model/EmbedConfiguration.java | 37 +++++++++++++++++- .../templating/model/EmbedField.java | 16 +++++++- .../templating/model/EmbedFooter.java | 12 +++++- .../templating/model/EmbedTitle.java | 12 +++++- .../TemplateRepository.java | 5 ++- .../service/TemplateServiceBean.java | 38 +++++++++++++++++++ .../TemplateManagementServiceBean.java | 8 +++- .../abstracto/templating/Templatable.java | 13 +++++++ .../templating/model/MessageToSend.java | 9 +++++ .../templating/model/database/Template.java | 9 +++++ .../templating/service/TemplateService.java | 24 ++++++++++++ .../management/TemplateManagementService.java | 21 ++++++++++ 19 files changed, 283 insertions(+), 10 deletions(-) rename abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/{loading => repository}/TemplateRepository.java (69%) diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/config/FreemarkerConfiguration.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/config/FreemarkerConfiguration.java index 6376a6cc9..ad5e9b6e6 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/config/FreemarkerConfiguration.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/config/FreemarkerConfiguration.java @@ -12,6 +12,9 @@ import org.springframework.ui.freemarker.FreeMarkerConfigurationFactory; import java.io.IOException; import java.util.Locale; +/** + * Configuration bean used to provide the {@link Configuration} bean to the spring context. + */ @org.springframework.context.annotation.Configuration public class FreemarkerConfiguration { @@ -24,6 +27,12 @@ public class FreemarkerConfiguration { @Autowired private InstantMethod instantMethod; + /** + * Creates a {@link Configuration} bean with the appropriate configuration which includes: + * The correct compatibility version and the provided formatter methods to be used in the templates. + * The encoding of the templates is set to UTF-8. + * @return A configured {@link Configuration} bean according to the configuration + */ @Bean public Configuration freeMarkerConfiguration() throws IOException, TemplateException { FreeMarkerConfigurationFactory factory = new FreeMarkerConfigurationFactory(); diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/config/TemplateSeedDataLoader.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/config/TemplateSeedDataLoader.java index 86f85ec68..8b230bb23 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/config/TemplateSeedDataLoader.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/config/TemplateSeedDataLoader.java @@ -16,6 +16,10 @@ import java.nio.charset.Charset; import java.util.Arrays; import java.util.List; +/** + * Loads the available templates from the class path and uploads them to the database, overriding existing templates in the process. + * This will load all *.ftl files at any level within a folder named 'templates' in the resources folder. + */ @Component @Slf4j public class TemplateSeedDataLoader { @@ -26,6 +30,10 @@ public class TemplateSeedDataLoader { @Autowired private TemplateManagementService service; + /** + * Is executed when the spring context is started, this will load all templates from the class path and + * store them in the database overriding the existing ones in the process. + */ @EventListener public void handleContextRefreshEvent(ContextRefreshedEvent ctxStartEvt) { log.info("Updating templates."); diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/loading/DatabaseTemplateLoader.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/loading/DatabaseTemplateLoader.java index fa971d3dd..7490e3f16 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/loading/DatabaseTemplateLoader.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/loading/DatabaseTemplateLoader.java @@ -11,6 +11,10 @@ import java.io.IOException; import java.io.Reader; import java.io.StringReader; +/** + * Loads the the template from the database to be used by Freemarker. This bean is also used when the templates within + * templates are used. + */ @Component public class DatabaseTemplateLoader implements TemplateLoader { @@ -20,6 +24,11 @@ public class DatabaseTemplateLoader implements TemplateLoader { @Autowired private TemplateManagementService templateManagementService; + /** + * Loads the content of the template object + * @param s The key of the template to load + * @return The template loaded from the database + */ @Override public Object findTemplateSource(String s) throws IOException { return templateManagementService.getTemplateByKey(s); @@ -36,6 +45,12 @@ public class DatabaseTemplateLoader implements TemplateLoader { } } + /** + * Retrieves the content of the template from the retrieved {@link Template} object + * @param o The retrieved {@link Template} object from the database + * @param s The encoding of the object + * @return The content of the template as a String reader + */ @Override public Reader getReader(Object o, String s) throws IOException { return new StringReader(((Template) o).getContent()); diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/methods/DurationMethod.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/methods/DurationMethod.java index 734591770..f5604f0f7 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/methods/DurationMethod.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/methods/DurationMethod.java @@ -12,12 +12,23 @@ import java.time.temporal.ChronoUnit; import java.util.HashMap; import java.util.List; +/** + * Method used to format the {@link Duration} object, as its not natively supported by Freemarker. + * This method only accepts a single {@link Duration} object as the first parameter. + */ @Component public class DurationMethod implements TemplateMethodModelEx { @Autowired private TemplateService service; + /** + * This method expects a single Duration object in the list of arguments. It will throw a {@link TemplateModelException} + * otherwise + * @param arguments The parameters passed to this method, should be only a single duration. + * @return The string representation of the {@link Duration} object + * @throws TemplateModelException + */ @Override public Object exec(List arguments) throws TemplateModelException { if (arguments.size() != 1) { @@ -30,6 +41,7 @@ public class DurationMethod implements TemplateMethodModelEx { Duration duration = (Duration) wrappedObject; StringBuilder stringBuilder = new StringBuilder(); // upgrading to java 9 makes this nicer + // todo refactor to use a single template, instead of multiple ones long days = duration.toDays(); if(days > 0) { stringBuilder.append(service.renderTemplate("day", getParam(days))); @@ -51,6 +63,11 @@ public class DurationMethod implements TemplateMethodModelEx { return stringBuilder.toString(); } + /** + * Creates the parameter passed to the template for rendering the single time unit template. + * @param value + * @return + */ private HashMap getParam(Long value) { HashMap params = new HashMap<>(); params.put("amount", value); diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/methods/InstantMethod.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/methods/InstantMethod.java index 9a2dd3475..a19502808 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/methods/InstantMethod.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/methods/InstantMethod.java @@ -11,15 +11,23 @@ import org.springframework.stereotype.Component; import java.time.Instant; import java.time.ZoneId; import java.time.format.DateTimeFormatter; -import java.util.HashMap; import java.util.List; +/** + * Formats the passed {@link Instant} object with the given Formatter. The format will be directly passed to {@link DateTimeFormatter}. + */ @Component public class InstantMethod implements TemplateMethodModelEx { @Autowired private TemplateService service; + /** + * Renders the given {@link Instant} object with the given String. Internally {@link DateTimeFormatter} will be used. + * @param arguments The list of arguments, first element must be an {@link Instant} and the second one must be a {@link String}. + * @return The formatted {@link Instant} as a string. + * @throws TemplateModelException If there are less or more arguments in the list and if the first element is not a {@link Instant}. + */ @Override public Object exec(List arguments) throws TemplateModelException { if (arguments.size() != 2) { diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedAuthor.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedAuthor.java index 8f718065a..f1cf139b6 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedAuthor.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedAuthor.java @@ -4,9 +4,22 @@ package dev.sheldan.abstracto.templating.model; import lombok.Getter; import lombok.Setter; -@Getter @Setter +/** + * The container class used to deserialize the embed configuration for the author in {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ +@Getter +@Setter public class EmbedAuthor { + /** + * The name used in the {@link net.dv8tion.jda.api.entities.MessageEmbed} author + */ private String name; + /** + * The URL used in the {@link net.dv8tion.jda.api.entities.MessageEmbed} author + */ private String url; + /** + * The picture used as the avatar of the author in {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ private String avatar; } diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedColor.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedColor.java index 986af32e8..d19343a80 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedColor.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedColor.java @@ -3,9 +3,22 @@ package dev.sheldan.abstracto.templating.model; import lombok.Getter; import lombok.Setter; -@Setter @Getter +/** + * The container class used to deserialize the embed configuration for the color in {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ +@Setter +@Getter public class EmbedColor { + /** + * The red part of RGB + */ private Integer r; + /** + * The green part of RGB + */ private Integer g; + /** + * The blue part of RGB + */ private Integer b; } diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedConfiguration.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedConfiguration.java index f013f7c10..885983691 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedConfiguration.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedConfiguration.java @@ -6,16 +6,51 @@ import lombok.Setter; import java.time.OffsetDateTime; import java.util.List; -@Getter @Setter +/** + * The whole container object used to deserialize the whole embed configuration + * https://raw.githubusercontent.com/DV8FromTheWorld/JDA/assets/assets/docs/embeds/07-addField.png + */ +@Getter +@Setter public class EmbedConfiguration { + /** + * The {@link EmbedAuthor} object holding the configuration for the author of the {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ private EmbedAuthor author; + /** + * The {@link EmbedTitle} object holding the configuration for the title in the {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ private EmbedTitle title; + /** + * The {@link EmbedColor} object holding the configuration for the color in the {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ private EmbedColor color; + /** + * The description which is going to be used in the {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ private String description; + /** + * The link to the image used as a thumbnail in the {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ private String thumbnail; + /** + * The link to the image used as the image in the {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ private String imageUrl; + /** + * The collection containing all the objects containing the configuration for the fields in the {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ private List fields; + /** + * The {@link EmbedFooter} object holding the configuration for the footer in {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ private EmbedFooter footer; + /** + * Thhe {@link OffsetDateTime} object used as the time stamp in the {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ private OffsetDateTime timeStamp; + /** + * The message which is posted along the {@link net.dv8tion.jda.api.entities.MessageEmbed} as a normal message. + */ private String additionalMessage; } diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedField.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedField.java index 7d062981e..6d0549221 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedField.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedField.java @@ -3,9 +3,23 @@ package dev.sheldan.abstracto.templating.model; import lombok.Getter; import lombok.Setter; -@Getter @Setter +/** + * The container class used to deserialize the embed configuration for a field in {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ +@Getter +@Setter public class EmbedField { + /** + * The name of the field to be set, must not be null or empty + */ private String name; + /** + * The value of the field to be set, must not be null or empty + */ private String value; + /** + * Whether or not the field should be rendered inline within the {@link net.dv8tion.jda.api.entities.MessageEmbed}. + * This means, if multiple fields can be put on the same height in the {@link net.dv8tion.jda.api.entities.MessageEmbed} this will be done by discord. + */ private Boolean inline; } diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedFooter.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedFooter.java index 5145fdf8c..9db206e2b 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedFooter.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedFooter.java @@ -3,8 +3,18 @@ package dev.sheldan.abstracto.templating.model; import lombok.Getter; import lombok.Setter; -@Getter @Setter +/** + * The container object used to deserialize the embed configuration for the footer in the {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ +@Getter +@Setter public class EmbedFooter { + /** + * The text which is going to be used as the footer text + */ private String text; + /** + * The link to the image which is going to be used as the icon of the footer + */ private String icon; } diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedTitle.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedTitle.java index c83653ae1..9162bdd2c 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedTitle.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/model/EmbedTitle.java @@ -3,8 +3,18 @@ package dev.sheldan.abstracto.templating.model; import lombok.Getter; import lombok.Setter; -@Getter @Setter +/** + * The container class used to deserialize the embed configuration used in the title in {@link net.dv8tion.jda.api.entities.MessageEmbed} + */ +@Getter +@Setter public class EmbedTitle { + /** + * The text which is going to be used as the title of the embed + */ private String title; + /** + * The link which is used when clicking on the title of the embed + */ private String url; } diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/loading/TemplateRepository.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/repository/TemplateRepository.java similarity index 69% rename from abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/loading/TemplateRepository.java rename to abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/repository/TemplateRepository.java index 4b4f4ab68..e3e4adae6 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/loading/TemplateRepository.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/repository/TemplateRepository.java @@ -1,9 +1,12 @@ -package dev.sheldan.abstracto.templating.loading; +package dev.sheldan.abstracto.templating.repository; import dev.sheldan.abstracto.templating.model.database.Template; import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.stereotype.Repository; +/** + * Repository used to load the templates from the database. + */ @Repository public interface TemplateRepository extends JpaRepository { } diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/service/TemplateServiceBean.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/service/TemplateServiceBean.java index 64b5d01e1..a71d5ebca 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/service/TemplateServiceBean.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/service/TemplateServiceBean.java @@ -19,6 +19,9 @@ import java.util.HashMap; import java.util.List; import java.util.stream.Collectors; +/** + * Bean used to render a template, identified by a key, with the passed model. + */ @Slf4j @Component public class TemplateServiceBean implements TemplateService { @@ -30,12 +33,29 @@ public class TemplateServiceBean implements TemplateService { private Gson gson; + /** + * Formats the passed passed count with the embed used for formatting pages. + * @param count The index of the page you want formated. + * @return The rendered template as a string object + */ private String getPageString(Integer count) { HashMap params = new HashMap<>(); params.put("count", count); return renderTemplateWithMap("embed_page_count", params); } + /** + * Retrieves the key which gets suffixed with '_embed' and this retrives the embed configuration. This configuration is then rendered + * and deserialized with GSON into a {@link EmbedConfiguration} object. This object is then rendered into a {@link MessageToSend} and returned. + * If the individual element do not fit in an embed, for example, if the field count is to high, another embed will be created in the {@link MessageToSend} object. + * If multiple embeds are necessary to provide what the {@link EmbedConfiguration} wanted, this method will automatically set the footer of the additional {@link MessageEmbed} + * with a formatted page count. + * This method will to try its best to provided a message which can be handled by discord without rejecting it. Besides that, the content from the rendered template, will be passed + * into the {@link EmbedBuilder} directly. + * @param key The key of the embed template to be used for rendering. + * @param model The model providing the properties to be used for rendering + * @return The {@link MessageToSend} object which is properly split up in order to be send to discord. + */ @Override public MessageToSend renderEmbedTemplate(String key, Object model) { String embedConfig = this.renderTemplate(key + "_embed", model); @@ -100,6 +120,12 @@ public class TemplateServiceBean implements TemplateService { .build(); } + /** + * Enlarges the passed list of builders, if the passed index is not yet available within the list. + * When a new builder is needed, this will automatically set the footer with a page indicator. + * @param builders The current list of {@link EmbedBuilder} builders used. + * @param neededIndex The desired index in the list which should be available for using. + */ private void extendIfNecessary(List builders, double neededIndex) { if(neededIndex > builders.size() - 1) { for (int i = builders.size(); i < neededIndex + 1; i++) { @@ -110,6 +136,12 @@ public class TemplateServiceBean implements TemplateService { } } + /** + * Renders the template identified by the key with the passed {@link HashMap} + * @param key The key of the template to be rendered. + * @param parameters The {@link HashMap} to be used as the parameters for the template + * @return The rendered template as a string + */ @Override public String renderTemplateWithMap(String key, HashMap parameters) { try { @@ -120,6 +152,12 @@ public class TemplateServiceBean implements TemplateService { } } + /** + * Renders the template identified by the key with the passed object as model + * @param key The key of the template to be rendered + * @param model The object containing the model to be used in the template + * @return The rendered template as a string + */ @Override public String renderTemplate(String key, Object model) { try { diff --git a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/service/management/TemplateManagementServiceBean.java b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/service/management/TemplateManagementServiceBean.java index 960879a33..e5648ba03 100644 --- a/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/service/management/TemplateManagementServiceBean.java +++ b/abstracto-application/templating/templating-impl/src/main/java/dev/sheldan/abstracto/templating/service/management/TemplateManagementServiceBean.java @@ -1,6 +1,6 @@ package dev.sheldan.abstracto.templating.service.management; -import dev.sheldan.abstracto.templating.loading.TemplateRepository; +import dev.sheldan.abstracto.templating.repository.TemplateRepository; import dev.sheldan.abstracto.templating.model.database.Template; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Autowired; @@ -8,6 +8,10 @@ import org.springframework.stereotype.Component; import java.time.Instant; +/** + * ManagementService bean used to retrieve the templates by key from the database. + * This class uses the {@link TemplateRepository} bean to laod the {@link Template} objects. + */ @Component @Slf4j public class TemplateManagementServiceBean implements TemplateManagementService { @@ -22,7 +26,7 @@ public class TemplateManagementServiceBean implements TemplateManagementService @Override public boolean templateExists(String key) { - return getTemplateByKey(key) != null; + return repository.existsById(key); } @Override diff --git a/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/Templatable.java b/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/Templatable.java index 638d3a004..a587907fa 100644 --- a/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/Templatable.java +++ b/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/Templatable.java @@ -1,6 +1,19 @@ package dev.sheldan.abstracto.templating; +/** + * An interface to be used on objects, which should be able to be processable by the template engine. + * This contains a template key and the model which is used when rendering this template. + */ public interface Templatable { + /** + * The template key to be used to render this object. + * @return The template key as string + */ String getTemplateName(); + + /** + * The model to be used to render this template. + * @return The model containing the attributes to be used for rendering. + */ Object getTemplateModel(); } diff --git a/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/model/MessageToSend.java b/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/model/MessageToSend.java index 2c67e05dc..088b6195e 100644 --- a/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/model/MessageToSend.java +++ b/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/model/MessageToSend.java @@ -7,10 +7,19 @@ import net.dv8tion.jda.api.entities.MessageEmbed; import java.util.List; +/** + * A full message which is ready to be send. This message can contain an arbitrary amount of embeds and a string message. + */ @Getter @Setter @Builder public class MessageToSend { + /** + * The collections of embeds to be send. The first embed is in the same message as the string message. + */ private List embeds; + /** + * The string content to be used in the first message. + */ private String message; } diff --git a/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/model/database/Template.java b/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/model/database/Template.java index fc80d67d1..4f5894ee5 100644 --- a/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/model/database/Template.java +++ b/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/model/database/Template.java @@ -10,6 +10,9 @@ import javax.persistence.*; import java.time.Instant; import java.util.Objects; +/** + * Represents the template stored in the database. + */ @Builder @Entity @NoArgsConstructor @@ -19,10 +22,16 @@ import java.util.Objects; @org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_WRITE) public class Template { + /** + * The globally unique key of the template + */ @Id @Getter private String key; + /** + * The content of the template + */ @Getter @Column(length = 4000) private String content; diff --git a/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/service/TemplateService.java b/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/service/TemplateService.java index 013518cd9..d1d3fc70a 100644 --- a/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/service/TemplateService.java +++ b/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/service/TemplateService.java @@ -4,8 +4,32 @@ import dev.sheldan.abstracto.templating.model.MessageToSend; import java.util.HashMap; +/** + * Provides methods to render templates with the appropriate model. + */ public interface TemplateService { + /** + * The template containing a embed definition which should be rendered. The key must refer to an existing template and the supplied model will be used when rendering. + * This creates a {@link MessageToSend} object containing the rendered template and might result in multiple embeds. + * @param key The key of the embed template to be used for rendering. + * @param model The model providing the properties to be used for rendering + * @return A fully rendered message containing the content of the template and might contain multiple embeds. + */ MessageToSend renderEmbedTemplate(String key, Object model); + + /** + * Renders the template identified by the key with the given {@link HashMap} used as model and returns the value as a string + * @param key The key of the template to be rendered. + * @param parameters The {@link HashMap} to be used as the parameters for the template + * @return The template rendered as string. + */ String renderTemplateWithMap(String key, HashMap parameters); + + /** + * Renders the template identified by the key with the given model and returns the value as a string + * @param key The key of the template to be rendered + * @param model The object containing the model to be used in the template + * @return The template rendered as string. + */ String renderTemplate(String key, Object model); } diff --git a/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/service/management/TemplateManagementService.java b/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/service/management/TemplateManagementService.java index 16aee7ad5..71376aae5 100644 --- a/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/service/management/TemplateManagementService.java +++ b/abstracto-application/templating/templating-interface/src/main/java/dev/sheldan/abstracto/templating/service/management/TemplateManagementService.java @@ -2,8 +2,29 @@ package dev.sheldan.abstracto.templating.service.management; import dev.sheldan.abstracto.templating.model.database.Template; +/** + * Provides methods to access the stored templates. + */ public interface TemplateManagementService { + /** + * Retrieves the template identified by the key. + * @param key They template key to search for + * @return The {@link Template} identified by the key, if it exists. + */ Template getTemplateByKey(String key); + + /** + * Checks whether or not the template exists in the database. + * @param key They key of the template to search for + * @return true, if the template exists and false otherwise + */ boolean templateExists(String key); + + /** + * Creates a template identified by the key and with the provided content. + * @param key They key of the template to create. + * @param content The content the template should have + * @return The created template in the database. + */ Template createTemplate(String key, String content); }