Nav

Quartz Transport Reference

When scheduling tasks, use the Poll Scope instead of Quartz

The Quartz transport provides support for scheduling events and for triggering new events. An inbound quartz endpoint can be used to trigger inbound events that can be repeated, such as every second. Outbound quartz endpoints can be used to schedule an existing event to fire at a later date. Users can create schedules using cron expressions, and events can be persisted in a database.

This transport makes use of the Quartz Project. The Quartz site has more generic information about how to work with Quartz.

Notes:

  • When running in an environment with multiple workers or nodes, a Quartz scheduler, by default, runs on each node, whereas a Poll Scope only runs on a single node. A Quartz scheduler can be configured to work this way but requires configuration of a JDBC JobStore.

  • When using a Quartz inbound endpoint, you cannot manage it through the Schedulers tab.

About Cron Expressions

A cron expression is a string comprised by six or seven fields separated by white space. Fields can contain any of the allowed values, along with various combinations of the allowed special characters for that field. The fields are as follows:

Field Name Mandatory Allowed Values Allowed Special Chars

Seconds

YES

0-59

, - * /

Minutes

YES

0-59

, - * /

Hours

YES

0-23

, - * /

Day of Month

YES

1-31

, - * ? / L W C

Month

YES

1-12 or JAN-DEC

, - * /

Day of Week

YES

1-7 or SUN-SAT

, - * ? / L C #

Year

NO

empty, 1970-2099

, - * /

Cron expressions can be as simple as this:
* * * * ? *

or more complex, like this:
0 0/5 14,18,3-39,52 ? JAN,MAR,SEP MON-FRI 2002-2010.

Following are some examples:

Expression Behavior

0 0 12 * * ?

Fire at 12pm (noon) every day

0 15 10 ? * *

Fire at 10:15am every day

0 15 10 * * ?

Fire at 10:15am every day

0 15 10 * * ? *

Fire at 10:15am every day

0 15 10 * * ? 2005

Fire at 10:15am every day during the year 2005

0 * 14 * * ?

Fire every minute starting at 2pm and ending at 2:59pm, every day

0 0/5 14 * * ?

Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day

1 1 1 1,6 * ?

Fire the first day of January and the first day of June, every year (in the first second of the first minute of the first hour)

If you are not familiar with cron syntax, don’t be intimidated! It’s reasonably easy to learn, here is a good tutorial, or you can even leverage online tools that can build cron expressions for you.

About Jobs

Jobs are used to perform an action when a time trigger occurs from the Quartz transport. Mule provides a number of jobs for generating and scheduling events. These are detailed below. Users can also write their own jobs and hook them in using the custom-job type included with Mule.

Connector

The Quartz connector is used to configure the default behavior for Quartz endpoints that reference the connector. Note if there is only one Quartz connector configured, all Quartz endpoints will use that connector.

Attributes of <connector…​>

Name Description

scheduler-ref

Provides an implementation of the Quartz Scheduler interface. If no value is provided, a scheduler is retrieved from the StdSchedulerFactory. If no properties are provided, the getDefaultScheduler method is called. Otherwise, a new factory instance is created using the given properties, and a scheduler is retrieved using the getScheduler method.

Type: string
Required: no
Default: none

Child elements of <connector…​>

Name Cardinality Description

factory-property

0..*

Set a property on the factory (see scheduler-ref).

When setting the org.quartz.scheduler.instanceName factory property, be sure to avoid duplicate names.

The value of instanceName must be different for every Quartz connector running in the same Mule instance, even if in different applications.

<quartz:factory-property key="org.quartz.scheduler.instanceName" value="MuleScheduler1"/>

If Quartz connectors share the same value for instanceName property, these connectors could miss firing the scheduled jobs in the applications in which they exist.

Example


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xmlns:quartz="http://www.mulesoft.org/schema/mule/quartz"
      xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/quartz http://www.mulesoft.org/schema/mule/quartz/current/mule-quartz.xsd">
 
    <quartz:connector name="quartzConnector1" scheduler-ref="myScheduler">
        <quartz:factory-property key="org.quartz.scheduler.instanceName" value="MuleScheduler1"/>
        <quartz:factory-property key="org.quartz.threadPool.class" value="org.quartz.simpl.SimpleThreadPool"/>
        <quartz:factory-property key="org.quartz.threadPool.threadCount" value="3"/>
        <quartz:factory-property key="org.quartz.scheduler.rmi.proxy" value="false"/>
        <quartz:factory-property key="org.quartz.scheduler.rmi.export" value="false"/>
        <quartz:factory-property key="org.quartz.jobStore.class" value="org.quartz.simpl.RAMJobStore"/>
    </quartz:connector>
