Demoiselle Framework v4 — Modernização Jakarta EE 10

// Antes (classe mutável com boilerplate)
SortModel sort = new SortModel(CrudSort.ASC, "name");
sort.getType();  // getter tradicional
sort.getField();

// Depois (record imutável)
SortModel sort = new SortModel(CrudSort.ASC, "name");
sort.type();   // accessor do record
sort.field();

// NullPointerException — tipo nulo
new SortModel(null, "name");

// NullPointerException — campo nulo
new SortModel(CrudSort.ASC, null);

// IllegalArgumentException — campo vazio ou em branco
new SortModel(CrudSort.ASC, "   ");

// Criação de mensagem de erro
var msg = new DemoiselleRestExceptionMessage(
    "AUTH_FAILED",
    "Token expirado",
    "https://docs.example.com/errors/auth-failed"
);

// Acessores do record
msg.error();            // "AUTH_FAILED"
msg.errorDescription(); // "Token expirado"
msg.errorLink();        // pode ser null

ResultSet rs = new ResultSet();

// setContent(null) resulta em lista vazia, não NullPointerException
rs.setContent(null);
rs.getContent(); // → List.of() (lista vazia imutável)

// Cópia defensiva — modificações na lista original não afetam o ResultSet
List<String> original = new ArrayList<>(List.of("a", "b", "c"));
rs.setContent(original);
original.add("d");           // modifica a lista original
rs.getContent().size();       // → 3 (inalterado)

// Metadados de campo de configuração
record ConfigFieldMeta(
    String key,          // chave no arquivo de configuração
    Field field,         // campo refletido
    boolean ignored,     // @ConfigurationIgnore presente?
    boolean suppressLog  // @ConfigurationSuppressLogger presente?
) {}

// Metadados da fonte de configuração
record ConfigSourceMeta(
    ConfigurationType type,  // PROPERTIES, XML ou SYSTEM
    String resource,         // nome do arquivo
    String prefix            // prefixo das chaves
) {}

public sealed interface FilterOp {
    String key();

    record Equals(String key, String value)          implements FilterOp {}
    record Like(String key, String pattern)           implements FilterOp {}
    record IsNull(String key)                         implements FilterOp {}
    record IsTrue(String key)                         implements FilterOp {}
    record IsFalse(String key)                        implements FilterOp {}
    record EnumFilter(String key, String value, int ordinal) implements FilterOp {}
    record UUIDFilter(String key, UUID value)         implements FilterOp {}
}

protected Predicate buildPredicate(FilterOp op, From<?, ?> from,
        CriteriaBuilder cb, CriteriaQuery<?> cq) {
    return switch (op) {
        case FilterOp.IsNull(var key)              -> cb.isNull(from.get(key));
        case FilterOp.Like(var key, var pattern)    -> buildLikePredicate(cb, cq, from, key, pattern);
        case FilterOp.IsTrue(var key)               -> cb.isTrue(from.get(key));
        case FilterOp.IsFalse(var key)              -> cb.isFalse(from.get(key));
        case FilterOp.EnumFilter(var key, _, var o) -> cb.equal(from.get(key), o);
        case FilterOp.UUIDFilter(var key, var uuid) -> cb.equal(from.get(key), uuid);
        case FilterOp.Equals(var key, var val)      -> cb.equal(from.get(key), val);
    };
    // Sem cláusula default — o compilador garante exaustividade!
}

public class MessageBundleBuildCompatibleExtension
        implements BuildCompatibleExtension {

    @Discovery
    public void discovery(ScannedClasses scan) {
        // CDI 4.0 Lite descobre automaticamente
    }

    @Enhancement(types = Object.class,
                 withAnnotations = MessageBundle.class)
    public void collectMessageBundles(ClassInfo classInfo) {
        // Coleta interfaces @MessageBundle
    }

    @Synthesis
    public void registerBeans(SyntheticComponents syn) {
        // Registra beans sintéticos com proxy dinâmico
    }
}

@MessageBundle
public interface AppMessages {

    @MessageTemplate("{welcome}")
    String welcome();

    @MessageTemplate("{greeting}")
    String greeting(String name);
}

@Inject
@MessageBundle
AppMessages messages;

messages.welcome();           // "Bem-vindo ao sistema"
messages.greeting("João");    // "Olá, João!"

