From 5b9c6fee7ede88a0ea1a61bebd670c6fc97aa532 Mon Sep 17 00:00:00 2001 From: "alexis.drai@etu.uca.fr" Date: Fri, 16 Jun 2023 16:28:48 +0200 Subject: [PATCH] :memo: Add some Javadoc where it's most useful --- .../java/fr/uca/iut/codecs/GenericCodec.java | 46 +++++++++++++++ .../iut/controllers/GenericController.java | 39 +++++++++++++ .../fr/uca/iut/entities/GenericEntity.java | 5 ++ .../iut/entities/GenericVersionedEntity.java | 9 ++- .../iut/repositories/GenericRepository.java | 58 +++++++++++++++++++ .../uca/iut/repositories/MoveRepository.java | 1 - .../iut/repositories/PokemongRepository.java | 1 - .../iut/repositories/TrainerRepository.java | 1 - .../fr/uca/iut/services/GenericService.java | 55 +++++++++++++++++- 9 files changed, 205 insertions(+), 10 deletions(-) diff --git a/src/main/java/fr/uca/iut/codecs/GenericCodec.java b/src/main/java/fr/uca/iut/codecs/GenericCodec.java index ed21526..ec3898e 100644 --- a/src/main/java/fr/uca/iut/codecs/GenericCodec.java +++ b/src/main/java/fr/uca/iut/codecs/GenericCodec.java @@ -11,14 +11,39 @@ import org.bson.codecs.EncoderContext; import org.bson.types.ObjectId; import org.jetbrains.annotations.NotNull; +/** + * An abstract codec class for encoding and decoding entities to and from BSON. + * The specific type of entity is defined by the generic parameter T, which extends GenericEntity. + * This class implements the CollectibleCodec interface. + */ public abstract class GenericCodec implements CollectibleCodec { + /** + * Encodes the entity into BSON. + * This method must be overridden by subclasses. + * + * @param writer The BsonWriter to write the BSON. + * @param entity The entity to encode. + * @param encoderContext The context for encoding. + */ @Override public abstract void encode(BsonWriter writer, T entity, EncoderContext encoderContext); + /** + * Returns the class of the entity being encoded. + * This method must be overridden by subclasses. + * + * @return The class of the entity being encoded. + */ @Override public abstract Class getEncoderClass(); + /** + * Generates an ID for the document if it doesn't have one. + * + * @param document The document to possibly assign an ID to. + * @return The document with an ID assigned, if it didn't have one. + */ @Override public T generateIdIfAbsentFromDocument(T document) { if (!documentHasId(document)) { @@ -27,16 +52,37 @@ public abstract class GenericCodec implements Collectib return document; } + /** + * Checks if a document has an ID. + * + * @param document The document to check. + * @return true if the document has an ID, false otherwise. + */ @Override public boolean documentHasId(@NotNull T document) { return document.getId() != null; } + /** + * Returns the ID of the document. + * + * @param document The document whose ID to get. + * @return The ID of the document. + */ @Override public BsonValue getDocumentId(@NotNull T document) { return new BsonObjectId(new ObjectId(document.getId())); } + + /** + * Decodes a BSON document into an entity. + * This method must be overridden by subclasses. + * + * @param reader The BsonReader from which to read the BSON. + * @param decoderContext The context for decoding. + * @return The decoded entity. + */ @Override public abstract T decode(BsonReader reader, DecoderContext decoderContext); } diff --git a/src/main/java/fr/uca/iut/controllers/GenericController.java b/src/main/java/fr/uca/iut/controllers/GenericController.java index 6c11aeb..a215651 100644 --- a/src/main/java/fr/uca/iut/controllers/GenericController.java +++ b/src/main/java/fr/uca/iut/controllers/GenericController.java @@ -7,14 +7,29 @@ import jakarta.ws.rs.*; import jakarta.ws.rs.core.MediaType; import jakarta.ws.rs.core.Response; +/** + * An abstract controller class providing CRUD operations for entities. + * The specific type of entity is defined by the generic parameter T, which extends GenericEntity. + */ public abstract class GenericController { protected GenericService service; + /** + * Sets the service to be used by this controller. + * + * @param service The service to be used by this controller. + */ public void setService(GenericService service) { this.service = service; } + /** + * Retrieves an entity by its ID. + * + * @param id The ID of the entity to retrieve. + * @return A Response object containing the entity, or an error message if the entity does not exist. + */ @GET @Path("/{id}") public Response getOneById(@PathParam("id") String id) { @@ -35,12 +50,23 @@ public abstract class GenericController { } } + /** + * Retrieves all entities. + * + * @return A Response object containing a list of all entities. + */ @GET public Response getAll() { return Response.ok(service.getAll()) .build(); } + /** + * Creates a new entity. + * + * @param entity The entity to create. + * @return A Response object containing the created entity, or an error message if the entity is not valid. + */ @POST @Consumes(MediaType.APPLICATION_JSON) public Response createOne(T entity) { @@ -59,6 +85,13 @@ public abstract class GenericController { } } + /** + * Updates an existing entity. + * + * @param id The ID of the entity to update. + * @param entity The updated entity. + * @return A Response object containing the updated entity, or an error message if the entity is not found or not valid. + */ @PUT @Path("/{id}") @Consumes(MediaType.APPLICATION_JSON) @@ -83,6 +116,12 @@ public abstract class GenericController { } } + /** + * Deletes an entity by its ID. + * + * @param id The ID of the entity to delete. + * @return A Response object indicating success, or an error message if the entity is not found. + */ @DELETE @Path("/{id}") public Response deleteOneById(@PathParam("id") String id) { diff --git a/src/main/java/fr/uca/iut/entities/GenericEntity.java b/src/main/java/fr/uca/iut/entities/GenericEntity.java index f98460a..c5294b9 100644 --- a/src/main/java/fr/uca/iut/entities/GenericEntity.java +++ b/src/main/java/fr/uca/iut/entities/GenericEntity.java @@ -4,6 +4,11 @@ import org.bson.codecs.pojo.annotations.BsonId; import java.util.Objects; +/** + * Abstract entity class that provides common properties and methods for all entities in the system. + * Entities extending this class will automatically have an ID field, along with associated getter and setter, + * and overridden hashCode and equals methods based on the ID field. + */ public abstract class GenericEntity { @BsonId diff --git a/src/main/java/fr/uca/iut/entities/GenericVersionedEntity.java b/src/main/java/fr/uca/iut/entities/GenericVersionedEntity.java index 7ede19a..cf60fb8 100644 --- a/src/main/java/fr/uca/iut/entities/GenericVersionedEntity.java +++ b/src/main/java/fr/uca/iut/entities/GenericVersionedEntity.java @@ -1,11 +1,10 @@ package fr.uca.iut.entities; /** - * The strategy for incrementing the schema version number is simple. - *