...

Outbound Endpoint

An outbound Quartz endpoint allows existing events to be stored and fired at a later time/date. If you are using a persistent event store, the payload of the event must implement java.io.Serializable. You configure an org.quartz.Job implementation on the endpoint to tell it what action to take. Mule has some default jobs, but you can also write your own.

Attributes of <outbound-endpoint…​>

Name Description

jobName

The name to associate with the job on the endpoint. This is only really used internally when storing events.

Type: string
Required: no
Default: none

cronExpression

The cron expression to schedule events at specified dates/times. This attribute or repeatInterval is required. A cron expression is a string comprised by 6 or 7 fields separated by white space. Fields can contain any of the allowed values, along with various combinations of the allowed special characters for that field. See About Cron Expressions for field names, allowed values, and examples.

Type: string
Required: no
Default: none

repeatInterval

The number of milliseconds between two events. This attribute or cronExpression is required.

Type: long
Required: no
Default: none

repeatCount

The number of events to be scheduled. This value defaults to -1, which means that the events are scheduled indefinitely.

Type: integer
Required: no
Default: none

startDelay

The number of milliseconds that elapse before the first event is fired.

Type: long
Required: no
Default: none

cronTimeZone

Timezone to use as reference.

Type: time zone
Required: no
Default: Time zone passed as system property, or in a machine’s operating system.

Child Elements of <outbound-endpoint…​>

Name Cardinality Description

abstract-job

1..1

A placeholder for Quartz jobs that can be set on the endpoint.

Inbound Endpoint

A Quartz inbound endpoint can be used to generate events. It is most useful when you want to trigger a flow at a given interval (or cron expression) rather than have an external event trigger the flow.

Attributes of <inbound-endpoint…​>

Name Description

jobName

The name to associate with the job on the endpoint. This is only really used internally when storing events.

Type: string
Required: no
Default: none

cronExpression

The cron expression to schedule events at specified dates/times. This attribute or repeatInterval is required. A cron expression is a string comprised by 6 or 7 fields separated by white space. Fields can contain any of the allowed values, along with various combinations of the allowed special characters for that field. See About Cron Expressions  for field names, allowed values, and examples.

Type: string
Required: no
Default: none

repeatInterval

The number of milliseconds between two events. This attribute or cronExpression is required.

Type: long
Required: no
Default: none

repeatCount

The number of events to be scheduled. This value defaults to -1, which means that the events are scheduled indefinitely.

Type: integer
Required: no
Default: none

startDelay

The number of milliseconds that elapse before the first event is fired.

Type: long
Required: no
Default: none

cronTimeZone

Timezone to use as reference.

Type: time zone
Required: no
Default: Time zone passed as system property, or in machine’s operating system.

Child Elements of <inbound-endpoint…​>

Name Cardinality Description

abstract-job

1..1

A placeholder for Quartz jobs that can be set on the endpoint.

Endpoint

A global endpoint that can be used as a template to create inbound and outbound Quartz endpoints. Common configuration can be set on a global endpoint and then referenced using the @ref attribute on the local endpoint. Note that because jobs sometimes only work on inbound or outbound endpoints, they have to be set on the local endpoint.

Attributes of <endpoint…​>

Name Description

jobName

The name to associate with the job on the endpoint. This is only really used internally when storing events.

Type: string
Required: no
Default: none

cronExpression

The cron expression to schedule events at specified dates/times. This attribute or repeatInterval is required. A cron expression is a string comprised by 6 or 7 fields separated by white space. Fields can contain any of the allowed values, along with various combinations of the allowed special characters for that field. See About Cron Expressions  for field names, allowed values, and examples.

Type: string
Required: no
Default: none

repeatInterval

The number of milliseconds between two events. This attribute or cronExpression is required.

Type: long
Required: no
Default: none

repeatCount

The number of events to be scheduled. This value defaults to -1, which means that the events are scheduled indefinitely.

Type: integer
Required: no
Default: none

startDelay

The number of milliseconds that elapse before the first event is fired.

Type: long
Required: no
Default: none

cronTimeZone

Timezone to use as reference.

Type: time zone
Required: no
Default: Time zone passed as system property, or in machine’s operating system.

Child Elements of <endpoint…​>

Name Cardinality Description

abstract-job

0..1

A placeholder for Quartz jobs that can be set on the endpoint.

Abstract Job

A placeholder for Quartz jobs that can be set on the endpoint.

