Value

Injecao de Valores (@Value) — Addon Studio 2.0

@Value injeta valores de configuracao (env vars, system properties, parametros Sankhya) diretamente em campos de componentes gerenciados pelo Guice. Conversao de tipo automatica. Thread-safe.

---

1. Atributos

| Atributo | Obrigatorio | Descricao | |:---------------|:------------|:--------------------------------------------------------------------------| | value | Nao | Nome da propriedade. Alternativa a param. | | param | Nao | Nome do parametro. Alternativa a value. Tem precedencia sobre value. | | group | Nao | Grupo do parametro — exclusivo de SANKHYA_PARAM. | | type | Sim | Fonte: ENV_VAR, SYSTEM_PROPERTY, SANKHYA_PARAM ou UNDEFINED. | | defaultValue | Sim | Fallback quando a propriedade nao e encontrada. Nunca deixar vazio. |

> * Ao menos um entre value ou param e obrigatorio.

---

2. Eager vs Lazy

| Modo | Sintaxe | Resolucao | Quando usar | |:-------|:-------------------------------|:------------------------|:-----------------------------------------| | Eager | private Integer porta | Na criacao do objeto | Valor sempre necessario | | Lazy | private Provider porta | Na primeira chamada .get(), cacheado para sempre | Valor opcional / custoso — config estavel |

// Eager — resolvido na inicializacao
@Value(value = "server.port", type = ValueType.SYSTEM_PROPERTY, defaultValue = "8080")
private Integer serverPort;

// Lazy — resolvido so quando chamado, DEPOIS congela
@Value(param = "MAX_RETRIES", type = ValueType.SANKHYA_PARAM, defaultValue = "3")
private Provider maxRetries;

public void executar() {
    int retries = maxRetries.get();  // resolve na primeira chamada; das seguintes vem do cache
    // ...
}

> Lazy adia a resolucao, mas NAO reflete mudanca posterior. O ValueProvider do SDK resolve uma unica vez no primeiro .get() e cacheia para sempre (double-checked locking). Como componentes vivem em singletons ou presos em grafos de vida longa (interceptor dentro de OkHttpClient reutilizado, client @Provides @Singleton), o valor so muda com restart. Para toggle em runtime, ver secao "Feature flag togglavel".

---

3. Fontes (ValueType)

ENV_VAR — variavel de ambiente

@Value(value = "API_KEY", type = ValueType.ENV_VAR, defaultValue = "")
private String apiKey;

SYSTEM_PROPERTY — propriedade Java (-Dchave=valor)

@Value(value = "server.port", type = ValueType.SYSTEM_PROPERTY, defaultValue = "8080")
private Integer serverPort;

SANKHYA_PARAM — parametro do sistema Sankhya

// Sem grupo
@Value(param = "MAX_CONNECTIONS", type = ValueType.SANKHYA_PARAM, defaultValue = "10")
private Provider maxConnections;

// Com grupo
@Value(param = "TIMEOUT", group = "CONNECTION", type = ValueType.SANKHYA_PARAM, defaultValue = "30")
private Provider connectionTimeout;

UNDEFINED — sempre usa o defaultValue

@Value(value = "qualquer", type = ValueType.UNDEFINED, defaultValue = "valor-fixo")
private String valorFixo;

---

4. Tipos suportados

String, Integer/int, Boolean/boolean, Long/long, Double/double, Float/float — e Provider de qualquer um deles. Conversao de String para o tipo declarado e automatica.

---

5. Exemplo completo

import br.com.sankhya.studio.stereotypes.Value;
import br.com.sankhya.internal.sdk.injectors.ValueType;
import br.com.sankhya.studio.stereotypes.Component;
import com.google.inject.Inject;
import com.google.inject.Provider;

@Component
public class IntegracaoConfig {

    @Value(value = "API_BASE_URL", type = ValueType.ENV_VAR, defaultValue = "http://localhost:8080")
    private Provider apiBaseUrl;

    @Value(value = "API_KEY", type = ValueType.ENV_VAR, defaultValue = "dev-key")
    private Provider apiKey;

    // ATENCAO: congela no primeiro get() — para toggle sem restart, ver secao "Feature flag togglavel"
    @Value(param = "INTEGRACAO_ATIVA", type = ValueType.SANKHYA_PARAM, defaultValue = "false")
    private Provider integracaoAtiva;

    @Value(value = "http.timeout", type = ValueType.SYSTEM_PROPERTY, defaultValue = "30000")
    private Integer timeout;

    private final IntegracaoHttpDispatcher dispatcher;

