Imported from snk-devcenter/addon-studio (plugins/addon-studio/skills/listener/SKILL.md). Install upstream with npx skills add snk-devcenter/addon-studio --skill listener. Copyright stays with the author.

name: listener description: Cria, revisa e padroniza listeners de persistência Sankhya com @Listener (classe estende PersistenceEventAdapter) — reage a eventos CRUD (before/after insert, update, delete) de qualquer entidade JAPE, inclusive instâncias nativas. Use ao criar, alterar, revisar, auditar ou padronizar reação a gravação/exclusão de registros, ao validar ou preencher campos automaticamente no insert/update, ao exigir campo preenchido/não vazio (sinal prático: o dev fala do campo da tabela no insert/update, não de payload nem de tela — vale para qualquer origem de gravação: REST, tela, job, integração; se for só o payload que chega no endpoint, é controller; se for NOT NULL na coluna, é database), ao implementar auditoria de alterações (quem mudou e quando), ao reagir a mudança de status de um registro, ao bloquear gravação ou exclusão com exceção em before*, ao trabalhar com classes *Listener de persistência, ou ao tocar em código com @Listener/PersistenceEventAdapter/PersistenceEvent. NÃO usar para interceptar busca/carregamento/leitura de entidades (FinderListener, filtro em query) — isso é @BeforeLoadListener, skill before-load-listener. NÃO usar quando o gatilho é o barramento comercial do MGE e não a gravação do registro — validação que roda na confirmação/faturamento de documento do comercial via interface Regra + ContextoRegra (ex. liberação de limite de crédito) é @BusinessRule, skill business-rule. Gravação de registro, em qualquer tabela, é aqui. license: Proprietary compatibility: Sankhya Addon Studio 2.0 (Wildfly/EJB + JAPE SDK). Java 8, Gradle, ISO-8859-1.

Listener de Persistência (@Listener) — Addon Studio 2.0

@Listener executa lógica personalizada em eventos de persistência (CRUD) de uma entidade JAPE — antes/depois de insert, update e delete. Funciona em entidades do próprio add-on e em instâncias nativas do sistema (CabecalhoNota, Parceiro, Produto, etc.). A anotação registra o listener automaticamente — sem edição manual de XML.

⚠️ @Listener ≠ @BeforeLoadListener. São mecanismos distintos, com anotação, interface, evento e escopo diferentes: @Listener reage a escrita (insert/update/delete, via PersistenceEventAdapter); @BeforeLoadListener intercepta leitura (busca/carregamento no Finder, via FinderListener) — e só funciona em instâncias do próprio add-on. Tarefa de leitura/filtro de busca → skill before-load-listener.

1. Quando usar — @Listener vs @BeforeLoadListener vs @BusinessRule vs @ActionButton

Regra rápida: reagir a gravação/exclusão de registro (automático, sem clique)? @Listener. Filtrar leitura? @BeforeLoadListener. Regra de nota no barramento comercial? @BusinessRule.

Diferente do @BeforeLoadListener, o @Listener pode escutar instâncias nativas do sistema (CabecalhoNota, Financeiro, Parceiro, etc.).

2. Anatomia

import br.com.sankhya.jape.event.PersistenceEvent;
import br.com.sankhya.jape.event.PersistenceEventAdapter;
import br.com.sankhya.jape.vo.DynamicVO;
import br.com.sankhya.studio.annotations.Listener;
import com.google.inject.Inject;
import lombok.extern.java.Log;

import java.math.BigDecimal;

@Log
@Listener(instanceNames = "TdcXyzPedido")
public class TdcXyzPedidoListener extends PersistenceEventAdapter {

    private final CalculoPedidoService calculoService;

    @Inject
    public TdcXyzPedidoListener(CalculoPedidoService calculoService) {
        this.calculoService = calculoService;
    }

    @Override
    public void beforeInsert(PersistenceEvent event) throws Exception {
        DynamicVO vo = (DynamicVO) event.getVo();
        BigDecimal total = calculoService.calcularTotal(vo.asBigDecimalOrZero("VLRUNIT"),
            vo.asBigDecimalOrZero("QTD"));
        vo.setProperty("VLRTOT", total);
    }

    @Override
    public void beforeUpdate(PersistenceEvent event) throws Exception {
        // Recalcula apenas se algum campo relevante mudou
        if (event.getModifingFields().isModifing("VLRUNIT")
                || event.getModifingFields().isModifing("QTD")) {
            beforeInsert(event);
        }
    }
}

• Classe estende br.com.sankhya.jape.event.PersistenceEventAdapter e sobrescreve só os eventos de interesse.
• Listener é entrypoint fino: filtra o evento, manipula o DynamicVO e delega a regra de negócio a service/use case injetado.

3. Atributo da anotação @Listener

@Listener(instanceNames = "TdcXyzPedido")                        // uma instancia
@Listener(instanceNames = {"CabecalhoNota", "Financeiro"})       // varias instancias (nativas)

Gotcha: instanceNames é o nome lógico da entidade, não a tabela. Para @JapeEntity(entity = "TdcXyzPedido", table = "TDCXYZPED"), usa-se @Listener(instanceNames = "TdcXyzPedido").

4. Eventos disponíveis (PersistenceEventAdapter)

• Todos declaram throws Exception. Em before*, exceção lançada cancela a operação e propaga a mensagem ao usuário — use exceção tipada com mensagem de negócio.
• Alterações no DynamicVO feitas em before* são persistidas junto com a operação — não chame save.
• Em after* o registro já foi gravado — alterar o VO ali não persiste nada.
• O adapter também expõe hooks avançados (afterLoadValueObject, afterRetrieveValueObject, updateRequired, transferData) — raramente necessários.