public class ConfigurationBuildCompatibleExtension
        implements BuildCompatibleExtension {

    @Discovery
    public void discovery(ScannedClasses scan) { }

    @Enhancement(types = ConfigurationValueExtractor.class)
    public void collectExtractors(ClassInfo classInfo) {
        // Coleta implementações de ConfigurationValueExtractor
    }

    @Synthesis
    public void registerExtractorRegistry(SyntheticComponents syn) {
        // Registra bean sintético ApplicationScoped com o cache de extractors
    }
}

@Inject
DemoiselleUser user;

// getRoles() retorna cópia independente via List.copyOf()
List<String> roles = user.getRoles();
// Modificações internas posteriores NÃO afetam esta cópia

// getPermissions() retorna deep copy
Map<String, List<String>> perms = user.getPermissions();
// Cada lista de valores também é copiada via List.copyOf()

// getParams() retorna cópia independente via Map.copyOf()
Map<String, String> params = user.getParams();

// ANTES: Collections.unmodifiableList() — view mutável
// Se a lista interna mudasse, a view refletia a mudança
List<String> roles = user.getRoles(); // view
user.addRole("admin");
roles.contains("admin"); // true (!) — a view refletia a mudança

// DEPOIS: List.copyOf() — cópia defensiva
List<String> roles = user.getRoles(); // cópia
user.addRole("admin");
roles.contains("admin"); // false — a cópia é independente

user.addRole(null); // → NullPointerException

private final ReadWriteLock rwLock = new ReentrantReadWriteLock();

public void load(final Object object, Class<?> baseClass) {
    // Leitura rápida — múltiplas threads leem simultaneamente
    rwLock.readLock().lock();
    try {
        if (isAlreadyLoaded(object)) return;
    } finally {
        rwLock.readLock().unlock();
    }

    // Escrita exclusiva — apenas uma thread por vez
    rwLock.writeLock().lock();
    try {
        // Double-checked locking
        if (!isAlreadyLoaded(object)) {
            processConfiguration(object, baseClass);
        }
    } finally {
        rwLock.writeLock().unlock();
    }
}

@ApplicationScoped
public class DynamicManagerCache implements Serializable {

    // ANTES: static Map (compartilhado globalmente, não GC-friendly)
    // DEPOIS: campos de instância (ciclo de vida gerenciado pelo CDI)
    private final Map<String, ConcurrentHashMap<String, Object>> scriptCache =
        new ConcurrentHashMap<>();
    private final Map<String, Object> engineList =
        new ConcurrentHashMap<>();

    public Map<String, ConcurrentHashMap<String, Object>> getScriptCache() {
        return scriptCache;
    }

    public Map<String, Object> getEngineList() {
        return engineList;
    }
}

// No DynamicManager — injeção via CDI
@Inject
private DynamicManagerCache cache;

// Uso via getters em vez de acesso estático
cache.getEngineList().put(engineName, engine);
cache.getScriptCache().put(engineName, new ConcurrentHashMap<>());

@Override
public T mergeHalf(I id, T entity) {
    CriteriaBuilder cb = getEntityManager().getCriteriaBuilder();
    CriteriaUpdate<T> update = cb.createCriteriaUpdate(entityClass);
    Root<T> root = update.from(entityClass);

    boolean hasUpdates = false;

    for (final Field field : getAllFields(entityClass)) {
        // @ManyToOne sempre incluído
        if (!field.isAnnotationPresent(ManyToOne.class)) {
            final Column column = field.getAnnotation(Column.class);
            // Sem @Column ou @Column(updatable=false) → pular
            if (column == null || !column.updatable()) {
                continue;
            }
        }
        field.setAccessible(true);
        final Object value = field.get(entity);
        if (value != null) {
            update.set(root.get(field.getName()), value);
            hasUpdates = true;
        }
    }

    if (hasUpdates) {
        String idName = CrudUtilHelper.getMethodAnnotatedWithID(entityClass);
        update.where(cb.equal(root.get(idName), id));
        getEntityManager().createQuery(update).executeUpdate();
    }

    return entity;
}

public class PedidoDAO extends AbstractDAO<Pedido, Long> {

    @Override
    protected EntityGraph<Pedido> getEntityGraph() {
        EntityGraph<Pedido> graph = getEntityManager()
            .createEntityGraph(Pedido.class);
        graph.addAttributeNodes("itens", "cliente");
        return graph;
    }
}

