Agendando tarefas com Spring e Quartz - Revista Easy Java Magazine 25

Frequentemente nos deparamos com a necessidade de desenvolver aplicações que necessitam executar tarefas em momentos específicos e pré-programados. Assim, a funcionalidade do agendamento de tarefas é muito útil para aproveitar horas de menor tráfego da rede, na geração de relatórios, na replicação de dados, na geração de dados para fechamento de períodos fiscais, na atualização de bases de dados, etc.

Assim, tendo em vista que essa necessidade precisava ser suprida, o projeto Quartz surgiu permitindo o controle de repetição e o agendamento de tarefas da aplicação.

O Spring Framework nos traz à mão diversas facilidades para integração e configuração de bibliotecas externas, permitindo assim a integração com as bibliotecas do Quartz. Dessa maneira, é possível cuidar do agendamento (scheduling) de métodos, seja em momentos específicos, seja em determinados intervalos de tempo, tudo isso configurado dentro de seus próprios parâmetros de configuração do framework e com a simplicidade já característica do Spring.

Neste artigo, vamos demonstrar uma solução para executar tarefas em nossa aplicação com data e hora específicas, ou simplesmente executar métodos repetidamente em intervalos de tempo pré-definidos. Este agendamento é facilmente coberto pelas bibliotecas do Quartz. A dúvida então é: como integrá-las a aplicações que já fazem uso do Spring Framework, aproveitando as facilidades da inversão de controle, injeção de dependências, controle transacional, entre outras, do Spring, e fazê-las funcionar concomitantemente? Vejamos uma solução para esta questão.

O Spring Framework

O Spring é um framework open source, modular, que facilita a criação de soluções elegantes e leves. Uma das suas principais características é a flexibilidade, o que permite a integração com outros frameworks (Nota do DevMan 1). Durante a codificação de uma aplicação utilizando-se Spring, podemos configurar e utilizar somente o que nos interessa ao projeto, evitando assim codificação desnecessária, ou seja, só se configura o que será utilizado.

Em sua concepção, o Spring possui o mínimo de dependências necessárias ao seu funcionamento, não exigindo outras bibliotecas para executar a maioria das suas funcionalidades básicas.

A utilização do Spring em sua aplicação facilita a utilização de transações declarativas, acesso remoto RMI ou Web Services, possui diversas opções para persistência de dados, além de auxiliar nos testes da aplicação, por exemplo, permitindo o desenvolvimento e teste isolados de cada componente da aplicação. Ademais, o Spring facilita a utilização de interfaces, o que aumenta a produtividade, qualidade do código e reusabilidade.

Graças a sua popularidade, o Spring tem sido abordado em fóruns e comunidades de desenvolvedores, o que torna relativamente fácil a tarefa de compartilhamento de informações. Como excelente fonte de consulta tem o fórum do Spring (ver seção Links), que pode oferecer uma base de referência e compartilhamento.

Segundo Craig Walls, criador da série de livros “Spring in Action”, podemos definir como suas principais funcionalidades a Inversão de Controle (IoC ou Inversion of Control), a Injeção de dependências (DI) e a Programação Orientada a Aspectos (AOP), quando usamos o Spring juntamente com as bibliotecas do AspectJ, por exemplo.

Estes itens auxiliam na implementação do projeto, garantindo a manutenção do baixo acoplamento entre as classes, evitam a replicação de código, favorecem as boas práticas de programação e arquitetura, etc.

É disponibilizada ainda toda uma tool suite própria para desenvolvimento, o SpringSource Tool Suite, um ambiente de desenvolvimento baseado na renomada IDE Eclipse e que já inclui suporte ao Spring 3.1.

Hoje, o Spring Framework permite que trabalhemos com todas as suas configurações e parametrizações declaradas em um arquivo XML, além das conhecidas Annotations inseridas dentro do próprio escopo da classe e/ou nas declarações de objetos.

