Package br.com.intersys.systextil.function

package br.com.intersys.systextil.function

Contém as classes que correspondem às funções globais do Systêxtil 5 em Vision. Aqui todas as funções globais são publicadas sem nenhum tipo de hierarquia ou agrupamento, da mesma forma como se encontram no Systêxtil 5.

Algumas funções convertidas muito tempo atrás podem se encontrar em outras packages próximas, ou mesmo em outro projeto, como systextil-util.

Como usar

Conferir sempre o javadoc da classe correspondente à função. Geralmente basta invocar o método estático executar passando os argumentos necessários.

Se não existir esse método, provavelmente a função retorna mais de um valor. Nesse caso, é preciso obter o objeto que vai retornar os valores - geralmente invocando o construtor da classe passando os argumentos. Os valores retornados são as propriedades do objeto obtido.

Se a execução da função lançar TagException, a aplicação deve levar isso em conta para interromper o processo e apresentar a mensagem correspondente da maneira correta. Em algumas situações, é preciso usar blocos try-catch em volta da chamada da função. Nos casos da chamada estar dentro do método validar de campos de texto do NXJ, o uso de blocos try-catch geralmente não é necessário.

Em formulários do NXJ que herdam de forms.systextil.ControleSobre: o argumento AppConnection é obtido através de getConn(); os argumentos mdi, utilTag e nome_form são obtidos diretamente da herança; e o argumento TagInteractive é obtido através de getInteractive().

Algumas funções fogem completamente aos padrões deste documento. Os procedimentos corretos, nesses casos, estão documentados no javadoc da classe correspondente.

Padrões para converter funções de Vision para Java

Via de regra, a cada função global em Vision corresponde uma classe Java nesta package. O nome da classe obedece às convenções de nomenclatura Java. Se o nome da função contiver um prefixo indicativo de função, como f, f_, fnc_ e similares, esse prefixo deve ser abandonado.

Exemplo: a função f_seq_req_almoxarifado corresponde à classe SeqReqAlmoxarifado.

No início da classe deve estar declarada a variável public int versao_systextilweb_f contendo o número da versão da função no Systêxtil 5, se existir.

Sempre que possível, a execução da função é feita através de um método public static chamado executar. O retorno desse método é o valor retornado pela função, exceto se corresponder apenas ao sucesso da execução, conforme explicado abaixo, e pode ser void.

Exemplo: a mesma função, retornando um número inteiro, será executada através do método public static int executar.

Os argumentos do método executar, em geral, são os mesmos argumentos da função em Vision, e geralmente não há necessidade de transcrever o nome dos argumentos para as convenções de nomenclatura Java (por exemplo f_cod_cliente para codCliente). Mas há as seguintes ressalvas, que são muito comuns:

  • Se a função fizer acesso ao banco de dados, o primeiro argumento deve ser AppConnection conn.
  • Em seguida, se a função fizer acesso a variáveis da mdi, o próximo argumento deve ser Mdi mdi.
  • Em seguida, se a função manusear mensagens traduzidas, exceto para mensagens de erro, o próximo argumento deve ser UtilStr utilStr.
  • Em seguida, se a função fizer interação com o usuário para, por exemplo, exibir mensagens ou fazer perguntas, exceto para mensagens de erro, o próximo argumento deve ser TagInteractive tagInteractive.
  • Em seguida, se a função utilizar o nome do programa que a chamou, o próximo argumento deve ser String form_name.
  • Argumentos que servem para receber valores de retorno da função em Vision não devem ser passados como argumentos em Java. Os valores de retorno devem ser retornados (sic) na execução do próprio método, ou, se isso não for possível, através da técnica descrita abaixo.

Quando a função é convertida, as instruções para seu uso devem ser preenchidas no sistema de controle de conversões. Preferentemente, os detalhes principais devem estar no javadoc da própria classe. Assim, bastará registrar o nome da classe associada à função, e a instrução para consultar o javadoc da mesma. É claro, deve-se publicar a atualização do javadoc assim que possível.