    @Inject
    public IntegracaoConfig(IntegracaoHttpDispatcher dispatcher) {
        this.dispatcher = dispatcher;
    }

    public void enviar(Payload payload) {
        if (!integracaoAtiva.get()) return;
        dispatcher.enviar(apiBaseUrl.get(), apiKey.get(), payload, timeout);
    }
}

---

6. Feature flag togglavel (sem restart)

@Value (eager OU lazy) nao serve para flag que precisa mudar em runtime: eager resolve na criacao, lazy congela no primeiro .get(). Para toggle refletir sem restart, leia o parametro direto a cada uso via MGECoreParameter (mesma API que o PropertyResolver do SDK chama por baixo):

import br.com.sankhya.modelcore.util.MGECoreParameter;

private boolean flagAtiva() {
    try {
        return MGECoreParameter.getParameterAsBoolean("PRXMODMINHAFLAG");
    } catch (Exception e) {
        return false; // default seguro — fora do contexto do ERP a chamada lanca
    }
}

Pre-requisitos:

• Parametro declarado com cacheable="false" no parameter.xml (ver secao 7) — senao o proprio ERP cacheia o valor.
• try/catch com default seguro e obrigatorio — fora do contexto do ERP (e em teste) a chamada lanca.

> ValueProvider.clearCache() existe e e publico, mas a classe e interna (br.com.sankhya.internal.*) — documentado apenas como solucao para testes, nao para producao.

---

7. Declarando o parametro (META-INF/parameter.xml)

@Value(type = SANKHYA_PARAM) e MGECoreParameter pressupoem parametro existente. Declare em src/main/resources/META-INF/parameter.xml — o deploy registra e o valor fica editavel nas Preferencias do ERP:

Restricoes do XSD (parameters.xsd) que derrubam o build/deploy:

| Atributo | Restricao | |:---------|:----------| | key | 3–15 chars, [a-zA-Z_]+ — sem digitos | | name | [a-zA-Z.]+ (pontuado, comeca com o modulo) | | description | 3–50 chars | | type | integer / string / boolean / date / list / number | | cacheable | false para valor que muda em runtime (flags) | | module | letra do modulo (ex.: B = Configuracao) | | list-content | opcoes separadas por \n quando type="list" |

> cacheable="false" e pre-requisito do pattern de flag togglavel da secao 6.

---

8. Restricoes

• Somente em classes gerenciadas pelo Guice (@Component, @Controller, @Repository, etc.). Em classes criadas com new, o campo fica null.
• Nao funciona em campos final.
• group e exclusivo de SANKHYA_PARAM — ignorado nas outras fontes.

---

9. Anti-Patterns (PROIBIDO)

| Anti-Pattern | Correcao | |:---------------------------------------------------|:--------------------------------------------------| | Classe nao gerenciada com @Value | Anotar classe com @Component ou equivalente | | Campo final anotado com @Value | Remover final | | defaultValue = "" em valor critico | Fornecer fallback significativo | | value e param juntos (ambiguidade) | Usar so param — tem precedencia de qualquer forma| | group em ENV_VAR ou SYSTEM_PROPERTY | group so funciona com SANKHYA_PARAM | | Eager em valor opcional/custoso | Usar Provider (Lazy) | | Provider como feature flag togglavel | Congela no primeiro .get() — ler MGECoreParameter a cada uso + cacheable="false" (secao 6) | | SANKHYA_PARAM sem declarar no parameter.xml | Declarar em META-INF/parameter.xml (secao 7) |

---

10. Checklist: Novo @Value

1. [ ] Classe anotada com estereotipo Guice (@Component, @Controller, etc.).
2. [ ] Escolher fonte correta: ENV_VAR, SYSTEM_PROPERTY ou SANKHYA_PARAM.
3. [ ] Usar param para SANKHYA_PARAM (com group se necessario); value para as demais.
4. [ ] SANKHYA_PARAM: parametro declarado no META-INF/parameter.xml (secao 7).
5. [ ] Definir defaultValue com valor significativo — nunca string vazia em config critica.
6. [ ] Decidir Eager vs Lazy: Provider se o valor for opcional/custoso — lembrando que congela apos o primeiro .get().
7. [ ] Flag que precisa mudar sem restart? Nao usar @Value — pattern da secao 6.
8. [ ] Campo nao e final.

Skills relacionadas

• dependency-injection — wiring Guice que injeta os @Value; @Value só funciona em @Component (e demais estereótipos) gerenciados pelo Guice
• addon-studio — regras universais do projeto

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: snk-devcenter
• Source: snk-devcenter/addon-studio
• License: MIT

Install and usage instructions live in the source repository linked above.