Sheldan/abstracto
1
0
Fork 0
mirror of https://github.com/Sheldan/abstracto.git synced 2026-04-05 00:53:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

[AB-60] improving java doc for experience module

Browse Source
This commit is contained in:
Sheldan
2021-03-03 16:35:06 +01:00
parent 821971523e
commit 373dfac001
36 changed files with 390 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/ExperienceGainResult.java
View File

@@ -6,16 +6,44 @@ import lombok.Setter;
import java.util.concurrent.CompletableFuture;
/**
* This object is used to determine the result of calculating the gained experience.
* It is used in the schedule job responsible to calculate the changes after experience has been awarded.
* This changes can include a level or experience role change.
*/
@Getter
@Setter
@Builder
public class ExperienceGainResult {
/**
* The calculation result contained in a {@link CompletableFuture future}. The future is necessary, because the calculation both calculates the new role
* and removes/adds {@link net.dv8tion.jda.api.entities.Role role} to the {@link net.dv8tion.jda.api.entities.Member member}
*/
private CompletableFuture<RoleCalculationResult> calculationResult;
/**
* The ID of the {@link dev.sheldan.abstracto.core.models.database.AUserInAServer user} for which this is the result
*/
private Long userInServerId;
/**
* The amount of experience the {@link dev.sheldan.abstracto.core.models.database.AUserInAServer user} has
*/
private Long newExperience;
/**
* The ID of the {@link dev.sheldan.abstracto.core.models.database.AServer server} this calculation took place in
*/
private Long serverId;
/**
* The new level the {@link dev.sheldan.abstracto.core.models.database.AUserInAServer user} reached. Might be the same as the old.
*/
private Integer newLevel;
/**
* The new amount of messages of the {@link dev.sheldan.abstracto.core.models.database.AUserInAServer user} in this server which were counted bý experience tracking
*/
private Long newMessageCount;
/**
* Whether or not a {@link dev.sheldan.abstracto.experience.models.database.AUserExperience experience} object needs to be created after the calculation.
* This happens if the object did not exist yet, but the calculation was done regardless.
*/
@Builder.Default
private boolean createUserExperience = false;
}

10
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/RoleCalculationResult.java
View File

@@ -4,10 +4,20 @@ import lombok.Builder;
import lombok.Getter;
import lombok.Setter;
/**
* The result of calculating the appropriate {@link dev.sheldan.abstracto.experience.models.database.AExperienceRole role} for a {@link dev.sheldan.abstracto.experience.models.database.AUserExperience user}
* in a server.
*/
@Getter
@Setter
@Builder
public class RoleCalculationResult {
/**
* The ID of the {@link dev.sheldan.abstracto.experience.models.database.AExperienceRole role} which was given to the user. Can be null, in case no role is given.
*/
private Long experienceRoleId;
/**
* The ID of a {@link dev.sheldan.abstracto.core.models.database.AUserInAServer user} for who the role was calculated for.
*/
private Long userInServerId;
}

10
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/ServerExperience.java
View File

@@ -7,11 +7,21 @@ import lombok.Setter;
import java.util.ArrayList;
import java.util.List;
/**
* Container object to store the experience in runtime and group it together. This basically is just a list of users who were tracked by experience.
* The actual calculation of the appropriate experience amount is done later.
*/
@Getter
@Setter
@Builder
public class ServerExperience {
/**
* The ID of the {@link dev.sheldan.abstracto.core.models.database.AServer} for which this experience were collected
*/
private Long serverId;
/**
* A list of IDs of the {@link dev.sheldan.abstracto.core.models.database.AUserInAServer} which should be given experience
*/
@Builder.Default
private List<Long> userInServerIds = new ArrayList<>();
}

11
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/database/ADisabledExpRole.java
View File

@@ -20,20 +20,29 @@ import java.time.Instant;
@EqualsAndHashCode
public class ADisabledExpRole implements Serializable {
/**
* The ID of the {@link ARole role} which is being marked to be used as a marker for {@link net.dv8tion.jda.api.entities.Member} which should not gain experience
*/
@Id
@Column(name = "id")
private Long id;
/**
* Reference to the actual {@link ARole} being marked as disabled for experience gain.
*/
@OneToOne(fetch = FetchType.LAZY, cascade = {CascadeType.PERSIST, CascadeType.MERGE})
@PrimaryKeyJoinColumn
private ARole role;
/**
* Reference to the actual {@link ARole} being marked as disabled for experience gain.
* The {@link Instant} this entity was created
*/
@Column(name = "created")
private Instant created;
/**
* The {@link Instant} this entity was updated
*/
@Column(name = "updated")
private Instant updated;
}

