A calendar decides at which day a job will run whereas a schedule's time expression decides at which time. A schedule can be optionally based on a calendar. If not, the job will run every day.
A calendar consists of the following parts:
Each part must be enabled separately, only enabled parts are respected. The type of a calendar, "include" or "exclude", decides whether the marked dates in an enabled part are included or excluded. Instead of using multiple parts of a single calendar it is recommended to stack calendars (described in a further section) which is much more flexible.
This part can be used to set the week days of a calendar:
The above example enables Monday to Friday. If the calendar is of type "include", then Monday to Friday are valid but Saturday and Sunday are invalid. If it is "exclude", then Saturday and Sunday are valid but Monday to Friday are invalid.
If the above calendar is saved in the routerconfig.xml, it looks like this:
<calendar name="Business Days" enable-weekdays="true" type="include">
<weekdays day-02="true" day-03="true" day-04="true" day-05="true" day-06="true"/>
</calendar>
As you see, Monday is "day-02", so the first day in a week is always Sunday ("day-01"). You might consider it if you configure a calendar directly in the routerconfig.xml.
This part can be used to set the month days of a calendar:
The above example enables the days 5, 10, 15, 20, 25, 30 of a month. If the calendar is of type "include", only these days are valid and the rest days of the month are invalid. If it is "exclude", all days of the month are valid, except the marked days.
The last day of a month varies. It might be the 28th February, 30th April, and so on. Some jobs might run on every last day in a month, e.g. end of month processing. This can be specified in a calendar by enabling the part "Month Days" AND "Last Month Day" (both!):
The above example enables the last day of a month. If the calendar is of type "include", the day is valid and all other days of a month are invalid. If it is "exclude", all days of a month are valid, except the last day.
This part of a calendar can be used to specify fixed dates of a year like bank holidays:
The above example defines 2 annual days, the 1st January (New Year) and the 3rd October (German Reunion Day). Since it is of type "exclude", these days are excluded.
This part of a calendar can be used to specify date ranges like company holidays and so on:
The above example defines 2 date ranges, "Summer Holiday" and "Winter Holiday". Since it is of type "exclude", these date ranges are excluded.
The real power of calendars is that you can build stacks of calendars, that is, you can create a calendar which is based on another calendar which might be based on another calendar and so on. Look at this example:
The left calendar "Business Days" is of type "include" and uses the week days part to enable Monday thru Friday. It hasn't a base calendar, so it's just that Monday thru Friday are valid.
The middle calendar "Bank Holidays" is of type "exclude" and uses the annual days part with 2 bank holiday entries. It is based on calendar "Business Days", referenced via attribute "Base Calendar". The result is that Monday thru Friday are valid (from "Business Days"), except 1st January and 3rd October (from "Bank Holidays").
The right calendar "Company Holidays" is of type "exclude" and uses the date range part with a single date range. It is based on calendar "Bank Holidays". The result is that Monday thru Friday are valid (from "Business Days"), except 1st January and 3rd October (from "Bank Holidays"), and except from 1st February 2002 to 10th February 2002 (from "Company Holidays").
Since the calendars are only connected by their name, you can build any combination of calendars, re-use existing calendars and so on. Only the sky is the limit!
All changes you perform on calendars (create a new calendar, modify or delete a calendar) are immediately applied to schedules. That is, all schedules which have a reference to the calendar (directly or indirect via a stacked calendar) are determined. If a job instance of these schedules is currently running, it is stopped and the schedule will be re-scheduled on base of the changes.
Therefore, if you don't want that a running job will be stopped due to a change, wait with your changes until your job(s) are finished, then disable the resp. schedule(s) and apply your calendar changes. Thereafter, enable the schedule(s).