Anda di halaman 1dari 14

GUIA PARA UTILIZAO DO FRAMEWORK QUARTZ

Outubro 2010

Sum r!o "# I$%orm&'(#) "o Do*um#$to


T!+o "o Do*um#$to, Referncia T-tu.o "o Do*um#$to, Guia para Utilizao do Framework Quartz E)t&"o "o Do*um#$to, Elaborado R#)+o$) /#!): Lucas Rafael de lmeida! "illian R# $edeiros % Re&isado por 'le&erson (udel! Fabio )*oda P&.&/r&)012&/#), Quartz R#)umo, +escrio de como confi*urar e utilizar o Quartz durante o desen&ol&imento de aplica,es -a&a# 34m#ro "# + 5!$&): ./ So%t6&r# ut!.!7&"o), 8#r)9o D&t& Mu"&$'&) .#0 012.02.0 'riao do documento#

SUM:RIO
1. QUARTZ..............................................................................................................................................................4 1.1 INTRODUO......................................................................................................................................................4 1.2 SOBRE O QUARTZ...............................................................................................................................................4 1.2.1 Jobs.........................................................................................................................................................4 1.2.2 Trigger....................................................................................................................................................4 1.2.3 Scheduler................................................................................................................................................4 2. CONFIGURAO.............................................................................................................................................5 2.1 CONFIGURANDO O QUARTZ NA APLICAO.............................................................................................................5 2.2 BIBLIOTECAS DO QUARTZ.....................................................................................................................................5 2.2.1 Download das bibliotecas......................................................................................................................5 2.2.2 Utilizao do a!en..............................................................................................................................5 2.3 CONFIGURANDO O ARQUIVO WEB.X L!................................................................................................................." 2.4 CONFIGURANDO O ARQUIVO DE PROPRIEDADES QUARTZ.PROPERTIES!.........................................................................# 2.4.2 "genda#ento e# $ase de Dados...........................................................................................................% 3. IMPLEMENTANDO O AGENDAMENTO COM O QUARTZ..................................................................10 3.1 CRIANDO O AGENDADOR DO SERVIO..................................................................................................................1$ 3.1.1 &assage# de &ar'#etros (ara o )*ecutor..........................................................................................11 3.1.2 "gendando #anual#ente.....................................................................................................................12 3.1.3 "gendando auto#atica#ente atra!+s de u# ,istener.........................................................................12 3.2 CRIANDO O EXECUTOR DO SERVIO....................................................................................................................13

1; QUARTZ
1;1 I$tro"u'9o
proposta deste documento 3 ser&ir como um *uia r4pido e simples no au56lio ao desen&ol&imento de Jobs de ser&ios! atra&3s da ferramenta Quartz! em aplica,es -a&a "eb#

1;2 Sobr# o Qu&rt7


7 Quartz 3 um framework Open Source 8ue propicia o a*endamento de Jobs de ser&ios em aplica,es -a&a! nas plataformas -a&a EE e -a&a )E9 permitindo 8ue se desen&ol&a aplica,es com a*endamentos por inter&alos de tempo! onde 3 poss6&el construir &4rios relacionamentos entre os elementos de sua estrutura b4sica: Jobs! Trigger e Scheduler#

1;2;1 <ob) )o as tarefas 8ue sero e5ecutadas pelo Quartz# e5ecuo est4 &inculada a uma determinada condio associada a este processo 8ue de&e ser satisfeita# : parte do c;di*o respons4&el por e5ecutar a tarefa propriamente dita do a*endamento#

1;2;2 Tr!55#r Trigger! ou *atil<o! est4 associado ao e&ento do disparo durante a e5ecuo de um processo# : parte do c;di*o respons4&el por determinar 8uando determinado Job de&er4 ser e5ecutado#

1;2;= S*2#"u.#r =amb3m con<ecido como Agendador de Tarefas! 3 respons4&el por realizar o

Guia para Utilizao do Framework Quartz % 'ELE> R

5 a*endamento das tarefas ou Jobs, como tamb3m &erificar 8uando determinado processo de&er4 ser e5ecutado pelo sistema#