Attributes of <abstract-job…​>

Name Description

groupName

The group name of the scheduled job.

Type: string
Required: no
Default: none

jobGroupName

The job group name of the scheduled job.

Type: string
Required: no
Default: none

Abstract Inbound Job

A placeholder for Quartz jobs that can be set on inbound endpoints only.

Attributes of <abstract-inbound-job…​>

Name Description

groupName

The group name of the scheduled job.

Type: string
Required: no
Default: none

jobGroupName

The job group name of the scheduled job.

Type: string
Required: no
Default: none

Event Generator Job

An inbound endpoint job that triggers a new event for the flow according to the schedule on the endpoint. This is useful for periodically triggering a flow without the need for an external event to occur.

Attributes of <event-generator-job…​>

Name Description

stateful

Determines if the job is persistent. If so, the job detail state persists for each request. More importantly, each job that triggers executes sequentially. If the Job takes longer than the next trigger, the next job waits for the current job to execute.

Type: boolean
Required: no
Default: none

Child Elements of <event-generator-job…​>

Name Cardinality Description

payload

0..1

The payload of the newly created event. The payload can be a reference to a file, fixed string, or object configured as a Spring bean. If this value is not set, an event generates with an org.mule.transport.NullPayload instance.

Example


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<quartz:connector name="Quartz" validateConnections="true" doc:name="Quartz"/>
<flow name="test2Flow1" doc:name="test2Flow1">
  <description>
  This configuration creates an inbound event for testService1 at 12 noon every day.
  The event payload always has the same value 'foo'.
  </description>
    <quartz:inbound-endpoint jobName="job1" cronExpression="0 0 12 * * ?" repeatInterval="0" responseTimeout="10000" connector-ref="Quartz" doc:name="Quartz">
        <quartz:event-generator-job>
          <quartz:payload>foo</quartz:payload>
        </quartz:event-generator-job>
    </quartz:inbound-endpoint>
</flow>
<flow name="test2Flow2" doc:name="test2Flow2">
  <description>This configuration creates an inbound event for testService2
  every 1 second indefinitely. The event payload always has the same value,
  which the contents of the file 'payload-data.txt'. The file can be on the
  classpath of the local file system.
  </description>
    <quartz:inbound-endpoint jobName="job2" repeatInterval="0" repeatCount="10" responseTimeout="10000" doc:name="Quartz" connector-ref="Quartz">
        <quartz:event-generator-job>
          <quartz:payload file="payload-data.txt"/>
        </quartz:event-generator-job>
    </quartz:inbound-endpoint>
</flow>

Endpoint Polling Job

An inbound endpoint job that can be used to periodically read from an external source (via another endpoint). This can be useful for triggering time-based events from sources that do not support polling or for simply controlling the rate in which events are received from the source.

Attributes of <endpoint-polling-job…​>

Name Description

stateful

Determines if the job is persistent. If so, the job detail state persists for each request. More importantly, each job that triggers executes sequentially. If the Job takes longer than the next trigger, the next job waits for the current job to execute.

Type: boolean
Required: no
Default: none

Child Elements of <endpoint-polling-job…​>

Name Cardinality Description

job-endpoint

0..1

A reference to another configured endpoint from which events are received.

Example


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<flow name="testFlow3" doc:name="testFlow3">
  <description>The endpoint polling Job tries and performs a 'request' on any Mule
  endpoint. If a result is received, it hands off to this 'testFlow3' flow
  for processing. The trigger fires every 5 minutes starting at 2pm and ending at
  2:55pm, every day. During this period, the job checks the file directory
  /N/drop-data/in every 5 minutes to see if any event data is available.
  </description>
  <quartz:inbound-endpoint jobName="job3" cronExpression="0 0/5 14 * * ?"
   repeatInterval="0" repeatCount="10" responseTimeout="10000"
   doc:name="Quartz" connector-ref="Quartz">
      <quartz:endpoint-polling-job>
        <quartz:job-endpoint address="file:///N/drop-data/in"/>
      </quartz:endpoint-polling-job>
  </quartz:inbound-endpoint>
</flow>

Scheduled Dispatch Job

An outbound job that schedules a job for dispatch at a later time/date. The event gets dispatched using the configured endpoint reference.

Attributes of <scheduled-dispatch-job…​>

Name Description

stateful

Determines if the job is persistent. If so, the job detail state persists for each request. More importantly, each job that triggers executes sequentially. If the Job takes longer than the next trigger, the next job waits for the current job to execute.

Type: boolean
Required: no
Default: none