A grande vantagem de se reunir todas as configurações do framework em um único lugar é a facilidade de futuras alterações e implementações, sem a necessidade de se refatorar grande parte do código, facilitando assim a manutenção do sistema e diminuindo o tempo de retrabalho.

Inclusive, a grande flexibilidade do Spring permite aplicá-lo em diversas modalidades de aplicações Java, de diversos portes e ambientes, sejam elas desktop (Swing), console (linha de comando), web, entre outras, justificando assim sua flexibilidade.

Spring Framework e o Quartz

Frequentemente nos deparamos com especificações de aplicações que necessitam realizar tarefas de forma agendada, sejam para geração de relatórios, backups, ou simplesmente para tirar proveito de momentos com menor tráfego de rede para a execução de tarefas que demandem maior necessidade computacional.

O Spring Framework possui na sua API a possibilidade de integrá-lo às bibliotecas do Quartz, que ajudam o desenvolvedor a realizar tais agendamentos aproveitando ainda as funcionalidades do Spring, que facilitam todo o trabalho do desenvolvedor.

Este artigo será focado justamente nesta integração, e demonstrará como pode ser fácil realizá-la e configurá-la dentro do Spring.

Antes de iniciarmos a codificação, devemos nos atentar ao fato de o Spring 3 não suportar a API mais recente do Quartz, a versão 2, e justamente numa das classes que usaremos neste artigo, a CronTrigger, que no Quartz 2 é uma interface, a implementação do Spring a trata como classe (CronTriggerBean extends CronTrigger). Assim sendo, sua utilização poderá gerar erros (mais detalhes na seção Links), motivo pelo qual empregaremos no exemplo deste artigo a versão 1.8.6 do Quartz. Quanto ao Spring Framework, utilizaremos a versão 3.2.1, a mais recente no momento em que este artigo foi escrito.

Para a implementação deste exemplo, foi escolhido o Eclipse Juno como IDE juntamente com o JDK 1.7. Assim, partiremos da premissa que o desenvolvedor já esteja familiarizado com esta IDE.

Neste artigo, será construída uma aplicação rodando em console que faz uso do Spring 3 integrado ao Quartz 1.8.6. Serão escritos dois métodos nesta aplicação, um deles com uma tarefa a ser executada em intervalos de tempo definidos, e o segundo com uma tarefa a ser executada em uma data específica.

Para executarmos as tarefas com o Quartz 1.8.6 em sua API, necessitamos que seja importada a biblioteca Apache Commons Logging. Para geração de log, utilizaremos neste artigo a versão 1.1.1 dessa biblioteca.

Com as bibliotecas devidamente baixadas, adicione-as ao classpath do projeto:

· Apache Commons Logging: commons-logging-api-1.1.1.jar, do log4j-1.2.14.jar;

· Quartz: quartz-all-1.8.6.jar, slf4j-api-1.6.0.jar, slf4j-log4j12-1.6.0.jar, spring-aop-3.2.0.M1.jar;

· Spring: spring-asm-3.2.0.M1.jar, spring-aspects-3.2.0.M1.jar, spring-beans-3.2.0.M1.jar, spring-context-3.2.0.M1.jar, spring-context-support-3.2.0.M1.jar, spring-core-3.2.0.M1.jar, spring-expression-3.2.0.M1.jar, spring-tx-3.2.0.M1.jar.

Criando o applicationContext.xml

Toda configuração de funcionamento do Spring é definida no arquivo applicationContext.xml, e é nele também que parametrizaremos as configurações do Quartz, integrando-o ao Spring.

Este arquivo deve ser criado em alguma pasta do projeto que possa ser facilmente visto num momento posterior e chamado pelas classes que instanciarão o contexto do Spring Framework. Para facilitar, criamos o arquivo applicationContext.xml no próprio diretório src da aplicação. Neste momento, já foram criados também os pacotes, representando as camadas da aplicação: um pacote controller, que conterá as classes com os métodos que serão acionados pelo Quartz; e o pacote view, que terá a classe Principal com o método main(), o ‘executável’ do programa.