2; 1O3FIGURAO
2;1 1o$%!5ur&$"o o Qu&rt7 $& A+.!*&'9o
'onfi*urar a aplicao para utilizar o Quartz no e5i*e muito trabal<o! sendo necess4rio apenas 8ue o pro?eto conten<a as bibliotecas (JARs) do Quartz! a adio de al*uns atributos dentro do ar8ui&o @web#5mlA! e a criao de um ar8ui&o de propriedades dentro do classpath da aplicao#

2;2 >!b.!ot#*&) "o Qu&rt7


>ara a utilizao do Quartz! 3 necess4rio 8ue as bibliotecas Bar8ui&os JARsC deste! faam parte do classpath do pro?eto# Do caso da aplicao ser um pro?eto 8ue utiliza o >lataforma >in<o! e 8ue ten<a sido criada a partir do E>ro?eto $6nimoE! essa preocupao 3 desnecess4ria para o desen&ol&edor! uma &ez 8ue tais ar8ui&os ?4 &m adicionados no pro?eto9 encontramFse no diret;rio:
context/WEB-NF/lib/

2;2;1 Do6$.o&" "&) b!b.!ot#*&) 'aso o pro?eto no ten<a sido criado a partir do E>ro?eto $6nimoE da >lataforma >in<o! as bibliotecas! 8ue de&em ser adicionadas no classpath do pro?eto! podem ser encontradas no site do Quartz! endereo:
www.quartz-scheduler.org/download

2;2;2 Ut!.!7&'9o "o M&/#$

'aso o pro?eto utilize o $a&en para *erenciar as bibliotecas! o desen&ol&edor!

Guia para Utilizao do Framework Quartz % 'ELE> R

" ao in&3s de adicionar os JARs no classpath do pro?eto! precisar4 informar ao $a&en 8ue o pro?eto ir4 utilizar o Quartz# >ara isto! basta adicionar no ar8ui&o de confi*urao do $a&en! localizado no pro?eto! no diret;rio raiz! pom.xml ! as dependncias necess4rias# >ara os pro?etos 8ue utilizam o Framework >in<o! no 3 necess4rio informar e5plicitamente as dependncias para o Quartz9 uma &ez 8ue este frame!or" ?4 o faz implicitamente# @pom.xml :
<dependencies> ... <dependenc > <group!d>"ra#ewor$</group!d> <arti"act!d>"ra#ewor$</arti"act!d> <%ersion>&.'.(</%ersion> </dependenc > ... </dependencies>

denominado

bai5o se*ue e5emplo de dependncia informada dentro do

>ara os pro?etos 8ue no fazem uso do Framework >in<o! 3 necess4rio informar as dependncias do Quartz dentro do pom.xml .

2;= 1o$%!5ur&$"o o &r?u!/o @web.xml


+entro do ar8ui&o !eb.xml , de&eFse adicionar al*umas tags para 8ue o ser&io do Quartz se?a iniciado e passe a &erificar os Jobs 8ue se encontram a*endados! a*uardando por e5ecuo# acrescentado:
<ser%let> <ser%let-na#e>)uartz!nitializer</ser%let-na#e> <*-- +pcional. ,ode-se adicionar quaisquer descri-.es --> <displa -na#e>)uartz !nitializer /er%let</displa -na#e> <ser%let-class> org.quartz.ee.ser%let.)uartz!nitializer/er%let </ser%let-class> <load-on-startup>(</load-on-startup> </ser%let>

bai5o se*ue o c;di*o #$% a ser

Guia para Utilizao do Framework Quartz % 'ELE> R

2;A 1o$%!5ur&$"o o &r?u!/o "# +ro+r!#"&"#) @quartz.properties


7 ar8ui&o de propriedades do Quartz c<amaFse @ &uart'.properties e de&e ficar no classpath da aplicao# >ara as aplica,es (eb 8ue se*uem a estrutura da >lataforma >in<o! o ar8ui&o de&e ficar no diret;rio:
src/#ain/resources >>> ,ara aplica-.es que utilizam a estrutura do 0a%en context/WEB-!NF/src >>> ,ara aplica-.es que no utilizam a estrutura do 0a%en

