Callbacks (User Exits)
User Exits são funções ADVPL/TLPP compiladas no RPO, referenciadas na chave UserExits do thread pool ou slave. Cada callback aponta para uma função existente no Environment daquele pool.
Entenda Pool e serviço (thread pool vs slaves) e, se for proteger a API, Autenticação. Callbacks são opcionais — muitas APIs funcionam só com annotations e oRest.
Nenhuma chave é obrigatória — mas se você declarar OnBlock=, por exemplo, o valor não pode ficar vazio.
Trilha sugerida
Os 7 callbacks, na ordem em que costumam aparecer no ciclo de vida. Cada página detalha assinatura e exemplo.
| Etapa | Momento | Comece em |
|---|---|---|
| 1 — OnBlock | Na subida — bloqueia URNs listadas (Thread Pool) | OnBlock |
| 2 — OnAllow | Na subida — permite só URNs listadas (Thread Pool) | OnAllow |
| 3 — OnSelect | Antes de atender — escolhe o slave (Thread Pool) | OnSelect |
| 4 — OnStart | Thread criada (Slave) | OnStart |
| 5 — OnStop | Thread encerrada (Slave) | OnStop |
| 6 — OnSend | Antes de enviar a resposta (Slave) | OnSend |
| 7 — OnError | Exceção na thread (Pool e/ou Slave) | OnError |
Autenticação HTTP (OnAuth) é outro recurso — configurada em TlppData, não em User Exits. Ver Authorization.
Dois grupos
Infraestrutura do servidor — rodam na orquestração, antes ou durante a distribuição:
- OnBlock / OnAllow — montam o mapa de APIs na subida
- OnSelect — decide qual thread/slave atende cada requisição
Ciclo da requisição — rodam na thread que processa (em geral o slave):
- OnStart → endpoint → OnSend → resposta ao cliente
- OnStop quando a thread morre
- OnError se der runtime error no meio
Ordem típica de uma requisição (com slaves)
- Cliente envia HTTP.
- OnSelect (pool principal) escolhe o slave — ou delega ao algoritmo nativo (
-1). - Thread do slave executa OnStart (se configurado).
- Sua API roda (
@Get,LoadURNs, etc.). - OnSend ajusta headers/body finais.
- Resposta vai ao cliente.
- Se houve exceção em qualquer passo → OnError.
- Ao encerrar a thread → OnStop.
Sem slaves, OnStart/OnStop/OnSend ficam no thread pool que atende direto.
Topologia típica
| Camada | Callbacks comuns |
|---|---|
| Thread Pool principal | OnBlock ou OnAllow, OnSelect, OnError |
| Slaves | OnStart, OnStop, OnSend, OnError |
[THREAD_POOL]
UserExits=TP_UEX
Slaves=SLAVE_01,SLAVE_02
[TP_UEX]
OnBlock=U_OnBlock
;OnAllow=U_OnAllow
OnSelect=U_OnSelect
OnError=U_OnError
[SLAVE_01]
UserExits=SLAVES_UEX
[SLAVE_02]
UserExits=SLAVES_UEX
[SLAVES_UEX]
OnStart=U_OnStart
OnStop=U_OnStop
OnSend=U_OnSend
OnError=U_OnError
Equivalente em JSON (VdrCtrl():Start):
OnBlock vs OnAllow
Mesma finalidade (controlar APIs disponíveis), lógica oposta:
| Callback | Lógica |
|---|---|
| OnBlock | Bloqueia o que você listar — o resto fica liberado |
| OnAllow | Permite só o que você listar — o resto é bloqueado |
Configure apenas um por ambiente. Se ambos estiverem ativos, OnAllow vence e OnBlock é ignorado.
OnBlock e OnAllow só são lidos no Thread Pool — configurar nos slaves não tem efeito.
Exemplos no GitHub
User Exits em Callbacks:
Próximo passo: OnBlock