Plugin e classe de modelo

Antes de começar

• Módulos 01 a 03 concluídos. Você vai precisar do 2Pack_1.0.0.zip gerado no módulo 03.
• Servidor rodando em modo Debug pelo Eclipse (Run > Debug Configurations > server.product). A partir daqui, o debug deixa de ser opcional.
• Este é o primeiro módulo com Java. O que se espera: saber criar classe, herança, e ler uma stack trace.

O que você vai construir

Até o módulo 03, a janela Visita Técnica funcionava sem nenhuma linha de Java. O iDempiere salvava os registros com uma classe genérica (GenericPO), que sabe gravar qualquer tabela mas não conhece nenhuma regra.

Neste módulo você cria o plugin com.gardenworld.visitas e coloca nele três coisas:

• O 2Pack do módulo 03, aplicado automaticamente quando o plugin sobe. Instalar o plugin passa a instalar tabelas, janela e menu.
• As classes das suas tabelas, geradas a partir do Dicionário.
• A primeira regra de negócio: uma visita só pode ser concluída se tiver pelo menos uma linha.

Por que um plugin

O iDempiere roda sobre OSGi: o servidor é um conjunto de módulos (bundles) que sobem, param e se enxergam por contratos. O core é um desses bundles; o seu plugin é outro.

A regra da comunidade é simples: customização nunca altera o core. Tudo o que você escreve fica no seu plugin e conversa com o core por pontos de extensão (factories, event handlers, serviços). É isso que permite atualizar o iDempiere sem reaplicar customizações à mão.

Passo a passo

1. Crie o plugin

No Eclipse, File > New > Other > Plug-in Development > Plug-in Project.

Na página seguinte:

Clique em Finish. O plugin fica dentro do repositório do projeto (o do módulo 03), mas aparece no workspace do Eclipse ao lado do core.

2. Declare as dependências

Abra META-INF/MANIFEST.MF, vá para a aba MANIFEST.MF (o texto puro) e deixe assim:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Visitas Técnicas
Bundle-SymbolicName: com.gardenworld.visitas;singleton:=true
Bundle-Version: 1.0.0.qualifier
Bundle-Activator: com.gardenworld.visitas.Activator
Bundle-RequiredExecutionEnvironment: JavaSE-17
Require-Bundle: org.adempiere.base;bundle-version="14.0.0",
 org.adempiere.plugin.utils;bundle-version="14.0.0"
Import-Package: org.osgi.framework,
 org.osgi.service.component.annotations;resolution:=optional
Bundle-ActivationPolicy: lazy
Automatic-Module-Name: com.gardenworld.visitas

O que importa aqui:

• Require-Bundle: o plugin enxerga as classes do core (org.adempiere.base) e os utilitários de plugin (org.adempiere.plugin.utils), onde fica o ativador que aplica 2Pack.
• org.osgi.service.component.annotations: as anotações @Component que você vai usar no passo 6. Só existem na compilação, por isso resolution:=optional.
• singleton:=true: só pode existir uma versão do plugin ativa por vez.

3. O plugin aplica o 2Pack sozinho

Mova o pacote do módulo 03 para dentro do plugin:

cd ~/sources/guia-idempiere-projeto
git mv 2pack/2Pack_1.0.0.zip com.gardenworld.visitas/META-INF/2Pack_1.0.0.zip

Troque o conteúdo de Activator.java:

package com.gardenworld.visitas;

import org.adempiere.plugin.utils.Incremental2PackActivator;

public class Activator extends Incremental2PackActivator {
}

Isso é tudo. Quando o plugin sobe, o Incremental2PackActivator procura arquivos META-INF/2Pack_*.zip, compara as versões com o que já foi instalado para este plugin e aplica só o que falta, em ordem de versão. O controle fica na tabela AD_Package_Imp, com o nome do plugin (com.gardenworld.visitas).

Quando mudar o Dicionário, gere 2Pack_1.0.1.zip e coloque ao lado. O 1.0.0 nunca é reaplicado.

