Demoiselle 4

=============

O framework Demoiselle implementa o conceito de framework integrador. Seu objetivo é facilitar a construção de aplicações minimizando tempo dedicado à escolha e integração de frameworks especialistas, o que resulta no aumento da produtividade e garante a manutenibilidade dos sistemas.

Disponibiliza mecanismos reusáveis voltados as funcionalidades mais comuns de uma aplicação (arquitetura, segurança, transação, mensagem, configuração, tratamento de exceções, etc).

Primeiros passos

Pré-requisitos: Java 21+, Maven 3.9+ e um runtime compatível com Jakarta EE 10. Importe o BOM para manter todos os módulos na mesma versão:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.demoiselle.jee</groupId>
            <artifactId>demoiselle-parent-bom</artifactId>
            <version>4.1.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.demoiselle.jee</groupId>
        <artifactId>demoiselle-core</artifactId>
    </dependency>
    <dependency>
        <groupId>org.demoiselle.jee</groupId>
        <artifactId>demoiselle-rest</artifactId>
    </dependency>
    <dependency>
        <groupId>org.demoiselle.jee</groupId>
        <artifactId>demoiselle-crud</artifactId>
    </dependency>
</dependencies>

Snapshots exigem o repositório Sonatype OSS. Para detalhes de configuração, exemplos CRUD e segurança, consulte o guia completo.

Versão 4.1.0-SNAPSHOT

A versão 4 do Demoiselle Framework traz as seguintes mudanças principais:

• Jakarta EE 10: Migração completa do namespace javax.* para jakarta.*
• Java 21: baseline mínimo LTS, verificado pelo Maven Enforcer
• CDI 4.0: Atualização para Jakarta Contexts and Dependency Injection 4.0
• JUnit 5: Migração completa dos testes para JUnit Jupiter
• OpenAPI 3.0: Substituição do Swagger 1.x por MicroProfile OpenAPI
• GitHub Actions: Pipeline CI em Java 21 com build completo, cobertura e credenciais de checkout desabilitadas
• Supply chain: plugins Maven com versões explícitas e SBOM agregado CycloneDX em JSON/XML
• Remoção do WildFly Swarm: Framework agnóstico de runtime (compatível com WildFly 27+, Quarkus, Open Liberty)
• Remoção do DeltaSpike: Substituído por implementação própria baseada em CDI 4.0

Modernização Jakarta EE 10

A versão 4 inclui modernizações que aproveitam plenamente Java 21 e Jakarta EE 10:

• Records para DTOs imutáveis (SortModel, DemoiselleRestExceptionMessage, ResultSet)
• Sealed Classes + Pattern Matching para filtros CRUD type-safe (FilterOp)
• CDI 4.0 Lite Build-Compatible Extensions compatíveis com GraalVM native image
• Coleções imutáveis com cópias defensivas via List.copyOf() / Map.copyOf()
• Preparação para Virtual Threads com ReentrantReadWriteLock e eliminação de campos estáticos mutáveis
• JPA 3.1 CriteriaUpdate type-safe e suporte a EntityGraph no AbstractDAO

Melhorias no Módulo CRUD

O módulo demoiselle-crud inclui funcionalidades modernas de persistência e proteção:

• Soft Delete — exclusão lógica declarativa via @SoftDeletable com suporte a LocalDateTime, Boolean e Instant
• Auditoria Automática — preenchimento automático de @CreatedAt, @UpdatedAt, @CreatedBy, @UpdatedBy via JPA EntityListener
• Specification Pattern — composição declarativa de consultas JPA com and(), or(), not()
• Operações em Batch — persistAll(), removeAll(), updateAll() com flush/clear automático
• PageResult<T> — record imutável com metadados de paginação (totalPages, currentPage, hasNext, hasPrevious)
• Operadores de Comparação — gt:, lt:, gte:, lte:, between:, in: via query string
• Cache de Consultas — @Cacheable com invalidação automática via eventos CDI
• Limites contra abuso — teto global de paginação, filtros, valores e campos de ordenação

📖 Documentação completa com exemplos

Segurança por padrão

• Respostas REST incluem headers nosniff, DENY, no-referrer e uma Permissions-Policy conservadora sem sobrescrever valores definidos pela aplicação.
• O header Demoiselle-Version fica oculto por padrão e pode ser reativado explicitamente.
• JWT mantém o perfil compat como default e oferece recommended e strict para exigir iss, aud, typ, iat, jti, idade máxima e, no modo estrito, sub.
• Algoritmos JWT continuam em allowlist (RS256 por padrão) e kid desconhecido é rejeitado.

Segurança e contratos operacionais

