1. O Application Framework do ColdFusion
Em se tratando de programação em geral, Application Framework é o termo geralmente utilizado para se referir à um conjunto de scripts, classes ou bibliotecas de códigos, usadas para a construção de uma aplicação estruturada.
No desenvolvimento ColdFusion, o Application Framework, é firmado sob três componentes:
- Consolidação de ações/variáveis comuns à uma aplicação.
- Gerenciamento do estado da aplicação
- Serviços de tratamento de erros
2. O Application Framework antes do CFMX 7
A instalação de tais componentes no contexto de uma determinada aplicação nas versões pré CFMX 7, é possível através de dois arquivos especiais: o Application.cfm e o OnRequestEnd.cfm. Ambos arquivos possuem comportamento muito semelhante à uma ação de inclusão com a tag CFINCLUDE. Sendo assim, todas as ações/variáveis setadas nesses arquivos são comuns, no tocante à serem executadas antes (Application.cfm) e depois (OnRequestEnd.cfm) de qualquer requisição numa aplicação. Um exemplo bastante simples disso seria a criação de uma variável contendo o nome do datasource que se faria necessário em qualquer interação com o banco de dados.
Neste cenário de desenvolvimento, o Application Framework é orientado à requisições, isto é, à cada chamada de uma página .cfm.
3. O Application Framework após o CFMX 7
A partir da versão 7, o ColdFusion MX implementou um novo conceito ao seu Application Framework, através da utilização do arquivo Application.cfc. Com este arquivo - que tem como intenção substituir os já conhecidos Application.cfm e OnRequestEnd.cfm - é possível se trabalhar com métodos de eventos.
Basicamente o arquivo Application.cfc é um ColdFusion component, que possui uma relação de métodos especiais, que seguem determinadas convenções, no tocante ao seu nome, tipo de retorno, etc. Estes por sua vez, são considerados métodos de evento, por somente executarem o código neles definido, em resposta à determinados eventos que ocorrem na aplicação. Como se pode ver, a partir de então, o Application Framework não é mais é orientado à requisições, e sim à eventos.
4. Os métodos/eventos do Application.cfc
Vamos a partir de agora, analisar cada um desses métodos bem como sua aplicação. Na explicação de utilização de cada método, procurei me ater apenas aos detalhes de implementação dos mesmos: no livedocs, existe um exemplo completo da criação de um Application.cfc, que considero suficiente para melhor compreensão deste artigo:
4.1 - onApplicationStart
Este método é executado, quando a aplicação é iniciada; isto geralmente ocorre, quando da primeira chamada do usuário feita à uma página .cfm dentro da aplicação.
Seu tipo de retorno sempre será booleano: verdadeiro, se o código que contém no método for executado sem problemas, e false caso contrário, quando por exemplo algum erro ocorrer durante a chamada do template.
Neste caso o CF irá processar novamente o método, até que seu retorno seja verdadeiro; uma vez processado com sucesso, numa próxima requisição este método é ignorado. Caso você não especifique o atributo returntype, não se faz necessário especificar a tag cfreturn.
4.2 - onApplicationEnd
Como o próprio nome diz, este método é executado ao finalizar uma determinada aplicação. Entende-se como finalizada toda e qualquer aplicação que sofre time-out, tomando como base o valor que é especificado no próprio Application.cfc através do atributo applicationTimeout, ou ainda no CF Administrator.
Por não possui retorno, o returntype do método é void; este método requer um argumento chamado ApplicationScope (uma estrutura de variáveis que possui informações sobre a aplicação iniciada).
Para acessar variáveis do scopo application, se faz necessário a declaração do argumento ApplicationScope; para melhor exemplificar, imagine uma variável application.dsn que foi criada no método onApplicationStart. Se por qualquer motivo você desejar fazer chamada do valor dessa variável neste método, a forma correta não será #application.dsn#; e sim: #Arguments.ApplicationScope.dsn#
4.3 - onError
De forma diferente das tags CFERROR e CFTRY/CFCATCH, este método serve para monitorar e capturar qualquer tipo de erro que ocorrer durante o uso da aplicação. A única exceção de atuação deste método fica por conta da existência de blocos CFTRY/CFCATCH.
O tipo de retorno desse método é void.
Este método requer dois argumentos: Exception e EventName. O primeiro, é uma estrutura de variáveis que possuem informações inerentes à exceção lançada: é idêntica à estrutura do CFCATCH; enquanto que o outro, possui o nome do evento de onde foi gerada a exceção. No caso de erros que ocorrerem em métodos que não forem implementados no Application.cfc, esse argumento estará vazio.
4.4 - onRequestStart
Este método é executado antes de cada reuisição: se assemelha muito à forma como o Application.cfm é utilizado. Por conta disso, a utilização dele é indicada na definição de constantes comuns à aplicação e na autenticação de usuários, por exemplo através da tag CFLOGIN.
O tipo de retorno desse método é booleano: false no caso de algum erro durante à execução deste método e true, nos demais casos. Caso você não especifique o atributo returntype, não é necessário especificar o cfreturn.
4.5 - onRequest
Este método é chamado, logo após o método onRequestStart: ele possui um scopo de tratamento das requisições feitas à aplicação: seja a modificação de alguma informação, redirecionamento para outro template, etc. Caso ele seja implementado, deve-se especificar o argumento targetPage - que possui o path (relativo ao web root) do template requisitado; isto porque, o valor deste argumento será utilizado em uma tag CFINCLUDE que o mesmo deve também implementar.
O tipo de retorno desse método é void.
O único alerta fica por conta da implementação desse método em projetos ou sistemas que envolvam à criação de webservices, flash remoting e à chamadas de event gateways, pois da mesma forma como a chamada dele é feito antes de um template .cfm, este método será executado primeiramente, antes da chamada desses componentes.
4.6 - onRequestEnd
De forma semelhante ao método onRequestStart, ele é executado ao final de cada requisição, logo após à chamada do método onRequest quando implementado. Possui o mesmo caráter de utilização do arquivo onRequestEnd.cfm. Um bom exemplo de uso desse método é a definição de um footer que deve ser mostrado ao final de cada página.
O tipo de retorno desse método é void e ele requer um argumento targetPage.
4.6 - onSessionStart
É executado ao início da sessão de um usuário e tão somente na utilização de variáveis do scopo session.
O tipo de retorno desse método é void.
Para sistemas que implementam a autenticação de usuários, com a tag CFLOGIN, para que este método seja executado durante essas autenticações, recomendo a alteração do valor da variável loginStorage para o scopo session, no início do seu Application.cfc
4.7 - onSessionEnd
Semelhante ao método anterior, com exceção de ser executado apenas ao time-out da sessão do usuário ou numa ação explícita de logout feita pelo mesmo.
O tipo de retorno desse método é void.
Dos argumentos que este método implementa: SessionScope (possui informações sobre a sessão) e ApplicationScope (possui informações sobre a aplicação), apenas o primeiro é obrigatório.
De forma parecida com o scopo Application, neste método, você não pode acessar informações diretamente do scopo session, e sim, através do argumento passado pelo CF.
*** Vale lembrar ainda, que além dos métodos de eventos descritos neste artigo, pode-se especificar também métodos personalizados para sua aplicação. Uma vez você implementando o método OnRequest, os mesmos estarão disponíveis em toda e qualquer parte da aplicação; caso contrário, estes, apenas estarão disponíveis aos métodos do CFC.
Para finalizar, aos desenvolvedores acostumados no desenvolvimento com o arquivo Application.cfm, no livedocs, existe uma referência capaz de confrontar os pontos de semelhança entre estes dois arquivos: uma documentação muito útil para os que querem já implementar a utilização desse arquivo em suas aplicações: Migrating from Application.cfm to Application.cfc
NOTA: Este artigo contém referências ao site de documentação do ColdFusion.
Todos os dreito em relação à documentação oficial são reservados.