Controle do sucesso da execução e mensagens de erro

Não é boa prática, em Java, utilizar variáveis de retorno que recebam, por exemplo, false, "N", 0 indicando que houve erro na execução do método. Erros de execução são notificados mediante o lançamento de Exceptions. No caso destas funções, isto é feito assim:

  • Mensagens informando ao usuário que determinada regra não foi atendida para a conclusão do processo são notificadas através do lançamento de uma TagException. A aplicação que chamou o método é responsável por capturá-la, traduzi-la e apresentá-la ao usuário. O framework preparado para o Systêxtil Web já possui mecanismos automatizados para isso, em especial na validação de campos de texto.
  • Mensagens informando que determinado comando SQL não obteve sucesso já são lançadas automaticamente pela AppConnection na forma de DebugException. A aplicação é responsável por tratá-la e exibi-la da maneira mais adequada.

Execução de comandos SQL

Cuidar para que todos os comandos SQL sejam fechados após a conclusão da execução. Em especial, cuidar para que após cada .executeUpdate() haja um .close() correspondente. Todos os while(conn1.next()) também devem ter o .close() correspondente ao fim do loop.

Para que os erros de execução sejam apresentados de forma satisfatória, todos os try-catch utilizados no Vision simplesmente para capturar a ocorrência de erros de SQL e apresentá-los ao usuário devem ser removidos em Java. Os que forem utilizados para verificar a violação de uma regra e aplicar um procedimento alternativo - ou simplesmente ignorar o problema - devem ter um bloco try-catch apropriado para isso, geralmente tratando uma RuleViolation (geralmente UniqueViolation, que corresponde ao código de erro -4) que ocorre na execução de um método AppConnection.executeCheckedUpdate(). Por exemplo: 

   // Configurar o comando e atribuir os parâmetros, geralmente um INSERT
    try {
        conn1.executeCheckedUpdate();
    } catch(UniqueViolation uv) { // Corresponde a status = -4
        // Executar um comando UPDATE na mesma tabela
    } catch(RuleViolation rv) {   // Qualquer outra violação de regras
        conn1.closeAndThrow(rv);  // Lançar DebugException
    } conn1.close();

As funções nunca devem executar commit ou rollback. Funções fazem parte de um contexto transacional, e portanto não podem gerenciar a própria transação. Se a função em Vision executar commit ou rollback, isso deve ficar documentado na função em Java, e o processo que chamou a função é responsável por controlar o momento em que o commit ou rollback deve ocorrer.

Funções que retornam mais de um valor

Um método estático não é capaz de retornar mais de um valor. Quando houver necessidade disso, a função se tornará a execução de um objeto cujos argumentos são recebidos no construtor, e cujos valores de retorno são propriedades constantes (public final) desse objeto. Todos os demais padrões deste documento continuam aplicáveis nesta situação.

Se for conveniente, esse objeto pode ser obtido indiretamente mediante um método estático, em vez de diretamente usando o construtor.

Conferir por exemplo NaturOperEmpresa

Evolução e compatibilidade reversa

Se for necessário alterar a assinatura do método de uma função, p. ex. através da adição de um argumento, é preciso preservar a assinatura do método original para não comprometer a compatibilidade reversa. Para isso, sobrecarrega-se o método original com a nova assinatura contendo a lógica completa e correta, e altera-se o método com a assinatura antiga para que execute o novo método passando argumentos compatíveis com a situação antiga - para que não ocorra duplicação de código. O método com a assinatura antiga deve ser anotado como @deprecated e todas as ocorrências nos programas onde o mesmo é invocado devem ser atualizadas o quanto antes em momento oportuno.

Os padrões deste documento não estão aplicados uniformemente nas funções desta package, em especial nas funções que foram convertidas há mais tempo. Os padrões foram sendo aperfeiçoados à medida que se convertiam mais e mais funções. Portanto, não deve causar estranhamento se alguma função convertida não se enquadrar perfeitamente nestes padrões. Não obstante, eles devem ser seguidos sempre que possível nas próximas conversões.