A estrutura inicial da aplicação é demonstrada na Figura 1.

Figura 1. Estrutura de pacotes da aplicação, já com o arquivo applicationContext.xml e a pasta lib contendo as bibliotecas.

Escrevendo o conteúdo do applicationContext.xml

Como item básico deste arquivo, deve-se definir o cabeçalho conforme demonstrado na Listagem 1. É no cabeçalho do arquivo de configuração que são declarados quais namespaces de funcionalidades específicas do framework serão utilizados. Dependendo da necessidade, podem ser adicionados outros pacotes.

Listagem 1. Parâmetros básicos de configuração do arquivo applicationContext.xml.

<?xml version="1.0" encoding="windows-1252"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/
       XMLSchema-instance"   
       xsi:schemaLocation="http://www.springframework.org/
       schema/beans 
       http://www.springframework.org/schema/beans/
       spring-beans-3.2.xsd">  

<!-- *** inserir código aqui *** -->

</beans>

Escrevendo classes

Para verificar a importação correta das bibliotecas do Spring e garantir que tudo esteja funcionando normalmente, no pacote br.com.javamagazine.view criaremos a classe Principal, contendo o método main(), cujo conteúdo é mostrado na Listagem 2.

Listagem 2. Classe Principal e método main()

package br.com.javamagazine.view;

import org.springframework.context.ApplicationContext;
import org.springframework.context.support.
ClassPathXmlApplicationContext;

public class Principal {

	public static void main(String[] args) {

		ApplicationContext context = 
               new ClassPathXmlApplicationContext
              ("applicationContext.xml");
	}
}

Ao executar a aplicação podem ser visualizados alguns avisos de inicialização do framework alertando que alguns parâmetros para o Log4J não foram definidos. Para a abordagem somente explicativa deste artigo tais implementações não se fazem necessárias e estes avisos devem ser desconsiderados. Se tudo foi configurado corretamente, não serão lançadas exceções, como demonstra a Figura 2.

Figura 2. Saída do console, mostrando a execução sem exceções da aplicação, com o Spring já integrado.

Criaremos agora a classe que deverá conter os métodos a serem executados pelo Quartz, a qual denominaremos ControladorQuartz dentro do pacote br.com.javamagazine.controller e que pode ser contemplada na Listagem 3.

Dentro desta classe é criado o método que será chamado e executado nas iterações do Quartz. Para ilustrar, exibiremos na saída do console a data atual do sistema através do método System.out.println().

Listagem 3. Classe ControladorQuartz com método a ser executados pelo Quartz.

package br.com.javamagazine.controller;

import java.sql.Date;
import java.text.SimpleDateFormat;

public class ControladorQuartz {

	public void metodoQuartz() {

		System.out.println("Executando Quartz em: "
		  + new SimpleDateFormat("dd/MM/yyyy HH:mm:ss").
                 format(new Date(
		 (System.currentTimeMillis()))));

	}
}

Integrando o Quartz ao contexto do Spring Framework

A partir de agora começaremos a escrever o nosso arquivo de configuração applicationContext.xml. Nele serão adicionadas instruções que mostrarão ao Spring quais classes contêm os métodos que devem ser executados pelo Quartz e a forma com que serão feitas as chamadas a eles.

A seguir, temos a primeira linha que deve ser inserida no arquivo, substituindo o texto comentado. Com isso, estamos criando um bean, ou seja, a instância de um objeto da classe ControladorQuartz. Observe que deve ser passado o fully qualified name da classe, isto é, deve-se colocar o nome da classe precedido do pacote que a contém.

O próximo passo será configurar o job que o Quartz executará e que deve estar contido na classe apontada anteriormente. Para tal, devemos acrescentar o código da Listagem 4.

Listagem 4. Configuração do Job para o Quartz.

