wiki:WF/depreciacao

Version 5 (modified by viani, 9 years ago) (diff)

--

Depreciação (deprecation)

A depreciação de classes e métodos pode ocorrer quando eles são considerados em desuso (ou desatualizados) em um sistema, ou API.
A utilização desses ítens deve ser evitada pois se tornarão obsoletos em versões futuras e devem ser rotulados com a notação @deprecated.
Portanto, sistemas novos não devem os utilizar e sistemas antigos, que fazem uso dessas classes e métodos, devem ser modificados para que usem seus substitutos e, assim, continuem funcionando normalmente.

Existem várias razões para que uma funcionalidade caia em desuso, como por exemplo:

  • é insegura
  • possui um bug
  • é ineficiente
  • será removida em versões futuras
  • proporciona más práticas de programação

Detectada a necessidade de depreciar uma classe ou método, deve-se avisar os desenvolvedores e prover-lhes uma alternativa para que possam substituir o uso da funcionalidade depreciada em seus códigos.
Porém, cabe aos próprios desenvolvedores certificarem-se que o uso da opção sugerida é realmente adequada ao seu sistema e efetivarem a alteração necessária em tempo para que seus usuários não sejam prejudicados.

No Workflow

No módulo Workflow do Expresso, foi implementada uma função ( ver ticket #446) para alertar os desenvolvedores a respeito dos métodos depreciados. Ela deve ser chamada pelo método depreciado e, além de apresentar uma mensagem de warning na tela, também registra em arquivo de log quando esse método é utilizado. Essa mensagem pode sugerir a classe e método que devem ser usados como substitutos aos ítens depreciados.

Notando-se a necessidade de depreciação de uma classe ou método no Workflow, o procedimento a seguir deverá ser adotado:

  • desenvolver o novo ítem que substitua o depreciado
  • rotular o ítem depreciado com "@deprecated X.Y", onde X.Y é a versão dessa depreciação
  • adicionar a chamada da função "wf_warn_deprecated_method('classe', 'método')" na primeira linha do método depreciado, informando a classe e método substitutos, quando necessário
    • essa função mostra um alerta na tela (caso esteja habilitado) e registra em arquivo de log
  • monitorar log para verificar se há processos desatualizados
    • caso haja, entrar em contato com os desenvolvedores responsáveis comunicando a futura remoção das depreciações e solicitando a atualização do seu código
  • efetuar a remoção dos códigos depreciados depois de duas versões intermediárias
    • no caso de "@deprecated 1.1", por exemplo, a remoção ocorrerá na versão 1.3

Relação de Elementos Depreciados

Método depreciado Método substituto
wf_create_object Factory::getInstance
{objeto_camada_model}->getInstance Factory::getInstance
wf_engine->continueInstance wf_instance->continueInstance
wf_engine->abortInstance wf_instance->abort
wf_engine->setInstanceName wf_instance->setName
wf_engine->setInstancePriority wf_instance->setPriority
wf_engine->getIdleInstances wf_instance->getIdle
wf_engine->getInstances wf_instance->getIdle
wf_engine->getInstancesByName wf_instance->getByName
wf_engine->getChildInstances wf_instance->getChildren
wf_engine->getInstanceProperties wf_instance->getProperties
wf_engine->getChildInstanceProperties wf_instance->getProperties
wf_engine->getUserInstances wf_instance->getByUser
wf_engine->setInstanceProperty wf_instance->setProperty
wf_engine->checkUserAccessToInstance wf_instance->checkUserAccess
wf_instance->getAll wf_instance->getAllActive