+entro deste ar8ui&o 3 poss6&el definir como ser4 o comportamento e a forma de e5ecuo dos ser&ios a*endados! como! por e5emplo: definir se os ser&ios a*endados estaro armazenados em mem;ria! em banco de dados! entre outros# bai5o se*ue um simples e5emplo deste ar8ui&o:
org.quartz.scheduler.instanceNa#e 1 No#e2a3plicacao)uartz/cheduler org.quartz.scheduler.instance!d 1 345+ org.quartz.scheduler.r#i.export 1 "alse org.quartz.thread,ool.class 1 org.quartz.si#pl./i#ple5hread,ool org.quartz.thread,ool.thread6ount 1 7 org.quartz.thread,ool.thread,riorit 1 ' org.quartz.8ob/tore.class 1 org.quartz.si#pl.930:ob/tore

)obre as descri,es utilizadas no e5emplo acima! se*ue uma bre&e descrio dos parGmetros 8ue foram informados:
>arGmetro
org.quartz.scheduler.instanceNa#e org.quartz.scheduler.instance!d

+escrio Dome dado ao scheduler# @Dome+a plicacaoQuartz)c<edulerA# Desse caso!

Halor 8ue indica o id do scheduler# Esse &alor de&e ser Inico e pode ser do tipo te5to# >odeFse utilizar o &alor A)TO para 8ue este &alor se?a *erado automaticamente# Jndica se o scheduler poder4 ser acessado &ia R$*# Quando false! indica 8ue o sc<eduler ser4 local# 'aso no conten<a este parGmetro! o &alor default ser4 false. Dome da implementao do thread+ool 8ue ser4 utilizada# Quantidade m45ima de threads simultGneas dispon6&eis no pool para e5ecutar os Jobs deste scheduler# Jndica a prioridade em 8ue o Job de )er&io ser4 e5ecutado# >ode &ariar entre prioridade m6nima B.C a prioridade m45imaB.0C# 7 &alor default 3 1# Jndica como ser4 armazenado os dados dos Jobs e das triggers# Utilizando org.&uart'.simpl.RA$JobStore , armazenar4 em mem;ria#

org.quartz.scheduler.r#i.export

org.quartz.thread,ool.class org.quartz.thread,ool.thread6ount org.quartz.thread,ool.thread,riorit

org.quartz.8ob/tore.class

Guia para Utilizao do Framework Quartz % 'ELE> R

% s confi*ura,es no &uart'.properties podem &ariar de acordo com as necessidades de cada aplicao9 como! por e5emplo: se determinada aplicao possuir poucos a*endamentos durante o dia e com inter&alos *randes! o &alor ideal para ser definido! na propriedade referente ao +ool de Threads ("org.quartz.threadPool.threadCount"), poderia ser . BumC# $aiores informa,es! refente ao ar8ui&o de confi*ura,es e seus parGmetros! podem ser encontradas no site: <ttp:22www#8uartzFsc<eduler#or*2.

2;A;1 A5#$"&m#$to #m M#mBr!&

Dos ambientes de Desenvolvimento e Homologa o 3 recomendado 8ue o a*endamento se?a armazenado em mem;ria! onde a propriedade
"org.quartz.!ob"tore.#lass"

de&er4 conter o &alor "org.quartz.simpl.$%&'ob"tore"# Desse

caso! a confi*urao do ar8ui&o de propriedades do Quartz ficar4 semel<ante ao e5emplo citado anteriormente9 podendo! uma propriedade ou outra! &ariar de acordo com as necessidades de cada aplicao#

2;A;2 A5#$"&m#$to #m >&)# "# D&"o) 7 a*endamento em (ase de +ados consiste em armazenar o controle de e5ecuo de -obs em um (anco de +ados9 e seu uso 3 recomendado para as aplica,es 8ue se encontram no ambiente de Produ o# propriedade
"org.quartz.!ob"tore.#lass"

l3m de informar na armazenar o

8ue

Quartz

de&er4