4. Suba o plugin junto com o servidor

O server.product não inclui plugins novos sozinho.

1. Run > Debug Configurations > server.product, aba Plug-ins.
2. Na lista Workspace, marque com.gardenworld.visitas.
3. Na coluna Auto-Start do plugin, escolha true.
4. Clique em Validate Plug-ins. Não pode haver erro.
5. Debug.

Sem o Auto-Start, o plugin é carregado mas não é iniciado: o ativador não roda e nada do que você registrar no passo 6 existe.

Com o servidor no ar, digite no console do Eclipse:

ss com.gardenworld

O plugin deve aparecer como ACTIVE. Se aparecer INSTALLED, faltou alguma dependência: rode diag <id> com o número da primeira coluna para ver qual.

Agora confira o 2Pack: entre como System, abra a janela Pack In e vá para a aba Package Installation. Deve haver um registro com.gardenworld.visitas, versão 1.0.0, com status de concluído.

5. Gere as classes das tabelas

Conceito: para cada tabela, o iDempiere trabalha com três classes:

A separação existe porque as classes I e X são geradas de novo toda vez que uma coluna muda. Se você escrever regra nelas, perde tudo na próxima geração.

Primeiro, diga ao iDempiere qual é o pacote Java do tipo de entidade: como System, na janela Entity Type, abra EDU e preencha Model Package com com.gardenworld.visitas.model. O gerador usa isso quando uma tabela sua aponta para outra tabela sua.

Depois, rode o processo Generate Model (busque no menu):

O processo roda no servidor e grava os arquivos na pasta informada, criando as subpastas do pacote. Como o servidor está na sua máquina, o caminho é o da sua máquina.

No Eclipse, clique no plugin e aperte F5 para ver os quatro arquivos novos: I_EDU_Visita, X_EDU_Visita, I_EDU_VisitaLinha e X_EDU_VisitaLinha.

Abra X_EDU_Visita e repare na primeira linha da classe:

@org.adempiere.base.Model(table="EDU_Visita")
public class X_EDU_Visita extends PO implements I_EDU_Visita, I_Persistent

É essa anotação que liga a classe à tabela. Repare também no nome dos getters: a coluna EDU_IsConcluida vira isEDU_IsConcluida(), e EDU_DataVisita vira getEDU_DataVisita().

6. Registre a model factory

O core ainda não sabe que essas classes existem. Quem diz ao iDempiere "para a tabela EDU_Visita, use esta classe" é uma model factory.

Crie com.gardenworld.visitas.VisitasModelFactory:

package com.gardenworld.visitas;

import org.adempiere.base.AnnotationBasedModelFactory;
import org.adempiere.base.IModelFactory;
import org.osgi.service.component.annotations.Component;

@Component(immediate = true, service = IModelFactory.class,
           property = {"service.ranking:Integer=1"})
public class VisitasModelFactory extends AnnotationBasedModelFactory {

    @Override
    protected String[] getPackages() {
        return new String[] {"com.gardenworld.visitas.model"};
    }
}

A classe base varre o pacote informado atrás de classes com @Model e monta o mapa tabela → classe. Quando encontra uma X que tem uma subclasse (a sua M), usa a subclasse.

O @Component registra a factory como serviço OSGi. O Eclipse transforma a anotação num arquivo em OSGI-INF/ e adiciona o cabeçalho Service-Component ao manifesto. Confira os dois depois de salvar.

7. A classe M e a primeira regra

Crie com.gardenworld.visitas.model.MVisita:

package com.gardenworld.visitas.model;

import java.sql.ResultSet;
import java.util.List;
import java.util.Properties;

import org.compiere.model.Query;

public class MVisita extends X_EDU_Visita {

    private static final long serialVersionUID = 1L;

    public MVisita(Properties ctx, int EDU_Visita_ID, String trxName) {
        super(ctx, EDU_Visita_ID, trxName);
    }

    public MVisita(Properties ctx, String EDU_Visita_UU, String trxName) {
        super(ctx, EDU_Visita_UU, trxName);
    }