TypedQuery<T> query = getEntityManager().createQuery(criteriaQuery);

EntityGraph<T> graph = getEntityGraph();
if (graph != null) {
    query.setHint("jakarta.persistence.fetchgraph", graph);
}

@Entity
@SoftDeletable(field = "deletedAt")
public class Produto {

    @Id @GeneratedValue
    private Long id;

    private String nome;

    private LocalDateTime deletedAt; // campo de soft delete

    // getters e setters
}

// LocalDateTime (padrão)
@SoftDeletable(field = "deletedAt")

// Boolean
@SoftDeletable(field = "deleted", type = Boolean.class)

// Instant
@SoftDeletable(field = "deletedInstant", type = Instant.class)

// remove() executa UPDATE em vez de DELETE
dao.remove(42L);
// SQL gerado: UPDATE produto SET deleted_at = '2026-04-01T10:30:00' WHERE id = 42

// find() exclui registros soft-deleted automaticamente
Result result = dao.find();
// SQL gerado: SELECT ... FROM produto WHERE deleted_at IS NULL

// find(id) retorna null para registros soft-deleted
Produto p = dao.find(42L); // → null (registro marcado como excluído)

// count() exclui registros soft-deleted
Long total = dao.count();
// SQL gerado: SELECT COUNT(*) FROM produto WHERE deleted_at IS NULL

// findIncludingDeleted() retorna TODOS os registros
Result todos = dao.findIncludingDeleted();
// SQL gerado: SELECT ... FROM produto (sem filtro de soft delete)

@SoftDeletable(field = "deleted", type = Boolean.class)
public class Tarefa {
    private Boolean deleted;
}

// remove() → UPDATE tarefa SET deleted = true WHERE id = ?
// find()   → SELECT ... WHERE (deleted = false OR deleted IS NULL)

// Campo inexistente → DemoiselleCrudException na inicialização do DAO
@SoftDeletable(field = "campoInexistente")
public class Invalida { }

// Tipo não suportado → DemoiselleCrudException
@SoftDeletable(field = "nome", type = String.class)
public class TipoInvalido { }

@Entity
@EntityListeners(AuditEntityListener.class)
public class Pedido {

    @Id @GeneratedValue
    private Long id;

    private String descricao;

    @CreatedAt
    private LocalDateTime criadoEm;

    @CreatedBy
    private String criadoPor;

    @UpdatedAt
    private LocalDateTime atualizadoEm;

    @UpdatedBy
    private String atualizadoPor;

    // getters e setters
}

// Ao persistir: preenche apenas @CreatedAt e @CreatedBy
entityManager.persist(pedido);
// pedido.criadoEm    → 2026-04-01T10:30:00
// pedido.criadoPor   → "admin"
// pedido.atualizadoEm → null
// pedido.atualizadoPor → null

// Ao atualizar: preenche apenas @UpdatedAt e @UpdatedBy
entityManager.merge(pedido);
// pedido.criadoEm    → (inalterado)
// pedido.criadoPor   → (inalterado)
// pedido.atualizadoEm → 2026-04-01T11:00:00
// pedido.atualizadoPor → "editor"

@FunctionalInterface
public interface Specification<T> {
    Predicate toPredicate(Root<T> root, CriteriaQuery<?> query, CriteriaBuilder cb);

    // Métodos default para composição
    default Specification<T> and(Specification<T> other) { ... }
    default Specification<T> or(Specification<T> other)  { ... }
    default Specification<T> not()                        { ... }
}

// Specification simples
Specification<Produto> precoMaior100 = (root, query, cb) ->
    cb.greaterThan(root.get("preco"), 100.0);

Specification<Produto> categoriaEletronicos = (root, query, cb) ->
    cb.equal(root.get("categoria"), "ELETRONICOS");

Specification<Produto> emEstoque = (root, query, cb) ->
    cb.greaterThan(root.get("estoque"), 0);

// AND: produtos eletrônicos com preço > 100
Specification<Produto> filtro = categoriaEletronicos.and(precoMaior100);

// OR: eletrônicos OU preço > 100
Specification<Produto> filtroOu = categoriaEletronicos.or(precoMaior100);

// NOT: produtos que NÃO são eletrônicos
Specification<Produto> naoEletronicos = categoriaEletronicos.not();