a*endamento em banco de dados B"org.quartz.impl.!db#!obstore.'ob"toreC&("), de&eFse confi*urar outras propriedades para 8ue funcione corretamente! como demonstrado abai5o:
org.quartz.scheduler.instanceNa#e 1 No#e2a3plicacao)uartz/cheduler org.quartz.scheduler.instance!d 1 345+ org.quartz.scheduler.r#i.export 1 "alse org.quartz.thread,ool.class 1 org.quartz.si#pl./i#ple5hread,ool org.quartz.thread,ool.thread6ount 1 7 org.quartz.thread,ool.thread,riorit 1 ; org.quartz.8ob/tore.class 1 org.quartz.i#pl.8dbc8obstore.:ob/tore605

Guia para Utilizao do Framework Quartz % 'ELE> R

&
org.quartz.8ob/tore.dri%er2elegate6lass 1 org.quartz.i#pl.8dbc8obstore.,ostgre/)<2elegate org.quartz.8ob/tore.table,re"ix 1 quartz.qrtz= org.quartz.8ob/tore.data/ource 1 # 2/ org.quartz.data/ource.# 2/.8ndi49< 1 8a%a>8dbc/)uartzNo#e2a3plicacao2/ org.quartz.8ob/tore.non0anaged5?2ata/ource 1 # 2/ org.quartz.8ob/tore.is6lustered 1 true

)e*ue abai5o discriminao dos parGmetros utilizados acima:


>arGmetro
org.quartz.scheduler.instanceNa#e org.quartz.scheduler.instance!d

+escrio Dome dado ao sc<eduler# @Dome+a plicacaoQuartz)c<edulerA# Desse caso!

Halor 8ue indica o id do scheduler# Esse &alor poder ser te5to e de&er ser Inico# >odeFse utilizar o &alor @ U=7A para 8ue este &alor se?a *erado automaticamente# 'aso a aplicao este?a em cluster ! e *uardando a*endamento em tabelas! de&eFse utilizar @ U=7A. Jndica se o scheduler poder4 ser acessado &ia R$*# Quando false! indica 8ue o sc<eduler ser4 local# 'aso no conten<a este parGmetro! o &alor default ser4 false. Dome da implementao do thread+ool 8ue ser4 utilizada# Quantidade m45ima de threads simultGneas dispon6&eis no pool para e5ecutar os Jobs deste scheduler# Jndica a prioridade em 8ue o Job de )er&io ser4 e5ecutado# >ode &ariar entre prioridade m6nima B.C a prioridade m45imaB.0C# 7 &alor default 3 1# Jndica como ser4 armazenado os dados dos Jobs e das triggers# Desse caso foi utilizado org.&uart'.impl.,dbc,obstore.JobStore-$T B'ontainer F$ana*ed =ransactionsC para indicar 8ue os dados sero armazenados em (anco de +ados# Jnforma 8ual o @dialetoA do (anco de +ados 8ue ser4 utilizado para armazenar os a*endamentos# Desse caso foi utilizado org.&uart'.impl.,dbc,obstore.+ostgreS.%/elegate para o )G(+ >ost*re)QL# 'ada )G(+ possui um @dialetoA distinto# Halor 8ue indica o prefi5o das tabelas do Quartz criadas no (anco de +ados# Dome do /ataSource propriedades BD7$E+)C# definido no ar8ui&o de

org.quartz.scheduler.r#i.export

org.quartz.thread,ool.class org.quartz.thread,ool.thread6ount org.quartz.thread,ool.thread,riorit

org.quartz.8ob/tore.class

org.quartz.8ob/tore.dri%er2elegate6lass

org.quartz.8ob/tore.table,re"ix +rg.quartz.8ob/tore.data/ource org.quartz.data/ource.N+0E2/.8ndi49< org.quartz.8ob/tore.non0anaged5?2ata/ou rce org.quartz.8ob/tore.is6lustered