• MCP fail-closed — sessões vinculadas ao principal, revalidação Bearer no POST, expiração, teto de sessões e rate limit de tools.
• Rate limit e brute force atômicos — SecurityStore com TTL/teto e forwarded headers confiáveis somente para proxies configurados.
• HashCash mantido — módulo no reactor/BOM, desafio assinado e vinculado ao recurso, segredo obrigatório e proteção contra replay.
• SPIs extensíveis — JwtKeyProvider, CacheBackend e SecretProvider, com providers locais limitados e sem infraestrutura externa obrigatória.
• Dados resilientes — @Idempotent, Transactional Outbox após commit, cursor/keyset assinado e headers de lifecycle/depreciação.
• Contratos seguros — separação entre Result e MutableResult e locking compartilhado por engine no módulo Script.

Consulte o guia de migração 4.1, o roadmap com status das entregas, o guia das extensões de produção — com benefícios e critérios de adoção para produtos Demoiselle — e o inventário dinâmico do reactor.

Módulo de Observabilidade (demoiselle-observability)

Módulo transversal com métricas, health checks e tracing distribuído:

• @Counted — CDI interceptor que incrementa contadores MicroProfile Metrics automaticamente
• @Traced — CDI interceptor que cria spans OpenTelemetry com atributos do módulo
• Health Checks — Liveness (CDI ativo) e Readiness (configuração carregada, chaves JWT disponíveis)
• Degradação Graceful — Quando MicroProfile Metrics, Health ou OpenTelemetry não estão no classpath, o módulo usa implementações noop sem erro

Módulo OpenAPI (demoiselle-openapi)

Geração automática de documentação OpenAPI para endpoints do framework:

• OpenAPIContributor — Interface para módulos contribuírem definições OpenAPI parciais
• DemoiselleOASModelReader — Agrega contribuições via CDI com tolerância a falhas
• Configurável — Ativação/desativação via demoiselle.openapi.enabled

Módulo MCP (demoiselle-mcp)

Suporte a servidores MCP (Model Context Protocol) para integração com clientes de IA:

• @McpTool — Expõe métodos CDI como ferramentas MCP com geração automática de JSON Schema
• @McpResource — Expõe dados como recursos MCP (arquivos, configurações, registros)
• @McpPrompt — Expõe templates de prompt MCP com argumentos tipados
• Transporte SSE — Comunicação HTTP via Server-Sent Events (JAX-RS)
• Transporte stdio — Comunicação local entre processos via stdin/stdout
• Integrações opcionais — ProblemDetail (RFC 9457), JWT, PageResult, @RateLimit, @Counted
• Degradação Graceful — Funciona com dependências mínimas (demoiselle-core + demoiselle-configuration)

Testes de Integração (demoiselle-integration-tests)

Módulo dedicado a testes de integração entre módulos:

• ConfigSecurityRestIT — Fluxo completo configuração → segurança JWT → REST
• ConfigScriptIT — Fluxo configuração → execução de scripts
• Testes Baseados em Propriedades — Invariantes de segurança, configuração, CRUD e integração validados com jqwik

📖 Documentação completa com exemplos

O nome Demoiselle é uma homenagem à série de aeroplanos construídos por Santos Dummont entre 1907 e 1909. Também conhecido como Libellule, as Demoiselles foram os melhores, menores e mais baratos aviões da sua época. Como sua intenção era popularizar a aviação com fabricação em larga escala, o inventor disponibilizou os planos em revistas técnicas para qualquer pessoa que se interessasse.

O framework Demoiselle usa a mesma filosofia do "Pai da Aviação", tendo sido disponibilizado como software livre em abril de 2009, sob a licença livre LGPL version 3. Mais informações no portal.

Links úteis

• Portal: Central de acesso as informações do Demoiselle
• Documentação Jakarta EE 10: Funcionalidades modernizadas com exemplos de código
• Roadmap técnico sugerido: Evoluções priorizadas a partir da auditoria
• Documentação Legada: Documentação dos módulos (versões anteriores)
• Fórum/Tracker: Fóruns de discussão e Submissão/acompanhamento de Bugs, Improvements e New Features
• Lista de discussão: Comunicação e troca de experiências entre os usuários do projeto.

Repositório Maven

Releases publicadas no Maven Central não exigem configuração adicional. Para usar versões SNAPSHOT, configure explicitamente o repositório Sonatype OSS:

<repository>
    <id>sonatype-oss-snapshots</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <releases>
        <enabled>false</enabled>
    </releases>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>

Contribuindo

1. Faça o seu fork.
2. Crie o seu branch (ramo) - (git checkout -b meu_framework)
3. Commit seu código (git commit -am "Explicando o motivo/objetivo")
4. Agora execute o Push para o branch (git push origin meu_framework)
5. Dúvidas, problemas ou sugestões? Crie uma issue no GitHub com o link para o seu branch