// Composição complexa: eletrônicos em estoque OU preço > 100
Specification<Produto> complexo = categoriaEletronicos.and(emEstoque)
                                                       .or(precoMaior100);

// find(spec) combina Specification com filtros do DemoiselleRequestContext
Result result = dao.find(precoMaior100.and(emEstoque));

// Paginação é aplicada automaticamente quando habilitada
// Retorna PageResult com metadados quando paginação está ativa

// find(null) equivale a find() padrão
Result result = dao.find(null); // mesmo que dao.find()

List<Produto> produtos = List.of(
    new Produto("Notebook", 3500.0),
    new Produto("Mouse", 89.90),
    new Produto("Teclado", 199.90)
);

// Persiste todos com flush/clear a cada N registros
List<Produto> persistidos = dao.persistAll(produtos);
// persistidos.size() == 3

try {
    dao.persistAll(entidades);
} catch (DemoiselleCrudException e) {
    // "Erro ao persistir entidade no índice 42"
    e.getMessage();
    e.getCause(); // PersistenceException original
}

List<Long> ids = List.of(1L, 2L, 3L, 4L, 5L);

// Remove todos (respeita @SoftDeletable quando presente)
int removidos = dao.removeAll(ids);
// removidos == 5

// Atualiza todos os produtos da categoria "ELETRONICOS" com desconto
Specification<Produto> eletronicos = (root, query, cb) ->
    cb.equal(root.get("categoria"), "ELETRONICOS");

Map<String, Object> updates = Map.of(
    "desconto", 0.15,
    "emPromocao", true
);

int atualizados = dao.updateAll(eletronicos, updates);
// SQL: UPDATE produto SET desconto = 0.15, em_promocao = true
//      WHERE categoria = 'ELETRONICOS'

public record PageResult<T>(
    List<T> content,       // conteúdo da página
    long totalElements,    // total de elementos em todas as páginas
    int totalPages,        // total de páginas
    int currentPage,       // página atual (0-indexed)
    int pageSize,          // tamanho da página
    boolean hasNext,       // existe próxima página?
    boolean hasPrevious    // existe página anterior?
) implements Result { }

// Com paginação habilitada → PageResult
Result result = dao.find();
if (result instanceof PageResult<?> page) {
    page.totalElements(); // 150
    page.totalPages();    // 15
    page.currentPage();   // 0
    page.pageSize();      // 10
    page.hasNext();       // true
    page.hasPrevious();   // false
    page.content();       // List<Produto> (10 itens)
}

// Sem paginação → ResultSet (comportamento anterior mantido)

// Criação manual com cálculos automáticos de metadados
PageResult<Produto> page = PageResult.of(
    produtos,        // conteúdo
    150L,            // totalElements
    20,              // offset
    10               // pageSize
);
// totalPages = 15, currentPage = 2, hasNext = true, hasPrevious = true

public sealed interface FilterOp {
    // Originais (7)
    record Equals(String key, String value)                    implements FilterOp {}
    record Like(String key, String pattern)                    implements FilterOp {}
    record IsNull(String key)                                  implements FilterOp {}
    record IsTrue(String key)                                  implements FilterOp {}
    record IsFalse(String key)                                 implements FilterOp {}
    record EnumFilter(String key, String value, int ordinal)   implements FilterOp {}
    record UUIDFilter(String key, UUID value)                  implements FilterOp {}

    // Novos operadores de comparação (6)
    record GreaterThan(String key, String value)               implements FilterOp {}
    record LessThan(String key, String value)                  implements FilterOp {}
    record GreaterThanOrEqual(String key, String value)        implements FilterOp {}
    record LessThanOrEqual(String key, String value)           implements FilterOp {}
    record Between(String key, String lower, String upper)     implements FilterOp {}
    record In(String key, List<String> values)                 implements FilterOp {}
}

public class ProdutoREST extends AbstractREST<Produto, Long> {

    @GET
    @Cacheable(ttl = 60) // cache por 60 segundos
    public Result find() {
        return super.find();
    }

    @GET
    @Path("/destaque")
    @Cacheable // TTL padrão: 300 segundos (5 minutos)
    public Result findDestaques() {
        // consulta customizada
    }
}

// persist() → EntityModifiedEvent(Produto.class, PERSIST, entity)
// mergeFull() / mergeHalf() → EntityModifiedEvent(Produto.class, MERGE, entity)
// remove() → EntityModifiedEvent(Produto.class, REMOVE, id)