J0/* )R% do /ataSource 8ue ser4 *erenciado pelo ser&idor de aplicao# Dome do /ataSource 8ue conter4 cone5o sem o uso do 'ontainerF$ana*ed =ransactions# 7 &alor desta propriedade de&e ser @trueA! se possuir &4rias instGncias do Quartz utilizando as mesmas tabelas no banco de dados# E caso se?a @trueA! de&e ser @ U=7A o &alor da propriedade org.&uart'.scheduler.instance*d .

>ara obter maiores informa,es sobre a parametrizao do ar8ui&o de confi*ura,es do Quartz 3 poss6&el encontr4Flas no site: <ttp:22www#8uartzF
Guia para Utilizao do Framework Quartz % 'ELE> R

1$ sc<eduler#or*2.

=; IMPLEME3TA3DO O AGE3DAME3TO 1OM O QUARTZ


=;1 1r!&$"o o A5#$"&"or "o S#r/!'o
codificao do a*endador de ser&io consiste em implementar numa classe o m3todo 8ue realizar4 o a*endamento de uma determinada tarefa! ficando assim! respons4&el por re*istrar 8uando determinada tarefa de&er4 ser e5ecutada# )ua construo 3 simples e pode ser &erificada no e5emplo abai5o:
... /** * Nome do servio que ser armazenado pelo Scheduler */ public static final String NOME_JOB = "NomeDoJo "! ... /** * "#$odo que realiza o a%endamen$o */ public static void a%endar&'( try ( // ) $endo uma ins$*ncia de a%endamen$o. Scheduler scheduler = S$dScheduler+ac$or,.getDefaultScheduler&'! // // // // // // if -eri.icando se a $are.a encon$ra/se a%endada0 para n1o re%is$r/la mais de uma vez. ) s.2 Nes$e e3emplo u$ilizou/se o %rupo Scheduler.D4+56789:;)6<. "as pode/se u$ilizar quaisquer ou$ros. 4s$e campo # a er$o0 do $ipo S$rin%0 e serve para associa1o dos =o s. &scheduler.%e$Jo De$ail&NOME_JOB0 Scheduler.DEFAULT_GROUP' == null' ( // // >riando um novo =o Jo De$ail =o De$ail = new Jo De$ail&NOME_JOB0 Scheduler.DEFAULT_GROUP0 43ecu$or5%endamen$o?uar$z.class'! // >riando 8ri%%er &usando >ron' associado ao Jo e Scheduler >ron8ri%%er $ri%%er = new >ron8ri%%er&NOME_JOB0 Scheduler.DEFAULT_GROUP'! // <arame$ros >ron&@ @ @ @ * *'2 Se%undos0 "inu$os0 Aora0 Dia do "Bs0 // "Bs0 Dia9da9Semana e 5no &opcional' $ri%%er.se$>ron43pression&"C C D @ * ")N"'! // 5%endado pra $odas as se%. / Dh // 5dicionando =o ao a%endador de servios. scheduler.scheduleJo &=o De$ail0 $ri%%er'! E E catch &43cep$ion e' ( log.error&")correu um erro ao a%endar F"G NOME_JOB G "H no ?uar$z."0 e'! E

...

Do e5emplo acima 3 demonstrado como obter uma instGncia do a*endador!


Guia para Utilizao do Framework Quartz % 'ELE> R

11 atra&3s de @"td"#heduler)a#tor*.getDe+ault"#heduler,) , e a criao de Job# +urante a criao de um Job, 3 informado: o nome desse Job! o nome de um *rupo Btarefas so or*anizadas em *ruposC e a classe 8ue ser4 respons4&el por e5ecutar a tarefa9 no e5emplo em 8uesto 3 a classe @ -xe#utor%gendamento.uartz , descrita posteriormente# 'omo nesse e5emplo no foi necess4rio or*anizar &4rias tarefas em diferentes *rupos! foi utilizada a constante @ "#heduler.D-)%/0(12$3/P , ?4 oferecida pelo Quartz# 7 conteIdo desta constante 3 a String: "D4+5678". 7utro detal<e 8ue 3 mostrado no e5emplo 3 o tipo de Trigger BdisparoC escol<ido para o e5emplo! neste caso o @ Cron(rigger 1 este 3 baseado no -ron e 3 recomendado para a maioria dos casos por no apresentar problemas 8uanto ao <or4rio de &ero# $as 3 poss6&el escol<er outros tipos de =ri**ers disponibilizados pelo Quartz9 como por e5emplo! o @"imple(rigger # >ara obter maiores informa,es sobre o uso do a*endamento e dos tipos de Triggers! 3 poss6&el atra&3s da documentao do Quartz! dispon6&el no site: http>//www.quartz-scheduler.org/.

=;1;1 P&))&5#m "# P&rCm#tro) +&r& o ED#*utor Em certos sistemas! pode <a&er a necessidade de se passar al*um parGmetro! durante o momento do a*endamento! e 8ue ser4 utilizado somente no momento da e5ecuo da tarefa a*endada# Destes casos 3 poss6&el acrescentar parGmetros atra&3s da instGncia do @'obDetail , no @'obData&ap ! como e5emplificado abai5o:
... // >riando um novo =o Jo De$ail =o De$ail = new Jo De$ail&NOME_JOB0 Scheduler.DEFAULT_GROUP0 43ecu$or5%endamen$o?uar$z.class'! // 5dicionando par*me$ro no =o =o De$ail.%e$Jo Da$a"ap&'.pu$&NOME_PARAMETRO0 ALOR_PARAMETRO'! ...

