Package br.ufsc.labsec.web

Class ReqItem<T>

java.lang.Object
br.ufsc.labsec.web.ReqItem<T>
Type Parameters:
T - tipo do valor do parâmetro
public final class ReqItem<T>
extends Object

Classe que representa um parâmetro ou parte presente na requisição. Permite a definição de condições para que o parâmetro seja obrigatório, transformações e validações do valor.

Como funciona:

A classe ReqItem é utilizada para representar um parâmetro ou parte presente na requisição. Todas as validações e transformações do valor do parâmetro são feitas através de métodos encadeados executados apenas na chamada do método getValue() ou getValueOrElse(Object).
Foi implementada uma nova interface chamada ReqItem.ApiFunction que representa uma Function que lança uma ApiMisusageException. Assim, o fluxo dos métodos é interrompido no primeiro erro de validação, que contém a mensagem de erro e o código de status HTTP para exposição na API.

Exemplo de uso:

É recomendada a utilização por meio da classe RequestParameterProcessor, com os métodos RequestParameterProcessor.parameter(String) e RequestParameterProcessor.part(String). 

         
         String name = parameter("name").required().map(String::toUpperCase).getValue();
         
         

         Neste exemplo, o parâmetro "name" é obrigatório e seu valor é transformado para maiúsculas.
         

         

         
         List<Part> files = part("file").required().getValue();
         
         

         Neste exemplo, a parte "file" é obrigatória.
         

         

         
         JSONObject name = parameter("x_path_internally_detached")
                                 .requiredIf(this.format == INTERNALLY_DETACHED)
                                 .map(JSONObject::new)
                                 .getValue();
          
          

          Neste exemplo, o parâmetro "x_path_internally_detached" é obrigatório se a variável "format" for igual a "INTERNALLY_DETACHED".
          Se o parâmetro fo opcional e não estiver presente na requisição, o valor retornado será null.
          

          

          
          String name = parameter("name").availableValues("A", "B", "C").getValueOrElse("A");
          
          

          Neste exemplo, o parâmetro "name" só será válido se seu valor for "A", "B" ou "C".
          Se ele não estiver presente na requisição, o valor retornado será "A".

  • Method Details

    • required

      public ReqItem<T> required()
      Define o parâmetro como obrigatório
      Returns:
      este objeto

    • requiredIf

      public ReqItem<T> requiredIf​(Supplier<Boolean> condition)
      Define o parâmetro como obrigatório se a condição for atendida
      TODO: verificar a necessidade de utilizar Supplier ao invés de boolean. Optou-se por essa abordagem por possibilitar o envio de métodos mais complexos que apenas são executados quando necessário.
      Parameters:
      condition - condição para que o parâmetro seja obrigatório
      Returns:
      este objeto

    • requiredIf

      public ReqItem<T> requiredIf​(boolean condition)
      Define o parâmetro como obrigatório se a condição for atendida
      Parameters:
      condition - condição para que o parâmetro seja obrigatório
      Returns:
      este objeto

    • availableValues

      public ReqItem<T> availableValues​(Collection<T> availableValues)
      Define os valores disponíveis para o parâmetro
      Parameters:
      availableValues - valores disponíveis
      Returns:
      este objeto

    • availableValues

      @SafeVarargs public final ReqItem<T> availableValues​(T... availableValues)
      Define os valores disponíveis para o parâmetro. Não é reaproveitável o uso de availableValues(Collection) por questões ambiguidade de tipos. List.of(T... availableValues) pode retornar List < T > ou List < T[] >
      Parameters:
      availableValues - valores disponíveis
      Returns:
      este objeto

    • match

      public ReqItem<T> match​(Predicate<T> predicate)
      Define uma validação para o valor do parâmetro
      Parameters:
      predicate - predicado que indica se o valor é válido
      Returns:
      este objeto

    • match

      public ReqItem<T> match​(Predicate<T> predicate, String errorMessage, int httpStatus)

    • map

      public <K> ReqItem<K> map​(ReqItem.ApiFunction<T,​K> transformFunction)
      Transforma o valor do parâmetro
      Type Parameters:
      K - tipo do novo valor
      Parameters:
      transformFunction - função que transforma o valor
      Returns:
      um novo ReqItem com o valor transformado

    • getValue

      public T getValue() throws ApiMisusageException
      Retorna o valor do parâmetro
      Returns:
      valor do parâmetro ou null se o parâmetro não estiver presente na requisição e não for obrigatório
      Throws:
      ApiMisusageException - se o valor do parâmetro for inválido ou se o parâmetro for obrigatório e não estiver presente na requisição

    • getValueOrElse

      public T getValueOrElse​(T defaultValue) throws ApiMisusageException
      Retorna o valor do parâmetro ou um valor padrão se o parâmetro não estiver presente na requisição
      Parameters:
      defaultValue - valor padrão
      Returns:
      valor do parâmetro ou valor padrão
      Throws:
      ApiMisusageException - se o valor do parâmetro for inválido