// Ao persistir um Produto, TODAS as consultas cacheadas de Produto são invalidadas
// Consultas cacheadas de outras entidades (Pedido, Cliente) permanecem intactas

@Cacheable(entityClass = Produto.class, ttl = 60)
public List<Produto> consultarDestaques() {
    // ...
}

import org.demoiselle.jee.observability.annotation.Counted;

@ApplicationScoped
public class TokenService {

    @Counted("demoiselle.jwt.tokens.issued")
    public String issueToken(DemoiselleUser user) {
        // lógica de emissão de token
        return jwt;
    }

    @Counted // nome automático: "TokenService.validateToken"
    public DemoiselleUser validateToken(String jwt) {
        // lógica de validação
        return user;
    }
}

import org.demoiselle.jee.observability.annotation.Traced;

@ApplicationScoped
public class PedidoService {

    @Traced(module = "pedido", operation = "criar")
    public Pedido criarPedido(PedidoDTO dto) {
        // lógica de criação
        return pedido;
    }

    @Traced // module = "PedidoService", operation = "buscarPorId"
    public Pedido buscarPorId(Long id) {
        return pedido;
    }
}

// Interface
public interface MetricsAdapter {
    void increment(String counterName);
    long getCount(String counterName);
}

// Quando MicroProfile Metrics está no classpath:
//   → MicroProfileMetricsAdapter (delega para MetricRegistry)

// Quando MicroProfile Metrics NÃO está no classpath:
//   → NoopMetricsAdapter (increment() não faz nada, getCount() retorna 0)

public interface TracingAdapter {
    <T> T executeInSpan(String module, String operation, SpanCallable<T> callable) throws Exception;

    @FunctionalInterface
    interface SpanCallable<T> {
        T call() throws Exception;
    }
}

// Quando OpenTelemetry está no classpath:
//   → OpenTelemetryTracingAdapter (cria spans com atributos)

// Quando OpenTelemetry NÃO está no classpath:
//   → NoopTracingAdapter (executa callable diretamente)

import org.demoiselle.jee.openapi.OpenAPIContributor;
import org.eclipse.microprofile.openapi.OASFactory;
import org.eclipse.microprofile.openapi.models.OpenAPI;

@ApplicationScoped
public class MeuModuloOpenAPIContributor implements OpenAPIContributor {

    @Override
    public OpenAPI contribute() {
        OpenAPI partial = OASFactory.createOpenAPI();
        partial.paths(OASFactory.createPaths()
            .addPathItem("/api/meu-recurso", OASFactory.createPathItem()
                .GET(OASFactory.createOperation()
                    .summary("Lista recursos")
                    .operationId("listarRecursos"))));
        return partial;
    }
}

@EnabledIf("isSecurityJwtAvailable")
class ConfigSecurityRestIT {

    @Test
    void fullFlow_configLoadAndTokenIssueAndValidate() {
        // 1. Carregar configuração de segurança
        // 2. Emitir token JWT com claims
        // 3. Validar token em novo TokenManager
        // 4. Verificar que claims são preservados
    }

    @Test
    void requiredRole_acceptsValidTokenWithCorrectRole() {
        // Token com role "admin" → interceptor permite execução
    }

    @Test
    void requiredRole_rejectsTokenWithWrongRole() {
        // Token com role "viewer" → interceptor rejeita com 403
    }

    @Test
    void expiredToken_isRejectedWithUnauthorized() {
        // Token expirado → interceptor rejeita com 401
    }

    @Test
    void corsFilter_appliesConfiguredHeaders() {
        // Filtro CORS aplica headers configurados
    }
}

@EnabledIf("isScriptAvailable")
class ConfigScriptIT {

    @Test
    void loadEngineAndExecuteScriptWithParameters() {
        // 1. Carregar engine Groovy
        // 2. Cachear script com parâmetros
        // 3. Executar e verificar resultado
    }

    @Test
    void fullFlow_loadCacheUpdateAndReExecute() {
        // Carregar → cachear → atualizar → re-executar
    }
}

@EnabledIf("isSecurityJwtAvailable")
class SecurityJwtIntegrationIT {

