Trading calendars

Trading calendars are used throughout the framework, primarily to display the time series on charts.

The main reason to use trading calendars is to avoid displaying empty spaces in the periods outside trading hours.

Trading calendars can be used by any other service, included [Trading Agents](Trading Agents).

Trading Calendar Manager

The service responsible for retrieving trading calendars is the interface:

public interface ITradingCalendarManager {
	ITradingCalendar tradingCalendarByName(String name);
	List<ITradingCalendar> findTradingCalendars(IContract contract, Boolean includeAfterHours);
}

This service must be available in the OSGi framework, in order for many functionalities to work.

The default implementation shipped with quantcomponents is this class, from the bundle com.quantcomponents.tradingcalendars.
It inspects every bundle, following the extender pattern, looking for a first level directory named tradingCalendars.
Whenever such a directory is found in a bundle, all the files with the .xml extension in it are parsed, and, if one is a valid calendar specification, an ITradingCalendar is created for it, and made available in the registry.

Trading calendar XML format

The format for a trading calendar is quite straightforward, and it is best explained looking at an example file, contained in the com.quantcomponents.tradingcalendars.standard bundle: cme_sp500mini.xml.
This file has been created for the mini futures on the S&P500 and exemplifies all the features of a trading calendar.

Let's analyse the important things:

Header

<name>CME S&amp;P500 mini</name> the name must be unique in the framework, since it is the key used to retrieve the calendars from the Trading Calendar Manager.

<description>CME S&amp;P500 mini futures 2012-2013</description> can be anything.

<timeZone>CST</timeZone> is important for the correct visualization. It is handed to java.util.TimeZone.getTimeZone(java.lang.String).

<startDate>2012-01-01T00:00:00 -0600</startDate>
<endDate>2013-01-01T00:00:00 +0600</endDate>

are the extremes between which the calendar is valid.

<includeAfterHours>true</includeAfterHours> is very important, since it must correspond to the flag on the time series, in order to be used with it.

<exchanges>
    <exchange>GLOBEX</exchange>
    <exchange>CBOT</exchange>
</exchanges>

The exchanges are matched against the exchange declared by the time series (it is selected by the time series creation wizard), and only trading calendars that include the time series exchange can be used for display.

Trading period specification

<bankHoliday>20121225</bankHoliday> must be specified one by one.

All other trading period specification are based on the same type:

<tradingDay>
    <tradingPeriod>
        <startHour>0</startHour>
        <startMinute>0</startMinute>
        <endHour>15</endHour>
        <endMinute>15</endMinute>
    </tradingPeriod>
    <tradingPeriod>
        <startHour>15</startHour>
        <startMinute>30</startMinute>
        <endHour>16</endHour>
        <endMinute>15</endMinute>
    </tradingPeriod>
    <tradingPeriod>
        <startHour>17</startHour>
        <startMinute>0</startMinute>
        <endHour>24</endHour>
        <endMinute>0</endMinute>
    </tradingPeriod>
</tradingDay>

The tradingDay can specify several tradingPeriods, each with a start time and end time specification. All times are considered relative to the timeZone specified in the header.

The weekTradingDays tag includes a map day of the week -> tradingDay where the integer constants for the days of the week are as specified by java.util.Calendar: SUNDAY = 1, SATURDAY = 7.

<weekTradingDay>
    <dayOfTheWeek>1</dayOfTheWeek>
    <tradingDay>
        <tradingPeriod>
            <startHour>17</startHour>
            <startMinute>0</startMinute>
            <endHour>24</endHour>
            <endMinute>0</endMinute>
        </tradingPeriod>
    </tradingDay>
</weekTradingDay>

A specialTradingDay correspond to a singular date with a specific opening time, and must be specified individually:

<specialTradingDay>
    <date>20121224</date>
    <tradingDay>
        <tradingPeriod>
            <endHour>13</endHour>
            <endMinute>30</endMinute>
            <startHour>10</startHour>
            <startMinute>0</startMinute>
        </tradingPeriod>
    </tradingDay>
</specialTradingDay>

Adding new calendars

To add a new set of calendars to the framework, create a bundle with a tradingCalendars directory in it, and put there all the XML definition files. Then install the new bundle as explained [here](Trading agents), but with a major difference: adding calendar bundles is much easier, since they do not need to be activated, only installed. Therefore there is no need to create an OSGi activator or a component definition. Just a plain bundle with this special directory in its root.

Many other ways of specifying trading calendars can be found. The service interface to implement is very small, and by substituting com.quantcomponents.tradingcalendars with a different bundle, declaring a service implementing ITradingCalendarManager, any scheme can be provided.

TODO coexistence of several Trading Calendar Managers