Merge pull request #12 from diegosneves/feat/i11

feat/i11 [CORE] - Desenvolvimento de Interfaces para Repositórios e Serviços voltados à Criação de Entidades

src/main/java/diegosneves/github/conectardoacoes/adapters/rest/config/web/CorsConfig.java

@@ -40,6 +40,7 @@
  * </pre>
  *
  * @author diegosneves
+ * @since 1.0.0
  */
 @Configuration
 public class CorsConfig {

src/main/java/diegosneves/github/conectardoacoes/adapters/rest/config/web/OpenApiConfig.java

@@ -18,6 +18,7 @@
  * <p>
  *
  * @author diegosneves
+ * @since 1.0.0
  */
 @Configuration
 public class OpenApiConfig {

src/main/java/diegosneves/github/conectardoacoes/adapters/rest/config/web/WebSecurityConfig.java

@@ -11,6 +11,7 @@
  * A classe {@link WebSecurityConfig} tem a responsabilidade de definir as configurações de segurança web desta aplicação.
  *
  * @author diegosneves
+ * @since 1.0.0
  */
 @Configuration
 @EnableWebSecurity

src/main/java/diegosneves/github/conectardoacoes/core/domain/shelter/entity/Shelter.java

@@ -6,18 +6,17 @@
 import diegosneves.github.conectardoacoes.core.exception.ShelterCreationFailureException;
 import diegosneves.github.conectardoacoes.core.exception.UuidUtilsException;
 import diegosneves.github.conectardoacoes.core.utils.UuidUtils;
+import diegosneves.github.conectardoacoes.core.utils.ValidationUtils;
 
 import java.util.ArrayList;
 import java.util.List;
 
-import static java.util.Objects.isNull;
-
 /**
  * Implementação da interface {@link ShelterContract}, que representa um abrigo na aplicação.
  * Uma instância desta classe representa um abrigo com uma identificação, um nome de referência, um endereço, um usuário responsável, e uma lista de doações.
  *
  * @author diegoneves
- * @version 1.0.0
+ * @since 1.0.0
  * @see ShelterContract
  */
 public class Shelter implements ShelterContract {
@@ -75,31 +74,11 @@ private void validateData() throws ShelterCreationFailureException {
         } catch (UuidUtilsException e) {
             throw new ShelterCreationFailureException(ID_VALIDATION_FAILURE, e);
         }
-        this.checkNotNullAndNotEmptyOrThrowException(this.shelterName, SHELTER_NAME_REQUIRED_ERROR);
-        this.checkNotNullAndNotEmptyOrThrowException(this.address, ADDRESS_REQUIRED_ERROR);
-        this.checkNotNullAndNotEmptyOrThrowException(this.responsibleUser, RESPONSIBLE_REQUIRED_ERROR);
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(this.shelterName, SHELTER_NAME_REQUIRED_ERROR, ShelterCreationFailureException.class);
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(this.address, ADDRESS_REQUIRED_ERROR, ShelterCreationFailureException.class);
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(this.responsibleUser, RESPONSIBLE_REQUIRED_ERROR, ShelterCreationFailureException.class);
     }
 
-    /**
-     * Este é um método genérico usado para verificar se o objeto fornecido é nulo ou, se é uma instância de String, se é vazio.
-     * Em ambos os casos, ele lançará uma exceção {@link ShelterCreationFailureException}.
-     * <p>
-     * Este método é particularmente útil para validar os detalhes do abrigo durante a criação de um novo abrigo.
-     * Assegura que os valores de todos os campos necessários estão presentes e não são nulos ou vazios.
-     *
-     * @param <T>          O tipo de objeto a ser verificado.
-     * @param object       O objeto a ser verificado.
-     * @param errorMessage A mensagem de erro a ser anexada à exceção em caso de falha de validação.
-     * @throws ShelterCreationFailureException Se o objeto fornecido for nulo ou, se for uma instância de String, se for vazio.
-     */
-    private <T> void checkNotNullAndNotEmptyOrThrowException(T object, String errorMessage) throws ShelterCreationFailureException {
-        if (isNull(object)) {
-            throw new ShelterCreationFailureException(errorMessage);
-        }
-        if (object instanceof String && ((String) object).trim().isEmpty()) {
-            throw new ShelterCreationFailureException(errorMessage);
-        }
-    }
 
     @Override
     public String getId() {
@@ -121,21 +100,26 @@ public UserContract getUser() {
         return this.responsibleUser;
     }
 
+    @Override
+    public List<Donation> getDonations() {
+        return this.donations;
+    }
+
     @Override
     public void changeShelterName(String shelterName) throws ShelterCreationFailureException {
-        this.checkNotNullAndNotEmptyOrThrowException(shelterName, SHELTER_NAME_REQUIRED_ERROR);
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(shelterName, SHELTER_NAME_REQUIRED_ERROR, ShelterCreationFailureException.class);
         this.shelterName = shelterName;
     }
 
     @Override
     public void changeAddress(Address address) throws ShelterCreationFailureException {
-        this.checkNotNullAndNotEmptyOrThrowException(address, ADDRESS_REQUIRED_ERROR);
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(address, ADDRESS_REQUIRED_ERROR, ShelterCreationFailureException.class);
         this.address = address;
     }
 
     @Override
     public void addDonation(Donation donation) throws ShelterCreationFailureException {
-        this.checkNotNullAndNotEmptyOrThrowException(donation, DONATION_REQUIRED_ERROR);
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(donation, DONATION_REQUIRED_ERROR, ShelterCreationFailureException.class);
         this.donations.add(donation);
     }
 }

src/main/java/diegosneves/github/conectardoacoes/core/domain/shelter/entity/ShelterContract.java

@@ -5,14 +5,16 @@
 import diegosneves.github.conectardoacoes.core.domain.user.entity.UserContract;
 import diegosneves.github.conectardoacoes.core.exception.ShelterCreationFailureException;
 
+import java.util.List;
+
 /**
  * Interface {@link ShelterContract} define os métodos que representam os principais comportamentos e a divulgação de informações de uma entidade {@link Shelter}.
  * <p>
  * Essa interface é fundamental para definir os contratos para identificação do Abrigo, gerenciamento e atualização de endereço e nome do abrigo,
  * além da adição de doações e recuperação de um usuário responsável pelo abrigo.
  *
  * @author diegoneves
- * @version 1.0.0
+ * @since 1.0.0
  */
 public interface ShelterContract {
 
@@ -37,6 +39,21 @@ public interface ShelterContract {
      */
     Address getAddress();
 
+    /**
+     * Retorna uma lista de todas as doações associadas ao Abrigo.
+     * <p>
+     * Cada item na lista é um objeto {@link Donation}, que representa uma
+     * doação feita ao Abrigo. A doação contém informações sobre a descrição
+     * e a quantidade da doação.
+     * <p>
+     * Este método não recebe nenhum parâmetro.
+     *
+     * @return Uma lista de objetos {@link Donation} que representam as
+     * doações feitas ao Abrigo. Se não houver doações, este método retornará
+     * uma lista vazia.
+     */
+    List<Donation> getDonations();
+
     /**
      * Este método é usado para alterar o endereço do abrigo.
      * <p>

src/main/java/diegosneves/github/conectardoacoes/core/domain/shelter/entity/value/Address.java

@@ -14,7 +14,7 @@
  * Este classe é utilizada na criação de entidades tais como {@link Shelter}, que precisam de uma representação de endereço.
  *
  * @author diegoneves
- * @version 1.0.0
+ * @since 1.0.0
  */
 @Getter
 public class Address {

src/main/java/diegosneves/github/conectardoacoes/core/domain/shelter/entity/value/Donation.java

@@ -8,7 +8,7 @@
  * Uma doação é caracterizada pela sua descrição e quantidade.
  *
  * @author diegoneves
- * @version 1.0.0
+ * @since 1.0.0
  */
 @Getter
 public class Donation {

src/main/java/diegosneves/github/conectardoacoes/core/domain/shelter/factory/ShelterFactory.java

@@ -3,12 +3,39 @@
 import diegosneves.github.conectardoacoes.core.domain.shelter.entity.Shelter;
 import diegosneves.github.conectardoacoes.core.domain.shelter.entity.value.Address;
 import diegosneves.github.conectardoacoes.core.domain.user.entity.UserContract;
+import diegosneves.github.conectardoacoes.core.exception.ShelterCreationFailureException;
 import diegosneves.github.conectardoacoes.core.utils.UuidUtils;
 
+/**
+ * Classe {@link ShelterFactory} responsável por fornecer métodos para criar instâncias da classe {@link Shelter}.
+ * <p>
+ * Esta classe é um exemplo de aplicação do padrão de projeto Factory, que fornece um método estático para a criação de instâncias de {@link Shelter}.
+ * Neste caso, a criação do objeto Shelter é abstraída para a esta classe.
+ * <p>
+ * Esta classe destaca a declaração de um método público estático create, responsável pela criação de uma instance de {@link Shelter}.
+ *
+ * @author diegoneves
+ * @since 1.0.0
+ * @see Shelter
+ */
 public class ShelterFactory {
 
     private ShelterFactory() {}
 
+    /**
+     * Construtor estático para a classe {@link Shelter}.
+     * <p>
+     * Este método é responsável por criar uma nova instancia de {@link Shelter} com um UUID gerado dinamicamente, juntamente com os detalhes fornecidos.
+     * <p>
+     * Este método utiliza o método {@link UuidUtils#generateUuid} para gerar um UUID único para o novo objeto {@link Shelter}.
+     *
+     * @param shelterName A string que representa o nome do abrigo.
+     * @param address A instância de {@link Address} que representa o endereço do abrigo.
+     * @param responsibleUser A instância de {@link UserContract} quem representa o usuário responsável pelo abrigo.
+     * @return {@link Shelter} A nova instância de Shelter com os detalhes fornecidos.
+     * @throws ShelterCreationFailureException se qualquer informação do Abrigo fornecida for inválida.
+     *
+     */
     public static Shelter create(String shelterName, Address address, UserContract responsibleUser) {
         return new Shelter(UuidUtils.generateUuid(), shelterName, address, responsibleUser);
     }

src/main/java/diegosneves/github/conectardoacoes/core/domain/shelter/shared/repository/ShelterRepository.java

@@ -0,0 +1,29 @@
+package diegosneves.github.conectardoacoes.core.domain.shelter.shared.repository;
+
+import diegosneves.github.conectardoacoes.core.domain.shelter.entity.Shelter;
+import diegosneves.github.conectardoacoes.core.domain.shelter.entity.ShelterContract;
+import diegosneves.github.conectardoacoes.core.repository.RepositoryContract;
+
+/**
+ * A interface {@link ShelterRepository} herda da interface {@link RepositoryContract}.
+ * Ela define o contrato para um repositório que persiste e recupera as entidades {@link ShelterContract}.
+ * <p>
+ * Tem as seguintes operações básicas:
+ *  - Encontrar uma entidade {@link Shelter} pelo seu identificador único
+ *  - Encontrar todas as instâncias da entidade {@link Shelter}
+ *  - Salvar uma instância da entidade {@link Shelter}
+ *  - Deletar uma entidade {@link Shelter} através seu identificador único
+ *
+ * <p>
+ * O uso desta interface é específico para operações relacionados com objeto {@link ShelterContract}
+ * e as suas implementações devem ser consideradas para trabalhar com dados da entidade Shelter.
+ * <p>
+ *
+ * @author diegoneves
+ * @since 1.0.0
+ * @see RepositoryContract
+ * @see Shelter
+ */
+public interface ShelterRepository extends RepositoryContract<ShelterContract> {
+
+}

src/main/java/diegosneves/github/conectardoacoes/core/domain/user/entity/User.java

@@ -4,6 +4,7 @@
 import diegosneves.github.conectardoacoes.core.exception.UserCreationFailureException;
 import diegosneves.github.conectardoacoes.core.exception.UuidUtilsException;
 import diegosneves.github.conectardoacoes.core.utils.UuidUtils;
+import diegosneves.github.conectardoacoes.core.utils.ValidationUtils;
 
 /**
  * Representa um usuário dentro do sistema.
@@ -30,7 +31,7 @@
  * </p>
  *
  * @author diegoneves
- * @version 1.0
+ * @since 1.0.0
  */
 public class User implements UserContract {
 
@@ -75,25 +76,18 @@ public User(String id, String userName, String email, UserProfile userProfile, S
      *                                      faltando, em branco ou é inválido
      */
     private void validateData() throws UserCreationFailureException {
-        if (this.userProfile == null) {
-            throw new UserCreationFailureException(PROFILE_NOT_PROVIDED);
-        }
-        if (this.userName == null || this.userName.isBlank()) {
-            throw new UserCreationFailureException(String.format(USERNAME_REQUIRED, this.userProfile));
-        }
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(this.userProfile, PROFILE_NOT_PROVIDED, UserCreationFailureException.class);
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(this.userName, String.format(USERNAME_REQUIRED, this.userProfile), UserCreationFailureException.class);
         try {
             UuidUtils.isValidUUID(this.id);
         } catch (UuidUtilsException e) {
             throw new UserCreationFailureException(USER_ID_REQUIRED, e);
         }
-        if (this.email == null || this.email.isBlank()) {
-            throw new UserCreationFailureException(EMAIL_NOT_PROVIDED);
-        }
-        if (this.userPassword == null || this.userPassword.isBlank()) {
-            throw new UserCreationFailureException(PASSWORD_NOT_PROVIDED);
-        }
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(this.email, EMAIL_NOT_PROVIDED, UserCreationFailureException.class);
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(this.userPassword, PASSWORD_NOT_PROVIDED, UserCreationFailureException.class);
     }
 
+
     @Override
     public String getId() {
         return this.id;
@@ -121,17 +115,13 @@ public String getEmail() {
 
     @Override
     public void changeUserPassword(String password) throws UserCreationFailureException {
-        if (password == null || password.isBlank()) {
-            throw new UserCreationFailureException(PASSWORD_NOT_PROVIDED);
-        }
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(password, PASSWORD_NOT_PROVIDED, UserCreationFailureException.class);
         this.userPassword = password;
     }
 
     @Override
     public void changeUserName(String updatedUsername) {
-        if (updatedUsername == null || updatedUsername.isBlank()) {
-            throw new UserCreationFailureException(String.format(USERNAME_REQUIRED, this.userProfile));
-        }
+        ValidationUtils.checkNotNullAndNotEmptyOrThrowException(updatedUsername, String.format(USERNAME_REQUIRED, this.userProfile), UserCreationFailureException.class);
         this.userName = updatedUsername;
     }
 }

src/main/java/diegosneves/github/conectardoacoes/core/domain/user/entity/UserContract.java

@@ -14,7 +14,7 @@
  * {@link UserCreationFailureException}.
  *
  * @author diegoneves
- * @version 1.0
+ * @since 1.0.0
  * @see UserCreationFailureException
  * @see RuntimeException
  */

src/main/java/diegosneves/github/conectardoacoes/core/domain/user/entity/value/UserProfile.java

@@ -5,7 +5,7 @@
  * Os perfis disponíveis são {@code 'Doador'} e {@code 'Beneficiário'}.
  *
  * @author diegoneves
- * @version 1.0.0
+ * @since 1.0.0
  */
 public enum UserProfile {
 

src/main/java/diegosneves/github/conectardoacoes/core/domain/user/factory/UserFactory.java

@@ -2,14 +2,45 @@
 
 import diegosneves.github.conectardoacoes.core.domain.user.entity.User;
 import diegosneves.github.conectardoacoes.core.domain.user.entity.value.UserProfile;
+import diegosneves.github.conectardoacoes.core.exception.UserCreationFailureException;
 import diegosneves.github.conectardoacoes.core.utils.UuidUtils;
 
+/**
+ * Classe de utilidade para a criação de usuário.
+ * <p>
+ * Oferece um método estático para criar um usuário com todas as informações necessárias
+ * como nome de usuário, e-mail, perfil de usuário e senha.
+ * Além disso, gera um identificador UUID para o novo usuário.
+ * </p>
+ * <p>
+ * Esta classe foi projetada para ser usada em todo o código que precisa criar um novo usuário,
+ * permitindo uma abordagem consistente para a criação de usuário.
+ * </p>
+ * <p>
+ * Esta classe não pode ser instanciada.
+ * </p>
+ *
+ * @author diegoneves
+ * @since 1.0.0
+ * @see User
+ */
 public class UserFactory {
 
     private UserFactory() {
 
     }
 
+    /**
+     * Cria um novo usuário com todas as informações necessárias e um identificador UUID gerado.
+     * <p>
+     * Este método utiliza o método {@link UuidUtils#generateUuid} para gerar um UUID único para o novo objeto {@link User}.
+     * @param username    O nome de usuário desejado para o novo usuário. Não deve ser nulo ou vazio.
+     * @param email       O e-mail do novo usuário. Não deve ser nulo ou vazio.
+     * @param userProfile O perfil do usuário {@link UserProfile} para o novo usuário. Não deve ser nulo.
+     * @param password    A senha para o novo usuário. Não deve ser nula ou vazia.
+     * @return O usuário criado com todas as informações fornecidas e um identificador UUID.
+     * @throws UserCreationFailureException se qualquer informação de usuário fornecida for inválida.
+     */
     public static User create(String username, String email, UserProfile userProfile, String password) {
         return new User(UuidUtils.generateUuid(), username, email, userProfile, password);
     }