    static boolean isSecurityJwtAvailable() {
        try {
            Class.forName("org.demoiselle.jee.security.jwt.impl.TokenManagerImpl");
            return true;
        } catch (ClassNotFoundException e) {
            return false;
        }
    }
}

ProblemDetail pd = new ProblemDetail();
pd.setStatus(404);
pd.applyAboutBlankDefaults();
pd.getTitle(); // → "Not Found"

String link = LinkHeaderBuilder.build("/api/resource?filter=active", pageResult);
// Preserva query parameters existentes:
// </api/resource?filter=active&range=10-19>; rel="next", ...

@Inject
RefreshTokenManager refreshTokenManager;

// Gerar par de tokens
TokenPair pair = refreshTokenManager.issueTokenPair(user);
pair.accessToken();  // JWT de curta duração
pair.refreshToken(); // JWT de longa duração (apenas sub, jti, exp)

// Renovar access token
String newAccessToken = refreshTokenManager.refresh(pair.refreshToken());

// removeUser() automaticamente adiciona o JTI à blacklist
tokenManager.removeUser(user);

// Tokens revogados são rejeitados na validação
tokenManager.getUser(); // → DemoiselleSecurityException (401)

@ApplicationScoped
public class TenantClaimsEnricher implements ClaimsEnricher {

    @Override
    public void enrich(JwtClaims claims, DemoiselleUser user) {
        claims.setClaim("tenant_id", resolveTenantId(user));
    }

    @Override
    public void extract(JwtClaims claims, DemoiselleUser user) {
        String tenantId = claims.getStringClaimValue("tenant_id");
        user.getParams().put("tenant_id", tenantId);
    }
}

// Observar login/logout/falha
public void onAuth(@Observes AuthenticationEvent event) {
    log.info("{} {} at {}", event.action(), event.user().getIdentity(), event.timestamp());
}

// Observar negação de autorização
public void onDenied(@Observes AuthorizationEvent event) {
    log.warn("Acesso negado: {} tentou acessar {}/{}",
        event.user().getIdentity(), event.resource(), event.operation());
}

// OR: usuário precisa de pelo menos UMA das roles
@RequiredAnyRole({"admin", "manager", "supervisor"})
public void aprovarPedido(Long id) { ... }

// AND: usuário precisa de TODAS as permissões
@RequiredAllPermissions({
    @Permission(resource = "pedido", operation = "aprovar"),
    @Permission(resource = "financeiro", operation = "consultar")
})
public void aprovarPedidoFinanceiro(Long id) { ... }

// Antes (string bruta, propenso a erros de digitação)
@CacheControl("max-age=3600, no-store")

// Depois (atributos tipados com validação em compilação)
@CacheControl(maxAge = 3600, noStore = true)

// Combinação de atributos
@CacheControl(maxAge = 86400, mustRevalidate = true, isPrivate = true)

// Modo legado mantido para retrocompatibilidade
@CacheControl("no-cache, no-store, must-revalidate")

@Configuration(prefix = "app")
public class AppConfig {

    @DefaultValue("8080")
    private int port;

    @DefaultValue("localhost")
    private String host;

    @DefaultValue("INFO")
    private LogLevel logLevel;  // enums suportados
}

// Antes: cast necessário
List<?> content = result.getContent();
List<Produto> produtos = (List<Produto>) content;

// Depois: type-safe
Result<Produto> result = dao.find();
List<Produto> produtos = result.getContent(); // sem cast

// Novos métodos com implementação default
boolean exists = dao.exists(42L);       // delega para find(id) != null
long total = dao.count();               // delega para find().getContent().size()
List<Produto> all = dao.findAll();      // delega para find().getContent()

throw new DemoiselleRestException("Token expirado", "DEMOISELLE-SEC-001");

// toString() inclui o código
// "DemoiselleRestException[DEMOISELLE-SEC-001]: Token expirado"

// Entradas expiradas são removidas automaticamente
// TTL padrão: 3600 segundos (1 hora)
// Limpeza executada a cada chamada de setUser()

// Antes: DemoiselleUser armazenado diretamente
// Depois: record com timestamp de expiração
record TokenEntry(DemoiselleUser user, Instant expiresAt) {}

// SecurityFilter.java — fonte única do Token no container CDI
@Produces
@RequestScoped
public Token produceToken() {
    if (currentToken != null) {
        return currentToken;  // TokenImpl mutável com key/type do header
    }
    return new TokenImpl();   // TokenImpl vazio (mutável)
}