<bean id="meuJob" class="org.springframework.scheduling.
quartz.MethodInvokingJobDetailFactoryBean">
        <property name="targetObject" 
         ref="minhaClasseQuartz"/>
        <property name="targetMethod" 
         value="metodoQuartz"/>
</bean>

Ao bean criado foi dado o nome de meuJob, por meio de MethodInvokingJobDetailFactoryBean, a partir do qual é definido o método da classe que será controlada pelo Quarts e que permite evocar este método.

A tarefa do MethodInvokingJobDetailFactoryBean é justamente fazer esta ligação entre o método e a classe que o contém e que o Quartz deve gerenciar. No nosso caso, chamaremos o método metodoQuartz().

Na propriedade targetObject colocamos uma referência ao bean minhaClasseQuartz, criado anteriormente, e na propriedade targetMethod, referenciamos o método que é contido por esta classe e que deverá ser executado pelo Quartz, ou seja, o metodoQuartz().

Configurando uma SimpleTrigger

Com os métodos devidamente configurados, devemos implementar a maneira como eles serão chamados. Para este primeiro exemplo, faremos com que o método seja executado em intervalos de tempo pré-definidos. Para isso, criaremos um objeto SimpleTriggerBean, que é uma subclasse de Trigger configurada conforme demonstra a Listagem 5, e funciona como se fosse um “gatilho”, que irá disparar a execução do método, além de estabelecer o intervalo de tempo em que a execução deve ser iniciada.

Listagem 5. Parâmetros da SimpleTrigger.

<bean id="minhaTrigger" class="org.springframework.
scheduling.quartz.SimpleTriggerBean">
        <property name="jobDetail" ref="meuJob"/>
        <property name="startDelay" value="2000"/>	
        <property name="repeatInterval" value="5000"/>
</bean>

Na propriedade jobDetail foi referenciado o bean meuJob, que como pode ser visto na Listagem 4, possui a propriedade targetObject apontando para o bean minhaClasseQuartz (que representa a classe ControladorQuartz criada anteriormente) e a propriedade targetMethod apontando para o método a ser executado deste bean, o metodoQuartz().

A propriedade startDelay determina quanto tempo o Quartz deve esperar para iniciar a execução deste gatilho a partir do momento em que o Spring for instanciado, ou seja, quanto tempo o Quartz deve aguardar para executar o método pela primeira vez. Os valores destas propriedades correspondem a intervalos de tempo e são informados em milissegundos. Neste caso estabelecemos 2 segundos (2000ms).

Por fim, na propriedade repeatInterval é passado o intervalo de repetição da trigger; na ocasião, 5 segundos (5000ms) .

Configurando o scheduler

Feito isso é necessário criar o scheduler, ou “agendador”, propriamente dito. Isto é realizado por meio do objeto SchedulerFactoryBean, que neste caso recebe uma lista de triggers que o Quartz deve executar.

Na Listagem 6, pode ser visualizado o código do SchedulerFactoryBean, já com a trigger minhaTrigger dentro da lista de execução. O SchedulerFactoryBean é responsável por registrar os objetos (por exemplo, beans como JobDetail, Calendar e Trigger) com os métodos que o Quartz deve executar.

Listagem 6. Configuração do SchedulerFactoryBean, com a lista de triggers a ser executada

<bean class="org.springframework.scheduling.quartz.
SchedulerFactoryBean">      
       <!-- Lista de triggers que devem ser executadas-->
        <property name="triggers">
            <list>
                <ref bean="minhaTrigger"/>
            </list>
        </property>
    </bean>

Pronto! A aplicação já está configurada e poderá ser executada. A Figura 3 mostra a saída no console da IDE.

Figura 3. Saída no console da aplicação executada.

Adicionando mais funcionalidades – criando e configurando uma CronTrigger

Foi demonstrada até agora apenas uma das facetas do Quartz integrado ao Spring, que permite somente que o método seja executado em intervalos fixos de tempo.