- * `schemaVersion` will have to start at 1, and need to be incremented by one at each schema change. - *

- * Every change to the schema needs to involve the schema version number being incremented. + * Abstract entity class that extends GenericEntity to include versioning of the schema. + * The strategy for incrementing the schema version number is simple: `schemaVersion` will have to start at 1, + * and need to be incremented by one at each schema change. Every change to the schema needs to involve + * the schema version number being incremented. */ public abstract class GenericVersionedEntity extends GenericEntity { diff --git a/src/main/java/fr/uca/iut/repositories/GenericRepository.java b/src/main/java/fr/uca/iut/repositories/GenericRepository.java index 71b208a..1327e45 100644 --- a/src/main/java/fr/uca/iut/repositories/GenericRepository.java +++ b/src/main/java/fr/uca/iut/repositories/GenericRepository.java @@ -17,32 +17,72 @@ import java.util.List; import static com.mongodb.client.model.Filters.eq; +/** + * Abstract repository class for managing database operations for entities of type T, + * where T extends the GenericEntity class. This class should be extended by other repository classes + * that implement specific operations for certain types of entities. + * + * @param The type of entity this repository manages. Must extend GenericEntity. + */ public abstract class GenericRepository { protected MongoClient mongoClient; @ConfigProperty(name = "quarkus.mongodb.database") String DB_NAME; + /** + * Sets the MongoDB client instance to be used by this repository. + * + * @param mongoClient The MongoDB client instance. + */ public void setMongoClient(MongoClient mongoClient) { this.mongoClient = mongoClient; } + /** + * Finds an entity by its ID. + * + * @param id The ID of the entity. + * @return The found entity, or null if no entity with the given ID exists. + */ @Nullable public T findById(String id) { return getCollection().find(eq("_id", new ObjectId(id))) .first(); } + /** + * Returns the MongoDB collection associated with this repository. + * The specific collection depends on the type T of the entities managed by the repository. + * + * @return The MongoDB collection of entities of type T. + */ protected abstract MongoCollection getCollection(); + /** + * Inserts an entity into the collection. + * + * @param entity The entity to insert. Must not be null. + */ public void persist(@NotNull T entity) { getCollection().insertOne(entity); } + /** + * Finds all entities in the collection. + * + * @return A list of all entities in the collection. + */ public List listAll() { return getCollection().find() .into(new ArrayList<>()); } + /** + * Replaces an existing entity in the collection with the provided entity. + * If the entity does not exist, it is inserted. + * + * @param entity The entity to replace or insert. Must not be null. + */ public void persistOrUpdate(@NotNull T entity) { getCollection().replaceOne( eq("_id", new ObjectId(entity.getId())), @@ -51,6 +91,13 @@ public abstract class GenericRepository { ); } + /** + * Updates all entities in the provided list. + * Each entity in the list replaces an existing entity in the collection with the same ID. + * If an entity does not exist, it is inserted. + * + * @param entities The list of entities to update. + */ public void updateAll(@NotNull List entities) { List> updates = new ArrayList<>(); for (T entity : entities) { @@ -66,10 +113,21 @@ public abstract class GenericRepository { getCollection().bulkWrite(updates); } + /** + * Deletes an entity from the collection. + * + * @param entity The entity to delete. Must not be null. + */ public void delete(@NotNull T entity) { getCollection().deleteOne(eq("_id", new ObjectId(entity.getId()))); } + /** + * Checks if an entity with the given ID exists in the collection. + * + * @param id The ID of the entity. + * @return true if an entity with the given ID exists, false otherwise. + */ public boolean existsById(String id) { Document query = new Document("_id", new ObjectId(id)); return getCollection().countDocuments(query) > 0; diff --git a/src/main/java/fr/uca/iut/repositories/MoveRepository.java b/src/main/java/fr/uca/iut/repositories/MoveRepository.java index 0226f04..a8726c3 100644 --- a/src/main/java/fr/uca/iut/repositories/MoveRepository.java +++ b/src/main/java/fr/uca/iut/repositories/MoveRepository.java @@ -11,7 +11,6 @@ import jakarta.inject.Inject; @ApplicationScoped public class MoveRepository extends GenericRepository { - // FIX?ME /** * Warns that "Unsatisfied dependency: no bean matches the injection point" * but the app works diff --git a/src/main/java/fr/uca/iut/repositories/PokemongRepository.java b/src/main/java/fr/uca/iut/repositories/PokemongRepository.java index 6e3c634..703f60e 100644 --- a/src/main/java/fr/uca/iut/repositories/PokemongRepository.java +++ b/src/main/java/fr/uca/iut/repositories/PokemongRepository.java @@ -17,7 +17,6 @@ import java.util.List; @ApplicationScoped public class PokemongRepository extends GenericRepository { - // FIX?ME /** * Warns that "Unsatisfied dependency: no bean matches the injection point" * but the app works diff --git a/src/main/java/fr/uca/iut/repositories/TrainerRepository.java b/src/main/java/fr/uca/iut/repositories/TrainerRepository.java index 35ff7ed..30eb66e 100644 --- a/src/main/java/fr/uca/iut/repositories/TrainerRepository.java +++ b/src/main/java/fr/uca/iut/repositories/TrainerRepository.java @@ -11,7 +11,6 @@ import jakarta.inject.Inject; @ApplicationScoped public class TrainerRepository extends GenericRepository { - // FIX?ME /** * Warns that "Unsatisfied dependency: no bean matches the injection point" * but the app works diff --git a/src/main/java/fr/uca/iut/services/GenericService.java b/src/main/java/fr/uca/iut/services/GenericService.java index e3bdb41..9032499 100644 --- a/src/main/java/fr/uca/iut/services/GenericService.java +++ b/src/main/java/fr/uca/iut/services/GenericService.java @@ -8,14 +8,34 @@ import org.jetbrains.annotations.NotNull; import java.util.List; +/** + * Abstract service class for performing common operations on entities of type T, + * where T extends the GenericEntity class. This class is designed to be extended by other service classes, + * providing common functionality such as add, validate, get, delete, and update operations. + * + * @param The type of entity this service will work with. Must extend GenericEntity. + */ public abstract class GenericService { protected GenericRepository repository; + /** + * Sets the repository to be used by this service. + * + * @param repository The repository to be used for database operations. + */ public void setRepository(GenericRepository repository) { this.repository = repository; } + /** + * Adds an entity to the repository. + * The entity is validated before it is persisted. + * + * @param entity The entity to add. Must not be null. + * @return The added entity. + * @throws NonValidEntityException If the entity is not valid. + */ public T addOne(@NotNull T entity) { validateOne(entity); repository.persist(entity); @@ -23,7 +43,11 @@ public abstract class GenericService { } /** - * Override me and start with `super.validateOne(entity);` + * Validates an entity. Throws NonValidEntityException if the entity is null. + * This method is designed to be overridden by subclasses to provide additional validation logic. + * + * @param entity The entity to validate. + * @throws NonValidEntityException If the entity is not valid. */ public void validateOne(T entity) throws NonValidEntityException { if (entity == null) { @@ -31,15 +55,31 @@ public abstract class GenericService { } } + /** + * Retrieves an entity by its ID from the repository. + * + * @param id The ID of the entity to retrieve. + * @return The entity if found, or null if no entity with the given ID was found. + */ @Nullable public T getOneById(String id) { return repository.findById(id); } + /** + * Retrieves all entities from the repository. + * + * @return A list of all entities in the repository. + */ public List getAll() { return repository.listAll(); } + /** + * Deletes an entity by its ID from the repository. + * + * @param id The ID of the entity to delete. + */ public void deleteOneById(String id) { T entity = repository.findById(id); if (entity != null) { @@ -48,7 +88,12 @@ public abstract class GenericService { } /** - * Override me + * Updates an entity in the repository. + * This method is designed to be overridden by subclasses to provide specific update logic. + * + * @param entity The entity to update. Must not be null. + * @return The updated entity, or null if the update was not successful. + * @throws NonValidEntityException If the entity is not valid. */ @Nullable public T updateOne(@NotNull T entity) { @@ -56,6 +101,12 @@ public abstract class GenericService { return entity; } + /** + * Validates and updates a list of entities in the repository. + * If the list of entities is not empty, each entity is validated before the list is updated in the repository. + * + * @param entities The list of entities to update. + */ public void updateAll(List entities) { if (!entities.isEmpty()) { for (T entity : entities) {