Package org.praxisplatform.uischema.service.base.annotation

Annotation Interface DefaultSortColumn

@Target(FIELD) @Retention(RUNTIME) public @interface DefaultSortColumn

📊 Anotação para Ordenação Padrão Automática

Define automaticamente a ordenação padrão para consultas JPA quando nenhuma ordenação explícita é fornecida via Pageable ou parâmetros de requisição.

🎯 Objetivo

Elimina a necessidade de especificar ordenação em cada consulta, fornecendo uma ordenação sensata e consistente por padrão para listagens e filtros.

⚙️ Como Funciona

  1. Detecção: BaseCrudService.getDefaultSort() escaneia campos com esta anotação
  2. Priorização: Campos são ordenados por prioridade (menor número = maior prioridade)
  3. Aplicação: Ordenação aplicada automaticamente quando Pageable.getSort().isSorted() == false

📋 Parâmetros

  • ascending: true = ASC, false = DESC (padrão: true)
  • priority: Prioridade da ordenação - menor valor = maior prioridade (padrão: 0)

🔄 Exemplos de Uso

Ordenação Simples:


 @Entity
 public class Cliente {
     @Id
     private Long id;
     
     @DefaultSortColumn  // Ordenação alfabética por padrão
     private String nome;
 }
 
 // Resultado: ORDER BY nome ASC (quando nenhum sort é especificado)

Ordenação Múltipla com Prioridades:


 @Entity
 public class Funcionario {
     @DefaultSortColumn(priority = 1, ascending = true)
     private String departamento;
     
     @DefaultSortColumn(priority = 2, ascending = true) 
     private String nomeCompleto;
 }
 
 // Resultado: ORDER BY departamento ASC, nomeCompleto ASC

Ordenação por Data (Mais Recente Primeiro):


 @Entity
 public class Noticia {
     @DefaultSortColumn(ascending = false)
     private LocalDateTime dataPublicacao;
 }
 
 // Resultado: ORDER BY dataPublicacao DESC (notícias mais recentes primeiro)

🔗 Integração com APIs

Sem parâmetro sort (usa @DefaultSortColumn):

 GET /api/funcionarios/all
 → Aplica ordenação: ORDER BY departamento ASC, nomeCompleto ASC

Com parâmetro sort (ignora @DefaultSortColumn):

 GET /api/funcionarios/all?sort=salario,desc
 → Aplica ordenação: ORDER BY salario DESC

⚡ Aplicação Automática

A ordenação é aplicada automaticamente nos seguintes métodos:

  • GET /{resource}/all - Lista completa sem filtros
  • POST /{resource}/filter - Lista filtrada com paginação
  • Qualquer método que use BaseCrudService.findAll()

🎯 Benefícios

  • UX Consistente: Usuários sempre veem dados organizados de forma lógica
  • Performance: Evita scans desnecessários com ordenação inteligente
  • Zero Configuração: Funciona automaticamente sem código adicional
  • Flexível: Pode ser sobrescrita via parâmetros de requisição

⚠️ Considerações

  • Usar apenas em campos indexados para melhor performance
  • Prioridades devem ser únicas para ordem determinística
  • Evitar ordenação por campos de relacionamentos profundos (N+1 queries)
Since:
1.0.0
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    ascending
     
    int
    priority
     

  • Element Details

    • ascending

      boolean ascending
      Default:
      true

    • priority

      int priority
      Default:
      0