No entanto, frequentemente precisamos “agendar”, no sentido mais exato da palavra, tarefas a serem executadas em datas ou horas específicas, como processos de backup, instruções de replicação de dados, entre outros. Tais atividades eventualmente precisam ser executadas na madrugada, quando o tráfego de rede é menor, ou em datas de fechamentos contábeis, por exemplo.

Para configurar métodos para execução em um horário/data específico, utilizaremos outra subclasse de Trigger, a CronTriggerBean.

Criaremos então mais um método na classe ControladorQuartz que será executado pela CronTrigger. A Listagem 7 mostra o código desse método, que chamamos de metodoCron().

Listagem 7. Método metodoCron() adicionado na classe ControladorQuartz.

public void metodoCron() {	

  System.out.println("\n********************* 
  TAREFA AGENDADA EXECUTADA EM: "
    + new SimpleDateFormat("dd/MM/yyyy HH:mm:ss")
       .format(new    Date((System.currentTimeMillis())))
       + "********************* \n");
}

Podemos configurar a CronTrigger de forma muito semelhante à SimpleTrigger. Precisamos para isto transformar o metodoCron() em um Job do Quartz. Para tal, adicione o código da Listagem 8 ao applicationContext.xml, logo após a definição de meuJob feita anteriormente. Note que como este método também está na classe QuartzController e esta já foi declarada anteriormente, somente precisamos criar mais um MethodInvokingJobDetailFactoryBean e nele declarar o metodoCron().

Listagem 8. Criação do Job apontando para o metodoCron().

<bean id="meuJobCron" class="org.springframework.scheduling.quartz
       .MethodInvokingJobDetailFactoryBean">
        <property name="targetObject" ref="minhaClasseQuartz"/>
        <property name="targetMethod" value="metodoCron"/>
</bean>

Agora é preciso inserir as propriedades do CronTriggerBean. Este bean tem como característica permitir que especifiquemos, com detalhes, qual o momento que determinado método deve ser executado, ou seja, ele representa um bean “agendável”.

O CronTriggerBean é configurado a partir do uso da sintaxe cronExpression, oriunda da plataforma Unix. Ele recebe como propriedade uma String com os dados posicionados em um padrão definido, com o objetivo de parametrizar os dados que definem o momento da execução. Na seção Links temos instruções de como funciona esta sintaxe.

A Listagem 9 mostra a configuração do CronTriggerBean que deve ser inserida após a configuração da minhaTrigger, no próprio applicationContext.xml. O CronTriggerBean recebe em sua lista de propriedades a cronExpression já definida.

Listagem 9. Criação do CronTriggerBean.

<bean id="cronTrigger"
          class="org.springframework.scheduling.
         quartz.CronTriggerBean"> 
        <property name="jobDetail" ref="meuJobCron" />       
        
        <!-- EXPRESSÃO CRON -->        
        <property name="cronExpression" 
         value="0 43 9 ? 8 FRI" />        
</bean>

Pode-se verificar a propriedade cronExpression com a sintaxe do cron. Com esta linha, configuramos para que este job seja executado aos “0 segundo, 43 minutos, 9 horas, qualquer dia do mês (?) de agosto (8), às sextas-feiras”.

Para testar, configure a cronExpression para uma data/hora próxima do momento atual, o que permitirá a verificação do correto funcionamento desta propriedade, evitando assim perda de tempo ao aguardar a sua execução.

Depois de configurado o CronTriggerBean, que chamamos de cronTrigger, deve-se colocá-lo na lista de execução das triggers do Quartz. Para tanto, é necessário apenas adicionar a linha abaixo à lista do SchedulerFactoryBean, que já havia sido criado anteriormente e somente continha referência à minhaTrigger:

<ref bean="cronTrigger" />

Feito isto, a configuração do SchedulerFactoryBean deve se parecer com o código apresentado na Listagem 10.

Listagem 10. Código de configuração do SchedulerFactoryBean.

