Merge pull request #48 from OneLiteFeatherNET/beta

feat: Improve entity queries and documentation

Author: theEvilReaper

src/main/java/net/onelitefeather/vulpes/api/generator/UuidV7Generator.java

@@ -9,13 +9,34 @@
 
 import static org.hibernate.generator.EventTypeSets.INSERT_ONLY;
 
+/**
+ * The {@link UuidV7Generator} class implements a generator that creates time-ordered UUIDs (version 7) for new entities.
+ *
+ * @author TheMeinerLP
+ * @version 1.0.0
+ * @since 0.1.0
+ */
 public final class UuidV7Generator implements BeforeExecutionGenerator {
 
+    /**
+     * Generates a time-ordered UUID (version 7) for the given entity.
+     *
+     * @param session      the session in which the entity is being created
+     * @param owner        the owner of the entity
+     * @param currentValue the current value of the UUID field (not used)
+     * @param eventType    the type of event triggering this generation (should be INSERT)
+     * @return a new time-ordered UUID
+     */
     @Override
     public Object generate(SharedSessionContractImplementor session, Object owner, Object currentValue, EventType eventType) {
         return UuidCreator.getTimeOrderedEpoch();
     }
 
+    /**
+     * Returns the set of event types for which this generator is applicable.
+     *
+     * @return an EnumSet containing the INSERT_ONLY event type
+     */
     @Override
     public EnumSet<EventType> getEventTypes() {
         return INSERT_ONLY;

src/main/java/net/onelitefeather/vulpes/api/generator/VulpesGenerator.java

@@ -9,8 +9,22 @@
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Annotation to mark a field or method for UUIDv7-based ID generation within the Vulpes model.
+ * <p>
+ * This annotation is a specialization that applies {@link UuidV7Generator} as the ID generation strategy.
+ * It can be applied to fields or methods to instruct the persistence framework to generate a UUIDv7
+ * when persisting the entity.
+ * </p>
+ *
+ * @author TheMeinerLP
+ * @version 1.0.0
+ * @see UuidV7Generator
+ * @see IdGeneratorType
+ * @since 0.1.0
+ */
 @IdGeneratorType(UuidV7Generator.class)
 @Retention(RUNTIME)
-@Target({METHOD,FIELD})
+@Target({METHOD, FIELD})
 public @interface VulpesGenerator {
 }

src/main/java/net/onelitefeather/vulpes/api/model/FontEntity.java

@@ -55,6 +55,7 @@ public FontEntity() {
      * @param variableName the variable name of the font
      * @param provider     the provider of the font
      * @param texturePath  the path to the texture of the font
+     * @param comment      a comment or description for the font
      * @param height       the height of the font
      * @param ascent       the ascent of the font
      * @param chars        the list of characters included in the font

src/main/java/net/onelitefeather/vulpes/api/model/NotificationEntity.java

@@ -44,11 +44,13 @@ public NotificationEntity() {
     /**
      * Constructs a new {@link NotificationEntity} with the specified values.
      *
-     * @param id        the unique identifier of the notification
-     * @param comment   a comment for the description
-     * @param material  the material type associated with the notification
-     * @param frameType the frame type associated with the notification
-     * @param title     the title of the notification
+     * @param id           the unique identifier of the notification
+     * @param uiName       the user interface name of the notification
+     * @param variableName the variable name of the notification
+     * @param comment      a comment for the description
+     * @param material     the material type associated with the notification
+     * @param frameType    the frame type associated with the notification
+     * @param title        the title of the notification
      */
     public NotificationEntity(UUID id, String uiName, String variableName, String comment, String material, String frameType, String title) {
         this.id = id;

src/main/java/net/onelitefeather/vulpes/api/model/VulpesModel.java

@@ -1,4 +1,15 @@
 package net.onelitefeather.vulpes.api.model;
 
+/**
+ * Marker interface for classes that are part of the Vulpes model definition.
+ * <p>
+ * This interface is used to restrict certain functionality or behavior to classes
+ * that explicitly implement it, serving as a means of semantic grouping within the model layer.
+ * </p>
+ *
+ * @author theEvilReaper
+ * @version 1.0.0
+ * @since 0.1.0
+ */
 public interface VulpesModel {
 }

src/main/java/net/onelitefeather/vulpes/api/model/sound/SoundEventEntity.java

@@ -1,5 +1,6 @@
 package net.onelitefeather.vulpes.api.model.sound;
 
+import jakarta.persistence.Column;
 import jakarta.persistence.Entity;
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.GenerationType;
@@ -33,6 +34,7 @@ public class SoundEventEntity implements VulpesModel {
     private String uiName;
     private String variableName;
     private String keyName;
+    @Column(name = "replace_flag")
     @ColumnDefault("false")
     private boolean replace;
     @ColumnDefault("null")

src/main/java/net/onelitefeather/vulpes/api/model/sound/SoundFileSource.java

@@ -4,6 +4,8 @@
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.GenerationType;
 import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
 import net.onelitefeather.vulpes.api.generator.VulpesGenerator;
 import net.onelitefeather.vulpes.api.model.VulpesModel;
 import org.hibernate.annotations.ColumnDefault;
@@ -38,9 +40,13 @@ public class SoundFileSource implements VulpesModel {
     private int attenuationDistance;
     @ColumnDefault("false")
     private boolean preload;
-    @ColumnDefault("file")
+    @ColumnDefault("'type_file'")
     private String type;
 
+    @ManyToOne
+    @JoinColumn(name = "sound_event_id")
+    private SoundEventEntity soundEvent;
+
     /**
      * Default constructor for JPA and Micronaut Data.
      * <p>
@@ -232,6 +238,14 @@ public boolean isStreamable() {
         return stream;
     }
 
+    public SoundEventEntity getSoundEvent() {
+        return soundEvent;
+    }
+
+    public void setSoundEvent(SoundEventEntity soundEvent) {
+        this.soundEvent = soundEvent;
+    }
+
     @Override
     public boolean equals(Object o) {
         if (o == null || getClass() != o.getClass()) return false;

src/main/java/net/onelitefeather/vulpes/api/repository/AttributeRepository.java

@@ -6,6 +6,13 @@
 
 import java.util.UUID;
 
+/**
+ * The {@link AttributeRepository} interface inherits from {@link PageableRepository} and provides methods to manage {@link AttributeEntity} objects.
+ *
+ * @author theEvilReaper
+ * @version 1.0.0
+ * @since 0.1.0
+ */
 @Repository
 public interface AttributeRepository extends PageableRepository<AttributeEntity, UUID> {
 }

src/main/java/net/onelitefeather/vulpes/api/repository/FontRepository.java

@@ -2,12 +2,20 @@
 
 import io.micronaut.data.annotation.Query;
 import io.micronaut.data.annotation.Repository;
+import io.micronaut.data.model.Pageable;
 import io.micronaut.data.repository.PageableRepository;
 import net.onelitefeather.vulpes.api.model.FontEntity;
 
 import java.util.List;
 import java.util.UUID;
 
+/**
+ * The {@link FontRepository} interface inherits from {@link PageableRepository} and provides methods to manage {@link FontEntity} objects.
+ *
+ * @author theEvilReaper
+ * @version 1.0.0
+ * * @since 0.1.0
+ */
 @Repository
 public interface FontRepository extends PageableRepository<FontEntity, UUID> {
 
@@ -17,6 +25,17 @@ public interface FontRepository extends PageableRepository<FontEntity, UUID> {
      * @param id the unique identifier of the font
      * @return a list of characters associated with the font
      */
-    @Query("SELECT c FROM fonts f JOIN f.chars c WHERE f.id = :id")
-    List<String> findCharsByFontId(UUID id);
+    @Query(
+            value = "SELECT c FROM fonts f JOIN f.chars c WHERE f.id = :id",
+            countQuery = "SELECT COUNT(c) FROM fonts f JOIN f.chars c WHERE f.id = :id"
+    )
+    List<String> findCharsByFontId(UUID id, Pageable pageable);
+
+    /**
+     * Retrieves all fonts along with their associated characters.
+     *
+     * @return a list of all FontEntity objects with their characters
+     */
+    @Query("select f from fonts f JOIN FETCH f.chars")
+    List<FontEntity> findAll();
 }

src/main/java/net/onelitefeather/vulpes/api/repository/ItemRepository.java

@@ -2,13 +2,21 @@
 
 import io.micronaut.data.annotation.Query;
 import io.micronaut.data.annotation.Repository;
+import io.micronaut.data.model.Pageable;
 import io.micronaut.data.repository.PageableRepository;
 import net.onelitefeather.vulpes.api.model.ItemEntity;
 
 import java.util.List;
 import java.util.Map;
 import java.util.UUID;
 
+/**
+ * The {@link ItemRepository} interface inherits from {@link PageableRepository} and provides methods to manage {@link ItemEntity} objects.
+ *
+ * @author theEvilReaper
+ * @version 1.0.0
+ * @since 0.1.0
+ */
 @Repository
 public interface ItemRepository extends PageableRepository<ItemEntity, UUID> {
 
@@ -18,24 +26,42 @@ public interface ItemRepository extends PageableRepository<ItemEntity, UUID> {
      * @param id the unique identifier of the item
      * @return a map of enchantment names and their levels associated with the item
      */
-    @Query("SELECT e FROM items i JOIN i.enchantments e WHERE i.id = :id")
-    Map<String, Short> findEnchantmentsById(UUID id);
+    @Query(value = "SELECT e FROM items i JOIN i.enchantments e WHERE i.id = :id",
+            countQuery = "SELECT count(e) FROM items i JOIN i.enchantments e WHERE i.id = :id"
+    )
+    Map<String, Short> findEnchantmentsById(UUID id, Pageable pageable);
 
     /**
      * Retrieves the lore associated with an item by its ID.
      *
      * @param id the unique identifier of the item
      * @return a list of lore strings associated with the item
      */
-    @Query("SELECT l FROM items i JOIN i.enchantments l WHERE i.id = :id")
-    List<String> findLoreById(UUID id);
+    @Query(value = "SELECT l FROM items i JOIN i.lore l WHERE i.id = :id",
+            countQuery = "SELECT count(l) FROM items i JOIN i.lore l WHERE i.id = :id"
+    )
+    List<String> findLoreById(UUID id, Pageable pageable);
 
     /**
      * Retrieves the flags associated with an item by its ID.
      *
      * @param id the unique identifier of the item
      * @return a list of flags associated with the item
      */
-    @Query("SELECT f FROM items i JOIN i.enchantments f WHERE i.id = :id")
-    List<String> findFlagsById(UUID id);
+    @Query(value = "SELECT f FROM items i JOIN i.flags f WHERE i.id = :id",
+            countQuery = "SELECT count(f) FROM items i JOIN i.flags f WHERE i.id = :id"
+    )
+    List<String> findFlagsById(UUID id, Pageable pageable);
+
+
+    /**
+     * Retrieves all items along with their associated enchantments, lore, and flags.
+     *
+     * @return a list of all ItemEntity objects with their enchantments, lore, and flags
+     */
+    @Query(
+            value = "SELECT i FROM items i LEFT JOIN FETCH i.enchantments LEFT JOIN FETCH i.lore LEFT JOIN FETCH i.flags",
+            countQuery = "SELECT count(i) FROM items i"
+    )
+    List<ItemEntity> findAllWithFetches(Pageable pageable);
 }