    public MVisita(Properties ctx, ResultSet rs, String trxName) {
        super(ctx, rs, trxName);
    }

    /** Linhas da visita, em ordem. */
    public List<X_EDU_VisitaLinha> getLinhas() {
        return new Query(getCtx(), X_EDU_VisitaLinha.Table_Name,
                X_EDU_VisitaLinha.COLUMNNAME_EDU_Visita_ID + "=?", get_TrxName())
            .setParameters(getEDU_Visita_ID())
            .setOrderBy(X_EDU_VisitaLinha.COLUMNNAME_Line)
            .list();
    }

    @Override
    protected boolean beforeSave(boolean newRecord) {
        if (isEDU_IsConcluida()
                && is_ValueChanged(COLUMNNAME_EDU_IsConcluida)
                && getLinhas().isEmpty()) {
            log.saveError("Error", "Inclua pelo menos uma linha antes de concluir a visita");
            return false;
        }
        return true;
    }
}

Pontos que valem para qualquer classe M:

• Os três construtores são obrigatórios. A factory cria os objetos por reflexão: pelo ID, pelo UUID e a partir de uma linha de ResultSet. Faltou um, e algum caminho do core falha ao criar o objeto.
• beforeSave devolve false para barrar o salvamento. O log.saveError define a mensagem que o usuário vê.
• get_TrxName() em toda consulta. A consulta roda dentro da mesma transação do registro sendo salvo. Sem isso, você lê o banco "de fora" e não enxerga o que ainda não foi confirmado.
• is_ValueChanged evita que a regra dispare em todo salvamento. Aqui ela só roda quando alguém marca Concluída.

O nome segue o costume do core: a classe M tira o prefixo da tabela (X_C_Order → MOrder). Uma M por tabela é o normal; a EDU_VisitaLinha não precisa de uma por enquanto.

8. Teste

O Eclipse recompila ao salvar e, em modo Debug, costuma aplicar a mudança sem reiniciar. Para uma classe nova e uma factory nova, reinicie o servidor.

1. Como GardenAdmin, crie uma visita, sem linhas, e salve.
2. Marque Concluída e salve. A mensagem da sua regra aparece e o registro não é gravado.
3. Desmarque, inclua uma linha, volte ao cabeçalho, marque Concluída e salve. Agora grava.

Por fim, coloque um breakpoint na primeira linha do beforeSave e salve qualquer visita. O Eclipse para ali. Inspecione this: é um MVisita, não um GenericPO. A factory está funcionando.

9. Commit

cd ~/sources/guia-idempiere-projeto
git add .
git commit -m "Plugin com.gardenworld.visitas: 2Pack, classes de modelo e regra de conclusão"

Não versione a pasta bin/ nem target/: crie um .gitignore com as duas.

Checkpoint

Erros comuns

Desafio

No módulo 02, a Mandatory Logic obriga o Motivo da Urgência quando a visita é urgente. Mas essa lógica é da tela: uma visita criada por um processo, uma importação ou uma API passa direto por ela.

Repita a regra no beforeSave da MVisita, para que valha em qualquer caminho. Dica: isEDU_IsUrgente() e getEDU_MotivoUrgencia().

Referência

Eventos da classe de modelo

Os quatro rodam antes dos event handlers de outros plugins (módulo 05). Regra da própria tabela fica na M; reação a tabelas de outros (inclusive do core) fica em event handler.

Métodos úteis de PO

Alternativa: o model.generator do Eclipse

O workspace do iDempiere tem uma configuração de execução model.generator (Run > Run Configurations > Eclipse Application) que gera as mesmas classes sem subir o servidor. O processo Generate Model, usado no passo 5, existe desde o iDempiere 11 e dispensa essa configuração.

Leitura oficial

• Plugin: Model Factory (em inglês)

Próximo módulo

05 · Regras de negócio: callout e event handler: reagir ao que o usuário digita, antes de salvar, e ao que outros plugins e o core gravam.