<bean class="org.springframework.scheduling.
quartz.SchedulerFactoryBean">      
       <!-- Lista de triggers que devem ser executadas-->
        <property name="triggers">
            <list>
                <ref bean="cronTrigger" />
                <ref bean="minhaTrigger"/>
            </list>
        </property>
</bean>

Concluindo, o applicationContext.xml é demonstrado por completo na Listagem11.

Listagem 11. Código completo do arquivo applicationContext.xml.

<?xml version="1.0" encoding="windows-1252"?>

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/
       schema/beans 
       http://www.springframework.org/schema/beans/
       spring-beans-3.2.xsd">    

<!-- Definição da classe que irá conter os métodos do Quartz -->
    <bean id="minhaClasseQuartz" class="br.com.
     javamagazine.controller.ControladorQuartz"/>

<!-- Método que será executado pela trigger--> 
    <bean id="meuJob" class="org.springframework.scheduling.
     quartz.MethodInvokingJobDetailFactoryBean">
        <property name="targetObject" ref="minhaClasseQuartz"/>
        <property name="targetMethod" value="metodoQuartz"/>
    </bean>

<!-- Método que será executado pelo scheduler -->
    <bean id="meuJobCron" class="org.springframework.
    scheduling.quartz.MethodInvoking
    JobDetailFactoryBean">
        <property name="targetObject" ref="minhaClasseQuartz"/>
        <property name="targetMethod" value="metodoCron"/>
    </bean>

<!-- Configurações da execução de minhaTrigger -->
    <bean id="minhaTrigger" class="org.springframework.
     scheduling.quartz.SimpleTriggerBean">
        <property name="jobDetail" ref="meuJob"/>
        <property name="startDelay" value="2000"/>	
        <property name="repeatInterval" value="5000"/>
    </bean>

<!-- Cron Trigger-->
    <bean id="cronTrigger"
          class="org.springframework.scheduling.quartz.
          CronTriggerBean"> 
        <property name="jobDetail" ref="meuJobCron" />       
        
        <!-- EXPRESSÃO CRON -->        
        <property name="cronExpression" value="0 30 10 ? 8 MON" />
   </bean>

    <bean class="org.springframework.scheduling.
     quartz.SchedulerFactoryBean">      
       <!-- Lista de triggers que devem ser executadas-->
        <property name="triggers">
            <list>
                <ref bean="cronTrigger" />
                <ref bean="minhaTrigger"/>
            </list>
        </property>
    </bean>
</beans>

Com a aplicação configurada corretamente, podemos enfim executá-la. A Figura 4 demonstra a saída que deverá aparecer.

Figura 4. Saída no console da aplicação executada.

Ao analisar o funcionamento da aplicação, verificamos que: o método agendado metodoQuartz() é chamado por minhaTrigger de 5 em 5 segundos, imprimindo na tela a data e o horário em que foi executado. Depois, o Quartz instancia cronTrigger, que executa o método agendado metodoCron() justamente às 09:43 do dia 17/08/2012, uma sexta-feira, conforme configurado.

Conclusão

O Spring Framework, sem sombra de dúvidas, é uma poderosa ferramenta à disposição dos desenvolvedores Java. Porém, neste artigo, demonstramos apenas uma das suas inúmeras capacidades.

Durante o desenvolvimento de sistemas, a necessidade de agendamento de tarefas pode se tornar um importante requisito. Neste cenário, o Spring permite a integração com o Quartz, nos auxiliando nesta tarefa, além de permitir configurá-lo de forma relativamente fácil e robusta, via arquivo de configuração, o que torna o código mais limpo. Este resultado pode ser observado no decorrer do exemplo implementado.

Enfim, esperamos que o leitor efetue a integração do Spring com o Quartz, e também se interesse em realizar exercícios, não só desta como de outras funcionalidades bastante interessantes do framework, como Inversão de Controle, AOP e gerenciamento de transações de banco de dados, buscando consolidar o conhecimento adquirido.