Child Elements of <scheduled-dispatch-job…​>

Name Cardinality Description

job-endpoint

0..1

The endpoint used to dispatch the scheduled event. The preferred approach is to create a global endpoint and reference it using the ref attribute. However, you can also use the address attribute to define a URI endpoint (which supports expressions). You can use the timeout attribute to specify an arbitrary time-out value associated with the endpoint that can be used by jobs that block waiting to receive events.

Example


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<description>
  This outbound Quartz endpoint receives an event after the component
  has processed it and stores it in the event store. When the trigger
  kicks in at 10:15am everyday, it dispatches the event on the endpoint
  referenced as 'scheduledDispatchEndpoint'. Since the 'repeatCount'
  is set to 0, the event is only sent out once.
  </description>
  <quartz:connector name="Quartz" validateConnections="true" doc:name="Quartz"/>
  <flow name="test2Flow1" doc:name="test2Flow1">
    <vm:inbound-endpoint exchange-pattern="one-way" path="INBOUND.QUEUE" doc:name="VM"/>
    <quartz:outbound-endpoint jobName="job4" cronExpression="0 15 10 * * ? *"
    repeatInterval="0" responseTimeout="10000" connector-ref="Quartz"
    doc:name="Quartz">
        <quartz:scheduled-dispatch-job>
            <quartz:job-endpoint ref="scheduledDispatchEndpoint"/>
        </quartz:scheduled-dispatch-job>
    </quartz:outbound-endpoint>
</flow>

Custom Job

A custom job can be configured on inbound or outbound endpoints. You can create and configure your own job implementation and use it on a Quartz endpoint. A custom job can be configured as a bean in the XML configuration and referenced using this job.

Attributes of <custom-job…​>

Name Description

groupName

The group name of the scheduled job.

Type: string
Required: no
Default: none

jobGroupName

The job group name of the scheduled job.

Type: string
Required: no
Default: none

job-ref

The bean name or ID of the custom job to use when this job gets executed.

Type: string
Required: no
Default: none

Example


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<flow name="testFlow3" doc:name="testFlow3">
  <description>The endpoint polling Job tries and performs a 'request' on any Mule
  endpoint. If a result is received it is handed off to this 'testFlow3' flow
  for processing. The trigger fires every 5 minutes starting at 2pm and ending at
  2:55pm, every day. During this period the job checks the file directory
  /N/drop-data/in every 5 minutes to see if any event data is available.
  </description>
  <quartz:inbound-endpoint jobName="job3" cronExpression="0 0/5 14 * * ?"
    repeatInterval="0" repeatCount="10" responseTimeout="10000"
    doc:name="Quartz" connector-ref="Quartz">
      <quartz:endpoint-polling-job>
              <quartz:job-endpoint address="file:///N/drop-data/in"/>
      </quartz:endpoint-polling-job>
  </quartz:inbound-endpoint>
</flow>

Custom Job From Message

Allows a job to be stored on the current message. This can only be used on outbound endpoints. When the message is received, the job is read and the job is added to the scheduler with the current message. This allows for custom scheduling behavior determined by the message itself. Usually the flow or a transformer would create the job on the message based on application-specific logic. Any Mule-supported expressions can be used to read the job from the message. Typically, you add the job as a header, but an attachment could also be used.

Attributes of <custom-job-from-message…​>

Name Description

groupName

The group name of the scheduled job.

Type: string
Required: no
Default: none

jobGroupName

The job group name of the scheduled job.

Type: string
Required: no
Default: none

Example


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<flow name="testFlow3" doc:name="testFlow3">
  <description>This configuration processes a message and find a
  Job configured as a header called 'jobConfig' on the current message.
  We're using the test component here, but a real implementation needs
  to set a custom {{org.quartz.Job}} implementation as a header on the
  current message. Note that other expressions could be used to extract
  the job from an attachment or even a property within the payload itself.
  </description>
  <quartz:connector name="Quartz" validateConnections="true" doc:name="Quartz"/>

  <flow name="test2Flow1" doc:name="test2Flow1">
    <vm:inbound-endpoint exchange-pattern="one-way" path="INBOUND.QUEUE" doc:name="VM"/>
    <quartz:outbound-endpoint jobName="job4" cronExpression="0 15 10 * * ? *"
    repeatInterval="0" responseTimeout="10000" connector-ref="Quartz"
    doc:name="Quartz">
    <quartz:custom-job-from-message evaluator="header" expression="jobConfig"/>
    </quartz:outbound-endpoint>
</flow>

See Also