8
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/database/AExperienceLevel.java
View File

@@ -18,21 +18,29 @@ import java.time.Instant;
@Setter
@EqualsAndHashCode
public class AExperienceLevel implements Serializable {
/**
* The unique level from 0 to as defined in the configuration. Will be created on startup.
*/
@Id
@Column(name = "level")
private Integer level;
/**
* The total amount of experience needed for this level.
*/
@Column(name = "experience_needed")
private Long experienceNeeded;
/**
* The {@link Instant} this entity was created
*/
@Column(name = "created")
private Instant created;
/**
* The {@link Instant} this entity was updated
*/
@Column(name = "updated")
private Instant updated;

11
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/database/AExperienceRole.java
View File

@@ -25,12 +25,15 @@ import java.util.List;
public class AExperienceRole implements Serializable {
/**
* The abstracto unique id of this experience role.
* The ID of the {@link ARole} to be awarded at a certain experience level
*/
@Id
@Column(name = "id")
private Long id;
/**
* Reference to the {@link ARole} which is being awarded for this configuration
*/
@OneToOne(fetch = FetchType.LAZY, cascade = {CascadeType.PERSIST, CascadeType.MERGE})
@PrimaryKeyJoinColumn
private ARole role;
@@ -51,9 +54,15 @@ public class AExperienceRole implements Serializable {
@JoinColumn(name = "server_id", nullable = false)
private AServer server;
/**
* The {@link Instant} this entity was created
*/
@Column(name = "created")
private Instant created;
/**
* The {@link Instant} this entity was updated
*/
@Column(name = "updated")
private Instant updated;

15
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/database/AUserExperience.java
View File

@@ -24,12 +24,15 @@ import java.time.Instant;
public class AUserExperience implements Serializable {
/**
* The {@link AUserInAServer} id which is unique for each user in a server.
* The ID of the {@link AUserInAServer user} which is represented by this object
*/
@Id
@Column(name = "id")
private Long id;
/**
* The {@link AUserInAServer user} which is represented by this object
*/
@OneToOne(fetch = FetchType.LAZY, cascade = {CascadeType.PERSIST, CascadeType.MERGE})
@PrimaryKeyJoinColumn
private AUserInAServer user;
@@ -57,22 +60,28 @@ public class AUserExperience implements Serializable {
private Boolean experienceGainDisabled;
/**
* The {@link AExperienceLevel } which the user currently has.
* The {@link AExperienceLevel level} which the user currently has.
*/
@OneToOne(fetch = FetchType.LAZY, cascade = CascadeType.PERSIST)
@JoinColumn(name = "level_id", nullable = false)
private AExperienceLevel currentLevel;
/**
* The {@link AExperienceRole} the user currently has. Can be null.
* The {@link AExperienceRole role} the user currently has. Can be null.
*/
@OneToOne(fetch = FetchType.LAZY, cascade = CascadeType.PERSIST)
@JoinColumn(name = "role_id")
private AExperienceRole currentExperienceRole;
/**
* The {@link Instant} this entity was created
*/
@Column(name = "created")
private Instant created;
/**
* The {@link Instant} this entity was updated
*/
@Column(name = "updated")
private Instant updated;

2
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/database/LeaderBoardEntryResult.java
View File

@@ -9,7 +9,7 @@ public interface LeaderBoardEntryResult {
/**
* The {@link dev.sheldan.abstracto.core.models.database.AUserInAServer} id of the user
* @return
* @return The ID of the user in a server
*/
Long getUserInServerId();

3
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/templates/DisabledExperienceRolesModel.java
View File

@@ -15,6 +15,9 @@ import java.util.List;
@Getter
@SuperBuilder
public class DisabledExperienceRolesModel extends UserInitiatedServerContext {
/**
* A list of {@link FullRole roles} for which experience gain is disabled in this server
*/
@Builder.Default
private List<FullRole> roles = new ArrayList<>();
}

9
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/templates/LeaderBoardEntryModel.java
View File

@@ -15,7 +15,16 @@ import java.io.Serializable;
@Getter
@Builder
public class LeaderBoardEntryModel implements Serializable {
/**
* The {@link AUserExperience experience} for this particular user in the server
*/
private AUserExperience experience;
/**
* The {@link Member member} associated wit this user experience, might be null if the user left he server.
*/
private transient Member member;
/**
* The position this {@link dev.sheldan.abstracto.core.models.database.AUserInAServer user} in this server has, ordered by experience {@link AUserExperience#experience}
*/
private Integer rank;
}

2
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/models/templates/RankModel.java
View File

@@ -20,7 +20,7 @@ public class RankModel extends SlimUserInitiatedServerContext {
*/
private LeaderBoardEntryModel rankUser;
/**
* The necessary experience until the next level up.
* The necessary experience to the next level up.
*/
private Long experienceToNextLevel;
}

60
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/service/AUserExperienceService.java
View File

@@ -19,43 +19,44 @@ import java.util.function.Function;
/**
* Service providing the required mechanisms to provide experience tracking.
* This includes manipulations on the {@link AUserExperience} table, container for the runtime experience, synchronizing the
* user in the guild and retrieving {@link LeaderBoard} data.
* This includes manipulations on the {@link AUserExperience userExperience} table, container for the runtime experience, synchronizing the
* user in the guild and retrieving {@link LeaderBoard leaderboard} data.
*/
public interface AUserExperienceService {
/**
* Adds the given {@link AUserInAServer} to the list of user who gained experience in the current minute.
* Adds the given {@link AUserInAServer userInAServer} to the list of user who gained experience in the current minute.
* Does not add the user to the list of users, if it is already in there.
* @param userInAServer The {@link AUserInAServer} to be added to the list of users gaining experience
* @param userInAServer The {@link AUserInAServer userInAServer} to be added to the list of users gaining experience
*/
void addExperience(AUserInAServer userInAServer);
/**
* Calculates the appropriate level of the given {@link AUserExperience} according to the given {@link AExperienceLevel}
* Calculates the appropriate level for the given experience amount according to the given {@link AExperienceLevel levels}
* configuration.
* @param levels The list of {@link AExperienceLevel} representing the level configuration, this must include the initial level 0
* This level will be taken as the initial value, and if no other level qualifies, this will be taken. The levels must be ordered.
* @param experienceCount
* @return The appropriate level of {@link AUserExperience} according to the provided {@link AExperienceLevel} configuration
* @param levels The list of {@link AExperienceLevel levels} representing the level configuration, this must include the initial level 0
* This level will be taken as the initial value, and if no other level qualifies, this will be taken. The levels **must** be ordered.
* @param experienceCount The amount of experience to calculate the level for
* @return The appropriate level of the given experience according to the provided {@link AExperienceLevel levels} configuration
*/
AExperienceLevel calculateLevel(List<AExperienceLevel> levels, Long experienceCount);
/**
* Calculates the new level of the provided {@link AUserExperience} according
* to the provided list of {@link AExperienceLevel} used as level configuration
* @param userExperience The {@link AUserExperience} to increase the experience for
* @param levels The list of {@link AExperienceLevel} to be used as level configuration
* @param experienceCount
* Calculates the new level of the provided {@link AUserExperience userExperience} according
* to the provided list of {@link AExperienceLevel levels} used as level configuration
* @param userExperience The {@link AUserExperience userExperience} to increase the experience for
* @param levels The list of {@link AExperienceLevel levels} to be used as level configuration
* @param experienceCount The amount of experience which will be added
* @return Whether or not the user changed level
*/
boolean updateUserLevel(AUserExperience userExperience, List<AExperienceLevel> levels, Long experienceCount);
/**
* Iterates through the given list of {@link AServer} and increases the experience of the users contained in the
* {@link AServer} object, also increments the level and changes the role if necessary.
* This uses the respective configurable max/minExp and multiplier for each {@link AServer} and increases the message count
* Iterates through the given list of {@link AServer servers} and increases the experience of the users contained in the
* {@link ServerExperience serverExperience} object, also increments the level and changes the role if necessary.
* This uses the respective configurable max/minExp and multiplier for each {@link AServer server} and increases the message count
* of each user by 1.
* @param serverExp The list of {@link AServer} containing the users which get experience
* @param serverExp The list of {@link AServer servers} containing the users which get experience
* @return A {@link CompletableFuture future} completing when the experience gain was calculated and roles were assigned
*/
CompletableFuture<Void> handleExperienceGain(List<ServerExperience> serverExp);
@@ -63,18 +64,20 @@ public interface AUserExperienceService {
* Calculates the currently appropriate {@link AExperienceRole} for the given user and updates the role on the
* {@link net.dv8tion.jda.api.entities.Member} and ond the {@link AUserExperience}. Effectively synchronizes the
* state in the server and the database.
* @param userExperience The {@link AUserExperience} object to recalculate the {@link AExperienceRole} for
* @param roles The list of {@link AExperienceRole} used as a role configuration
* @param userExperience The {@link AUserExperience userExperience} object to recalculate the {@link AExperienceRole experienceRole} for
* @param roles The list of {@link AExperienceRole roles} used as a role configuration
* @return A {@link CompletableFuture future} containing the {@link RoleCalculationResult result} of the role calculation,
* completing after the role of the {@link net.dv8tion.jda.api.entities.Member} has been updated, if any
*/
CompletableFuture<RoleCalculationResult> updateUserRole(AUserExperience userExperience, List<AExperienceRole> roles, Integer currentLevel);
/**
* Synchronizes the state ({@link AExperienceRole}, {@link net.dv8tion.jda.api.entities.Role})
* of all the users provided in the {@link AServer} object in the {@link AUserExperience}
* and on the {@link net.dv8tion.jda.api.entities.Member} according
* to how much experience the user has. Runs completely in the background.
* @param server The {@link AServer} to update the users for
* @return The list of {@link CompletableFuture futures} for each update of the users in the {@link AServer server}
*/
List<CompletableFuture<RoleCalculationResult>> syncUserRoles(AServer server);
@@ -82,11 +85,12 @@ public interface AUserExperienceService {
* Synchronizes the state ({@link AExperienceRole}, {@link net.dv8tion.jda.api.entities.Role})
* of all the users provided in the {@link AServer} object in the {@link AUserExperience}
* and on the {@link net.dv8tion.jda.api.entities.Member} according
* to how much experience the user has. This method provides feedback back to the user in the provided {@link AChannel}
* to how much experience the user has. This method provides feedback back to the user in the provided {@link AChannel channel}
* while the process is going own.
* @param server The {@link AServer} to update users for
* @param channel The {@link AChannel} in which the {@link dev.sheldan.abstracto.experience.models.templates.UserSyncStatusModel}
* @param channelId The ID of a {@link AChannel channel} in which the {@link dev.sheldan.abstracto.experience.models.templates.UserSyncStatusModel statusUpdate}
* should be posted to
* @return A {@link CompletableFuture future} which completes after all the role changes have been completed
*/
CompletableFuture<Void> syncUserRolesWithFeedback(AServer server, Long channelId);
@@ -94,6 +98,7 @@ public interface AUserExperienceService {
* Recalculates the role of a single user in a server and synchronize the {@link net.dv8tion.jda.api.entities.Role}
* in the {@link net.dv8tion.jda.api.entities.Guild}
* @param userExperience The {@link AUserExperience} to synchronize the role for
* @return A {@link CompletableFuture future} which completes after the roles have been synced for the given {@link AUserInAServer user}
*/
CompletableFuture<RoleCalculationResult> syncForSingleUser(AUserExperience userExperience);
@@ -121,7 +126,10 @@ public interface AUserExperienceService {
* template
* @param experiences The list of {@link AUserExperience} to be working on
* @param channel The {@link AChannel} used to provide feedback to the user
* @param toExecute The {@link Consumer} which should be executed on each element of the passed list
* @param toExecute The {@link Function} which should be executed on each element of the passed list,
* this function needs to take a {@link AUserExperience userExperience} as parameter and returns a {@link CompletableFuture}
* with a {@link RoleCalculationResult} for each of them. These futures are then returned.
* @return A {@link CompletableFutureList completeFutureList} which represents the individual {@link RoleCalculationResult results} and a primary future, which is completed after all of the individual ones are
*/
CompletableFutureList<RoleCalculationResult> executeActionOnUserExperiencesWithFeedBack(List<AUserExperience> experiences, AChannel channel, Function<AUserExperience, CompletableFuture<RoleCalculationResult>> toExecute);
@@ -137,5 +145,9 @@ public interface AUserExperienceService {
*/
void enableExperienceForUser(AUserInAServer userInAServer);
/**
* Updates the actually stored experience roles in the database
* @param results The list of {@link RoleCalculationResult} which should be updated in the database
*/
void syncRolesInStorage(List<RoleCalculationResult> results);
}

20
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/service/ExperienceLevelService.java
View File

@@ -1,31 +1,31 @@
package dev.sheldan.abstracto.experience.service;
/**
* Service responsible for operations on {@link dev.sheldan.abstracto.experience.models.database.AExperienceLevel}
* Service responsible for operations on {@link dev.sheldan.abstracto.experience.models.database.AExperienceLevel experienceLevel}
* This includes creating and calculations.
*/
public interface ExperienceLevelService {
/**
* Creates all the levels up until the given level.
* @param level The max level to create {@link dev.sheldan.abstracto.experience.models.database.AExperienceLevel} for
* @param level The max level to create {@link dev.sheldan.abstracto.experience.models.database.AExperienceLevel level} for
*/
void createLevelsUntil(Integer level);
/**
* Calculates the required experience until the next level is reached according to the current experience and
* current level.
* @param level The current level to base the calculation of
* @param currentExperience The current experience
* @return The amount of experience required necessary to get to one level higher as currently.
* Calculates the required experience until the next level is reached according to the provided experience and
* provided level.
* @param level The level to base the calculation of
* @param currentExperience The current total experience
* @return The amount of experience required necessary to reach the next level
*/
Long calculateExperienceToNextLevel(Integer level, Long currentExperience);
/**
* Calculates the required experience to reach this level. This calculated experience is relative, in the sense
* the returned experience is the increment from the experience requirement from the level before.
* Calculates the required experience to reach this level. This calculated experience is relative, in the sense that
* the returned experience is the difference between the level before the provided one
* @param level The level to calculate the experience amount for
* @return The needed experience to reach this level, if the user already has the level below the passed one
* @return The needed experience to reach this level, if the user already has the level below the provided one
*/
Long calculateExperienceForLevel(Integer level);
}

33
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/service/ExperienceRoleService.java
View File

@@ -11,36 +11,47 @@ import java.util.List;
import java.util.concurrent.CompletableFuture;
/**
* Service providing several methods surrounding {@link dev.sheldan.abstracto.experience.models.database.AExperienceRole}.
* Service providing several methods surrounding {@link dev.sheldan.abstracto.experience.models.database.AExperienceRole experienceRole}.
*/
public interface ExperienceRoleService {
/**
* Creates an {@link dev.sheldan.abstracto.experience.models.database.AExperienceRole} according to the given
* parameters
* @param role The {@link ARole} to set the level to
* @param level The level the {@link ARole} should be awarded at
* Creates an {@link dev.sheldan.abstracto.experience.models.database.AExperienceRole experienceRole} according to the given
* parameters. This actually updates the {@link net.dv8tion.jda.api.entities.Member members}
* which currently possessed the given role before and provides a display to see how far the progress is
* @param role The {@link ARole role} to set the level to
* @param level The new level the {@link ARole role} should be awarded at
* @param channelId The ID of the {@link dev.sheldan.abstracto.core.models.database.AChannel} in which the status updates
* should be sent to
* @return A {@link CompletableFuture future} which completes, after all the updates on the {@link net.dv8tion.jda.api.entities.Member}
* have been completed
*/
CompletableFuture<Void> setRoleToLevel(Role role, Integer level, Long channelId);
/**
* Removes the role from the {@link dev.sheldan.abstracto.experience.models.database.AExperienceRole} configuration
* Removes the role from the {@link dev.sheldan.abstracto.experience.models.database.AExperienceRole} configuration,
* this will also update all the {@link net.dv8tion.jda.api.entities.Member} which previously had this role and re-calculates
* a new {@link AExperienceRole experienceRole} for them while also updating them in the guild
* @param role The {@link ARole} to remove from the {@link dev.sheldan.abstracto.experience.models.database.AExperienceRole}
* configuration
* @param channelId The ID of the {@link dev.sheldan.abstracto.core.models.database.AChannel} in which the status updates
* should be sent to
* @return A {@link CompletableFuture future} which completes, after all the updates on the {@link net.dv8tion.jda.api.entities.Member}
* have been completed
*/
CompletableFuture<Void> unsetRole(ARole role, Long channelId);
/**
* Calculates the appropriate {@link AExperienceRole} based on the provided list of {@link AExperienceRole}
* @param roles The role configuration to be used when calculating the appropriate {@link AExperienceRole}
* @param currentLevel
* @return The best matching {@link AExperienceRole} according to the experience in the provided {@link AUserExperience}
* Calculates the appropriate {@link AExperienceRole experienceRole} based on the provided list of {@link AExperienceRole experienceRole}
* @param roles The role configuration to be used when calculating the appropriate {@link AExperienceRole experienceRole}
* @param currentLevel The level to calculate the {@link AExperienceRole experienceRole} for
* @return The best matching {@link AExperienceRole experienceRole} according to the experience in the provided {@link AUserExperience}
*/
AExperienceRole calculateRole(List<AExperienceRole> roles, Integer currentLevel);
/**
* Calculates the level at which the next role for a given level is available.
* For example, if the given {@link AExperienceLevel} is 5, and a a {@link AExperienceRole} is awarded at 8, but none in between, this method will return
* the {@link AExperienceLevel} 8.
* the {@link AExperienceLevel}.
* @param startLevel The {@link AExperienceLevel} to start off at
* @param server The {@link AServer} to use for the {@link AExperienceRole} configuration
* @return The next {@link AExperienceLevel} a {@link AExperienceRole} is awarded at, this will be null if there are no roles or there is no further role to reach

26
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/service/management/DisabledExpRoleManagementService.java
View File

@@ -12,31 +12,31 @@ import java.util.List;
public interface DisabledExpRoleManagementService {
/**
* Creates an instance of {@link ADisabledExpRole} which marks the {@link ARole} as disabled. This effectively means, that the experience is disabled for members
* which have the {@link ARole}
* @param role The {@link ARole} which should be used as a role to disable experience
* @return The create instance of {@link ADisabledExpRole}
* Creates an instance of {@link ADisabledExpRole experienceRole} which marks the {@link ARole role} as disabled. This effectively means, that the experience is disabled for members
* which have the {@link ARole role}
* @param role The {@link ARole role} which should be used as a role to disable experience
* @return The created instance of {@link ADisabledExpRole experienceRole}
*/
ADisabledExpRole setRoleToBeDisabledForExp(ARole role);
/**
* Removes the given {@link ARole} from the list of roles which had their experience gain disabled. This method removes the instance from the list of
* {@link ADisabledExpRole} and enables experience for the given {@link ARole}
* @param role The {@link ARole} to enable experience for
* Removes the given {@link ARole role} from the list of roles which had their experience gain disabled. This method removes the instance from the list of
* {@link ADisabledExpRole roles} and enables experience for the given {@link ARole role}
* @param role The {@link ARole role} to enable experience for
*/
void removeRoleToBeDisabledForExp(ARole role);
/**
* Retrieves all the {@link ADisabledExpRole} roles for a given {@link AServer}, which means, it returns all roles for which there is
* @param server The {@link AServer} to retrieve all {@link ADisabledExpRole} for
* @return A List of {@link ADisabledExpRole} which are currently on the {@link AServer}
* Retrieves all the {@link ADisabledExpRole experienceRole} roles for a given {@link AServer server}
* @param server The {@link AServer server} to retrieve all {@link ADisabledExpRole roles} for
* @return A List of {@link ADisabledExpRole roles} which are currently configured for the {@link AServer server}
*/
List<ADisabledExpRole> getDisabledRolesForServer(AServer server);
/**
* Checks if the given {@link ARole} has its experience disabled and returns true if so
* @param role The {@link ARole} to check for
* @return Whether or not the given {@link ARole} has the experience disabled.
* Checks if the given {@link ARole role} has its experience disabled and returns true if so
* @param role The {@link ARole role} to check for
* @return Whether or not the given {@link ARole role} has the experience disabled.
*/
boolean isExperienceDisabledForRole(ARole role);
}

16
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/service/management/ExperienceLevelManagementService.java
View File

@@ -6,34 +6,34 @@ import java.util.List;
import java.util.Optional;
/**
* Service responsible to create and retrieve {@link AExperienceLevel} objects in the database.
* Service responsible to create and retrieve {@link AExperienceLevel levels} objects in the database.
*/
public interface ExperienceLevelManagementService {
/**
* Creates the level referenced by the level and the needed experience in the database.
* @param level The unique level this level should represent.
* @param neededExperience The total amount of experience required to reach this level.
* @return A newly created {@link AExperienceLevel} instance.
* @return A newly created {@link AExperienceLevel level} instance.
*/
AExperienceLevel createExperienceLevel(Integer level, Long neededExperience);
/**
* Checks if a {@link AExperienceLevel} level indicated by the level exists in the database. Returns true if it does.
* Checks if a {@link AExperienceLevel level} indicated by the level exists in the database. Returns true if it does.
* @param level The integer of the level to check for.
* @return A boolean indicating whether or not the level exists in the database.
*/
boolean levelExists(Integer level);
/**
* Retrieves a {@link AExperienceLevel} according to the given level.
* @param level The level of the wanted {@link AExperienceLevel} to look for
* @return Returns an optional containing the {@link AExperienceLevel} if it exists, and null otherwise
* Retrieves a {@link AExperienceLevel level} according to the given level.
* @param level The {@link AExperienceLevel level} of the wanted level number
* @return Returns an optional containing the {@link AExperienceLevel level} if it exists, and empty otherwise
*/
Optional<AExperienceLevel> getLevel(Integer level);
/**
* Loads the complete level configuration and returns all found {@link AExperienceLevel} objects from the database.
* @return A list of {@link AExperienceLevel} objects representing the currently active configuration.
* Loads the complete level configuration and returns all found {@link AExperienceLevel levels} from the database.
* @return A list of {@link AExperienceLevel levels} representing the currently active configuration.
*/
List<AExperienceLevel> getLevelConfig();
}

52
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/service/management/ExperienceRoleManagementService.java
View File

@@ -9,50 +9,66 @@ import java.util.List;
import java.util.Optional;
/**
* Service responsible to manage the {@link AExperienceRole} configuration of a server. This contains functionality to
* set/unset a level to a certain role, retrieve {@link AExperienceRole} of a certain role and load all for a given
* Service responsible to manage the {@link AExperienceRole experienceRole} configuration of a server. This contains functionality to
* set/unset a level to a certain role, retrieve a {@link AExperienceRole experienceRole} of a certain role and load all for a given
* server.
*/
public interface ExperienceRoleManagementService {
/**
* Sets the given {@link AExperienceLevel} to the given {@link ARole} in the {@link AServer}. This will create an
* {@link AExperienceRole} instance and store it. If the role was already set in the server, this sets this role to
* Sets the given {@link AExperienceLevel level} to the given {@link ARole role} in the {@link AServer server}. This will create an
* {@link AExperienceRole experienceRole} instance and store it. If the role was already set in the server, this sets this role to
* the new level.
* @param level The {@link AExperienceLevel} to set the role for
* @param role The {@link ARole} to set to
* @return the created or updated {@link AExperienceRole}
* @param level The {@link AExperienceLevel experienceRole} to set the role for
* @param role The {@link ARole role} to set
* @return the created or updated {@link AExperienceRole experienceRole}
*/
AExperienceRole setLevelToRole(AExperienceLevel level, ARole role);
/**
* Deletes *all* (if there are multiple by some chance) roles which were set to be given at the provided {@link AExperienceLevel} in the {@link AServer}
* Deletes *all* (if there are multiple by some chance) roles which were set to be given at the provided {@link AExperienceLevel level} in the {@link AServer server}
* @param level The level to remove the roles for
* @param server The server in which this should happen
*/
void removeAllRoleAssignmentsForLevelInServer(AExperienceLevel level, AServer server);
/**
* Deletes a singular {@link AExperienceRole} directly.
* @param role The {@link AExperienceRole} to delete.
* Deletes a singular {@link AExperienceRole experienceRole} directly.
* @param role The {@link AExperienceRole experienceRole} to delete.
*/
void unsetRole(AExperienceRole role);
/**
* Retrieves the {@link AExperienceRole} which uses the given {@link ARole} in the {@link AServer}
* @param role The {@link ARole} to search for
* @return the {@link AExperienceRole} which uses the given {@link ARole}
* Retrieves the {@link AExperienceRole experienceRole} which uses the given {@link ARole role} in the {@link AServer server}
* @param role The {@link ARole role} to search for
* @return the {@link AExperienceRole experienceRole} which uses the given {@link ARole role}
*/
AExperienceRole getRoleInServer(ARole role);
Optional<AExperienceRole> getRoleInServerOptional(ARole role);
AExperienceRole getRoleInServer(Long roleId);
/**
* Retrieves all {@link AExperienceRole} configured in the given {@link AServer}
* @param server The server to retrieve the list of {@link AExperienceRole} for
* @return A list of {@link AExperienceRole} which are currently configured for the {@link AServer}
* Retrieves a possible {@link AExperienceRole role}, if it exists, for the given {@link ARole}. Returns an empty Optional if it does not exist
* @param role The {@link ARole role} to search for
* @return An {@link Optional optional} either empty or containing the {@link AExperienceRole role}
*/
Optional<AExperienceRole> getRoleInServerOptional(ARole role);
/**
* Retrieves all {@link AExperienceRole experienceRoles} configured in the given {@link AServer server}
* @param server The server to retrieve the list of {@link AExperienceRole experienceRoles} for
* @return A list of {@link AExperienceRole experienceRoles} which are currently configured for the {@link AServer server}
*/
List<AExperienceRole> getExperienceRolesForServer(AServer server);
/**
* Retrieves the {@link AExperienceRole experienceRole} by the given ID of a {@link ARole}.
* @param experienceRoleId The ID of the {@link ARole role} (which is the same as the {@link AExperienceRole experienceRole}) to retrieve the {@link AExperienceRole experienceRole} for
* @return The found {@link AExperienceRole experienceRole}
*/
AExperienceRole getExperienceRoleById(Long experienceRoleId);
/**
* Retrieves the {@link AExperienceRole experienceRole} in an {@link Optional optional} by the given ID of a {@link ARole}.
* @param experienceRoleId The ID of the {@link ARole role} (which is the same as the {@link AExperienceRole experienceRole}) to retrieve the {@link AExperienceRole experienceRole} for
* @return An {@link Optional optional} containing the found {@link AExperienceRole experienceRole} or empty otherwise
*/
Optional<AExperienceRole> getExperienceRoleByIdOptional(Long experienceRoleId);
}

24
abstracto-application/abstracto-modules/experience-tracking/experience-tracking-int/src/main/java/dev/sheldan/abstracto/experience/service/management/UserExperienceManagementService.java
View File

@@ -10,17 +10,29 @@ import java.util.List;
import java.util.Optional;
/**
* Service used to manage the record in the {@link AUserExperience} table
* Service used to manage the record in the {@link AUserExperience userExperience} table
*/
public interface UserExperienceManagementService {
/**
* Retrieves the {@link AUserExperience} object for the given {@link AUserInAServer}
* @param aUserInAServer The record in the table referenced by the given {@link AUserInAServer}, if none exists, creates one.
* @return The {@link AUserExperience} object representing the {@link AUserInAServer}
* Retrieves the {@link AUserExperience userExperience} object for the given {@link AUserInAServer userInAServer}
* @param aUserInAServer The record in the table referenced by the given {@link AUserInAServer userInAServer}, if none exists, creates one.
* @return The {@link AUserExperience userExperience} object representing the {@link AUserInAServer userInAServer}
*/
AUserExperience findUserInServer(AUserInAServer aUserInAServer);
/**
* Retrieves a possible {@link AUserExperience userExperience} for the given ID of the {@link AUserInAServer}.
* If none is found, returns an empty {@link Optional optional}
* @param userInServerId The ID of a {@link AUserInAServer} to search for
* @return An {@link Optional optional} containing a {@link AUserExperience userExperience} object if one is found, none otherwise
*/
Optional<AUserExperience> findByUserInServerIdOptional(Long userInServerId);
/**
* Retrieves the {@link AUserExperience userExperience} object for the given ID of an {@link AUserInAServer userInAServer}
* @param userInServerId The ID of a {@link AUserInAServer userInAServer} to retrieve the {@link AUserExperience} for.
* @return The {@link AUserExperience userExperience} object representing the {@link AUserInAServer userInAServer}
*/
AUserExperience findByUserInServerId(Long userInServerId);
/**
@@ -38,11 +50,11 @@ public interface UserExperienceManagementService {
List<AUserExperience> loadAllUsers(AServer server);
/**
* Retrieves a list of {@link AUserExperience} ordered by {@link AUserExperience.experience} and only returns the positions between {@code start} and @{code end}.
* Retrieves a list of {@link AUserExperience} ordered by {@link AUserExperience#experience} and only returns the positions between {@code start} and @{code end}.
* @param server The {@link AServer} to retrieve the users for
* @param start The start index in the complete ordered list to return the {@link AUserExperience} elements for
* @param end The end index for which to return a sublist of {@link AUserExperience} elements for
* @return A list desc ordered by {@link AUserExperience.experience} only containing the elements between {@code start} and @{code end}
* @return A list desc ordered by {@link AUserExperience#experience} only containing the elements between {@code start} and @{code end}
*/
List<AUserExperience> findLeaderBoardUsersPaginated(AServer server, Integer start, Integer end);