5. API do PersistenceEvent

DynamicVO vo = (DynamicVO) event.getVo();  // getVo() retorna EntityVO — cast obrigatorio

Gotcha de pacote: JdbcWrapper do evento é br.com.sankhya.jape.dao.JdbcWrapper — não br.com.sankhya.jape.util.

Métodos úteis do DynamicVO

Do VO à entidade tipada — EntityMapper.fromVO

Para trabalhar com a entidade @JapeEntity em vez de strings de campo:

import br.com.sankhya.sdk.data.repository.impl.EntityMapper;

TdcXyzPedido pedido = EntityMapper.fromVO(event.getVo(), TdcXyzPedido.class);
if (!pedido.deveProcessar()) return;  // regra de dominio na entidade, nao no listener

6. ModifingFields — filtrar updates por campo alterado

beforeUpdate/afterUpdate disparam em qualquer update da instância — e o evento de update só traz os campos alterados no VO. Filtre pelo que mudou:

@Override
public void beforeUpdate(PersistenceEvent event) throws Exception {
    DynamicVO vo = (DynamicVO) event.getVo();
    // Preenche vendedor preferencial so quando CODPARC muda sem CODVEND explicito
    if (event.getModifingFields().isModifing("CODPARC")
            && !event.getModifingFields().isModifing("CODVEND")) {
        preencherVendedorDoParceiro(vo);
    }
}

Gotcha: no update, vo.getProperty("CAMPO") de campo não alterado pode vir null — o VO do evento só carrega o delta. Precisa do registro completo em after*? Leia a PK do VO e recarregue via repository/use case.

7. Injeção de dependência

@Listener suporta @Inject (Guice) — não consta na documentação oficial, mas é suportado pelo SDK. Delegue a regra de negócio a services/use cases injetados via construtor:

@Log
@Listener(instanceNames = "TdcXyzPedido")
public class TdcXyzPedidoListener extends PersistenceEventAdapter {

    private final LimiteCreditoService limiteService;

    @Inject
    public TdcXyzPedidoListener(LimiteCreditoService limiteService) {
        this.limiteService = limiteService;
    }

    @Override
    public void beforeInsert(PersistenceEvent event) throws Exception {
        DynamicVO vo = (DynamicVO) event.getVo();
        // Excecao tipada do service bloqueia a gravacao com mensagem de negocio
        limiteService.validar(vo.asBigDecimalOrZero("CODPARC"), vo.asBigDecimalOrZero("VLRTOT"));
    }
}

• @Inject de com.google.inject.Inject — nunca javax.inject.Inject.
• Dependências private final, injetadas via construtor. Nunca new em dependência gerenciada.
• Services/repositories registrados no módulo Guice do projeto (ver dependency-injection).

8. Transação, loops e chamadas externas

O listener roda dentro da transação da operação:

• Exceção em before* → operação cancelada (rollback) e mensagem propagada ao usuário.
• Acesso a banco na mesma transação: use event.getJdbcWrapper() ou repositories — nunca abra/feche conexão própria.
• Chamada externa síncrona (API HTTP) dentro do listener é PROIBIDA — segura a transação e derruba o tempo de resposta da gravação. Padrão correto: gravar numa tabela-fila e processar via @Job ou worker pool assíncrono (fire-and-forget).

Loop de eventos

Listener que grava na própria instância que escuta (direta ou indiretamente via service) dispara os eventos de novo → loop infinito. Sempre proteja com guard clause de estado:

@Override
public void afterUpdate(PersistenceEvent event) throws Exception {
    DynamicVO vo = (DynamicVO) event.getVo();
    // O service muda o STATUS do proprio registro — sem este guard,
    // o update do service dispararia este afterUpdate de novo (loop)
    if (!"P".equals(vo.asString("STATUS"))) return;
    processamentoService.processar(vo.asBigDecimal("NUPED"));
}

9. Anti-Patterns (PROIBIDO)

10. Checklist: Novo @Listener

1. Classe estende br.com.sankhya.jape.event.PersistenceEventAdapter e sobrescreve só os eventos necessários.
2. Anotada com @Listener(instanceNames = "<NomeDaInstancia>") — nome lógico da entidade, não a tabela; array para múltiplas instâncias.
3. getVo() com cast para DynamicVO.
4. beforeUpdate/afterUpdate filtram por getModifingFields().isModifing(...).
5. Alteração de campos só em before* via vo.setProperty(...) — sem save manual.
6. Bloqueio de operação via exceção tipada em before*, mensagem de negócio.
7. Regra de negócio delegada a service/use case via @Inject construtor (Guice).
8. Sem chamada externa síncrona — tabela-fila + @Job/worker se precisar integrar.
9. Guard clause anti-loop se o listener (ou quem ele chama) grava na própria instância.
10. @Log Lombok para logging (java.util.logging).

Skills relacionadas

• entity — entidade @JapeEntity alvo do listener; EntityMapper.fromVO converte VO → entidade
• repository — recarregar registro completo pela PK quando o VO do evento só traz o delta
• before-load-listener — interceptação de leitura (escopo distinto: busca, não CRUD)
• business-rule — hook transacional do barramento comercial (notas)
• job — processamento assíncrono da tabela-fila alimentada pelo listener
• dependency-injection — wiring Guice dos services/use cases injetados
• test — JUnit + Mockito dos métodos de evento