@ApplicationScoped
public class CalculatorService {

    @McpTool(description = "Soma dois números inteiros")
    public int add(@McpParam(name = "a", description = "Primeiro operando") int a,
                   @McpParam(name = "b", description = "Segundo operando") int b) {
        return a + b;
    }
}

@McpTool(name = "buscar-produtos", description = "Busca produtos por filtro")
public List<Produto> buscar(
        @McpParam(name = "categoria", description = "Categoria do produto") String categoria,
        @McpParam(name = "precoMax", description = "Preço máximo", required = false) Double precoMax) {
    // ...
}

@McpResource(uri = "config://app", name = "App Config",
             description = "Configuração da aplicação", mimeType = "application/json")
public String readConfig() {
    return "{ \"version\": \"1.0\" }";
}

@McpPrompt(name = "code-review", description = "Revisa código fonte")
public List<Map<String, Object>> codeReview(
        @McpParam(name = "code", description = "Código a revisar") String code) {
    return List.of(Map.of(
        "role", "user",
        "content", Map.of("type", "text", "text", "Revise este código: " + code)
    ));
}

@Property(tries = 200)
void modifyingOriginalListDoesNotAffectGetContent(
        @ForAll List<String> elements) {

    List<String> mutableList = new ArrayList<>(elements);
    ResultSet rs = new ResultSet();
    rs.setContent(mutableList);

    List<?> snapshot = rs.getContent();

    mutableList.add("EXTRA");
    mutableList.clear();

    assertEquals(elements.size(), snapshot.size(),
        "Modificações na lista original não devem afetar getContent()");
}

// Antes
import javax.inject.Inject;
import javax.enterprise.context.ApplicationScoped;
import javax.persistence.Entity;
import javax.ws.rs.GET;

// Depois
import jakarta.inject.Inject;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.persistence.Entity;
import jakarta.ws.rs.GET;

// Antes: getError(), getErrorDescription(), getErrorLink()
msg.getError();

// Depois: error(), errorDescription(), errorLink()
msg.error();

// Antes: strings e if-else no DAO
if (value == null) { /* isNull */ }
else if (value.contains("*")) { /* like */ }

// Depois: pattern matching exaustivo
return switch (op) {
    case FilterOp.IsNull(var key)   -> cb.isNull(from.get(key));
    case FilterOp.Like(var key, var p) -> buildLikePredicate(cb, cq, from, key, p);
    // ... compilador garante exaustividade
};

// Antes: Collections.unmodifiableList() — view mutável
List<String> roles = user.getRoles(); // view
user.addRole("admin");
roles.contains("admin"); // true (!)

// Depois: List.copyOf() — cópia defensiva
List<String> roles = user.getRoles(); // cópia independente
user.addRole("admin");
roles.contains("admin"); // false

// Antes: raw type, cast necessário
Result result = dao.find();
List<?> content = result.getContent();

// Depois: genérico, type-safe
Result<Produto> result = dao.find();
List<Produto> content = result.getContent();

// Antes: DemoiselleSecurityException genérica
catch (DemoiselleSecurityException e) { /* status 429 */ }

// Depois: Response JAX-RS direta com Retry-After
// O interceptor retorna Response 429 diretamente
// Se seu código capturava a exceção, ajuste para tratar a resposta HTTP

// Antes: TokenImpl era @RequestScoped (bean CDI normal)
// Problema: ambiguidade com o producer em SecurityFilter (WELD-001409)

// Depois: TokenImpl é @Vetoed (não é mais bean CDI)
// O Token request-scoped é produzido exclusivamente pelo SecurityFilter
// setKey() e setType() continuam funcionando normalmente

// TokenRecord existe como alternativa imutável para uso externo,
// mas o producer do SecurityFilter entrega TokenImpl (mutável)
// para compatibilidade com TokenManagerImpl.setUser()

// Antes (continua funcionando)
@CacheControl("max-age=3600, no-store")

// Depois (nova opção)
@CacheControl(maxAge = 3600, noStore = true)

@RequiredAnyRole({"admin", "manager"})     // OR — nova
@RequiredAllPermissions({...})              // AND — nova
@RequiredRole("admin")                      // existente — inalterada
@RequiredPermission(resource="x", op="y")  // existente — inalterada