-4 no momento de e5ecuo da tarefa! para se obter o &alor informado durante o a*endamento! 3 preciso somente informar o nome do parGmetro! no

Guia para Utilizao do Framework Quartz % 'ELE> R

12 @'obData&ap, como demonstrado abai5o:

... // ) $endo par*me$ro in.ormado no Jo . Jo Da$a"ap da$a"ap = con$e3$.%e$Jo De$ail&'.%e$Jo Da$a"ap&'! S$rin% parame$roIn.ormado = &S$rin%' da$a"ap.%e$&NOME_PARAMETRO'! ...

=;1;2 A5#$"&$"o m&$u&.m#$t# 7 *endamento manual nada mais 3 do 8ue c<amar de al*um ponto do

sistema o m3todo da classe 8ue realiza o a*endamento das tarefas no Quartz# e5ecuo do a*endamento pode ser moti&ada por 8ual8uer ao 8ue resulte em a*endar uma tarefa para ser e5ecutada a posteriori # moti&ar a e5ecuo do a*endamento# e5ecuo de um determinado caso de uso ou uma ao em particular tomada pelo usu4rio podem

=;1;= A5#$"&$"o &utom&t!*&m#$t# &tr&/E) "# um 0istener Em determinadas aplica,es! o a*endamento de&e ocorrer desde o momento em 8ue ela ?4 se encontra em e5ecuo# >ara esta situao! 3 poss6&el resol&er criando um %istener e adicionando o c;di*o respons4&el pelo a*endamento dentro dele# bai5o temFse uma classe e5emplificando a criao de um %istener e a c<amada para o a*endamento:
... /** * >lasse Servle$ 7is$ener */ public class AgendadorServicoQuartz implements ServletContextListener { ... /** * "#$odo e3ecu$ado quando se inicia a aplica1o. */ public void con$e3$Ini$ialized&Servle$>on$e3$4ven$ even$' ( // >hama o e3ecu$or do a%endamen$o. age!dar&'!

Guia para Utilizao do Framework Quartz % 'ELE> R

13
E ... /** * "#$odo e3ecu$ado quando a aplica1o # .inalizada. */ public void con$e3$Des$ro,ed&Servle$>on$e3$4ven$ even$' ( try ( Scheduler scheduler = S$dScheduler+ac$or,.getDefaultScheduler&'! // ;emove o a%endamen$o. scheduler.removeJo 7is$ener&NOME_JOB'!

E catch &43cep$ion e' ( log.error&")correu um erro ao remover a%endamen$o do ?uar$z."0 e'! E

... E

>ara 8ue este %istener funcione! 3 necess4rio adicionar! no ar8ui&o !eb.xml, o nome da classe 8ue o implementa! como &isto abai5o:
...
<listener> <listener-class>go%.pr.celepar.exe#plo=quartz.3gendador/er%ico)uartz</listener-class> </listener>

...

=;2 1r!&$"o o ED#*utor "o S#r/!'o

o criar a classe 8ue ficar4 respons4&el pela e5ecuo do *endamento! ser4 necess4rio 8ue esta classe implemente a interface @ "tate+ul'ob ! disponibilizado pelo Quartz# Esta interface obri*ar4 a implementao do m3todo execute()! respons4&el por e5ecutar a tarefa atra&3s do Scheduler# e5emplo de uma classe 8ue implementa StatefulJob: bai5o se*ue um pe8ueno

Guia para Utilizao do Framework Quartz % 'ELE> R

14
... /** * >lasse que e3ecu$a Jo do ?uar$z */ public class 43ecu$or5%endamen$o?uar$z implements S$a$e.ulJo ( ... /** * 43ecu$ar Jo a%endado. */ public void e3ecu$e&Jo 43ecu$ion>on$e3$ con$e3$' throws Jo 43ecu$ion43cep$ion ( ... // 43ecu$ar as operaJes previs$as para o a%endamen$o. +acade.e3ecu$a5l%uma)peracao&'! E ...

... E

Guia para Utilizao do Framework Quartz % 'ELE> R