public interface CalendarService
ServiceCalendar and ServiceCalendarDate
entities for a given GTFS feed compactly represent the dates of service for a
particular service id, they are not particularly amenable to quick
calculations.
The CalendarService abstracts common date operations into a service
interface. The service is typically backed by an efficient data structure
that has scanned all the ServiceCalendar and
ServiceCalendarDate entities into an appropriate representation.
Many of the methods in CalendarService refer to "service dates". A
service date is a particular date when a particular service id is active. The
service date is represented by a ServiceDate object, which is a
locale-independent way of representing the year-month-date for a particular
service date.
A service date can be localized to a particular timezone (as specified for a
particular Agency) by calling the
ServiceDate.getAsDate(java.util.TimeZone) method to return an actual
Date object. Typically, the date is specified as midnight at the
start of the day in the specified timezone for the specified service date,
such that adding the arrival or departure time in seconds (as specified in a
StopTime) will return the actual arrival or departure time in UTC.
Note that on some days, like daylight saving time days, the time may not
actually be at midnight in order the make the StopTime calculation
correct, per the GTFS spec.
In many CalendarService methods, we refer to a
LocalizedServiceId, which is a service id that also includes timezone
information, such that localized service dates can be returned by a method.
It's important to note that a single timezone can't be attached to a
particular service id, since agencies with potentially different timezones
can refer to the same service id in a given GTFS feed.Set<AgencyAndId> getServiceIds()
Set<ServiceDate> getServiceDatesForServiceId(AgencyAndId serviceId)
serviceId - the target service idSet<AgencyAndId> getServiceIdsOnDate(ServiceDate date)
date - the target service dateTimeZone getTimeZoneForAgencyId(String agencyId)
TimeZone for the specified agency idagencyId - Agency.getId()LocalizedServiceId getLocalizedServiceIdForAgencyAndServiceId(String agencyId, AgencyAndId serviceId)
LocalizedServiceId
which is just a service id with timezone information attached. We use the
agencyId argument of the method call to lookup the timezone for requested
agency.
Note that the service id itself has an agencyId component as well, but we
don't use that for the timezone lookup. The service id's agencyId is more
of a prefix to guarantee dataset uniqueness. For example, multiple
Trip objects, representing different agencies, can all reference
the same service id. Its important that we look up agency timezone
information using the trip's agencyId and not the serviceId's agencyId.agencyId - the id of the Agency whose timezone info we will useserviceId - the service id to useList<Date> getDatesForLocalizedServiceId(LocalizedServiceId localizedServiceId)
boolean isLocalizedServiceIdActiveOnDate(LocalizedServiceId localizedServiceId, Date serviceDate)
List<Date> getServiceDatesWithinRange(LocalizedServiceId serviceId, ServiceInterval interval, Date from, Date to)
ServiceInterval, overlap with the
specified from-to time range.
Let's consider a few concrete examples to describe what this method does.
Consider a single StopTime with an arrival and departure time. That
StopTime is part of a Trip, which means it has a service id
attached to it. We wish to answer the question, What service dates would
make the specified StopTime active in a particular time range? To answer
that question, we'd need to consider each of the localized service dates
for which the specified service id is active, add the StopTime arrival and
departure offset to each, and see if the resulting time falls within the
target range. This method can perform that comparison. By specifying the
target service id, a ServiceInterval whose min and max arrival and
departure times are set to the arrival and departure time of the
StopTime, and the target from-to time interval, the method will
return the set of localized service dates that would make the StopTime
arrival or departure times active in the specified target time range.
As slightly different example, consider answering that same question for
multiple StopTime objects, such as all the StopTimes for a
particular trip or all the StopTimes for a particular stop. The question is
the same, but the difference is now there are multiple arrival and
departure times. Here, an appropriate ServiceInterval can be
constructed that includes the min and max arrival and departure times for
the set of StopTime objects and the calculation will be done
looking for service dates that cause any part of the service interval to
overlap with the target from-to range.
Note that this method considers both the arrival and departure times when
looking for overlaps. To consider only arrival times, check out
getServiceDateArrivalsWithinRange(LocalizedServiceId, ServiceInterval, Date, Date)
and for departures, check out
getServiceDateDeparturesWithinRange(LocalizedServiceId, ServiceInterval, Date, Date)serviceId - the localized service id whose service dates we'll
considerinterval - a range of arrival and departure times to considerfrom - - the min portion of the target time intervalto - - the max portion of the target time intervalMap<LocalizedServiceId,List<Date>> getServiceDatesWithinRange(ServiceIdIntervals serviceIdIntervals, Date from, Date to)
getServiceDatesWithinRange(LocalizedServiceId, ServiceInterval, Date, Date)
. This method does the same thing, except that it works with multiple
service ids and intervals at the same time.serviceIdIntervals - - a set of service ids and service intervalsfrom - - time interval minto - - time interval maxList<Date> getServiceDateDeparturesWithinRange(LocalizedServiceId serviceId, ServiceInterval interval, Date from, Date to)
getServiceDatesWithinRange(LocalizedServiceId, ServiceInterval, Date, Date)
. This method does the same thing, except that it only considers departure
times.serviceId - the localized service id whose service dates we'll
considerinterval - a range of departure times to considerfrom - - the min portion of the target time intervalto - - the max portion of the target time intervalMap<LocalizedServiceId,List<Date>> getServiceDateDeparturesWithinRange(ServiceIdIntervals serviceIdIntervals, Date from, Date to)
getServiceDateDeparturesWithinRange(LocalizedServiceId, ServiceInterval, Date, Date)
. This method does the same thing, except that it works with multiple
service ids and intervals at the same time.serviceIdIntervals - - a set of service ids and service intervalsfrom - - time interval minto - - time interval maxList<Date> getServiceDateArrivalsWithinRange(LocalizedServiceId serviceId, ServiceInterval interval, Date from, Date to)
getServiceDatesWithinRange(LocalizedServiceId, ServiceInterval, Date, Date)
. This method does the same thing, except that it only considers arrival
times.serviceId - the localized service id whose service dates we'll
considerinterval - a range of arrival times to considerfrom - - the min portion of the target time intervalto - - the max portion of the target time intervalMap<LocalizedServiceId,List<Date>> getServiceDateArrivalsWithinRange(ServiceIdIntervals serviceIdIntervals, Date from, Date to)
getServiceDateArrivalsWithinRange(LocalizedServiceId, ServiceInterval, Date, Date)
. This method does the same thing, except that it works with multiple
service ids and intervals at the same time.serviceIdIntervals - - a set of service ids and service intervalsfrom - - time interval minto - - time interval maxList<Date> getNextDepartureServiceDates(LocalizedServiceId serviceId, ServiceInterval interval, long targetTime)
StopTime after
the target time at a particular stop . By calling this method with the
serviceId and service interval for the specified stop, we return the set of
service dates that overlap or the next service date if none do,
guaranteeing that at least one service date instantiates a StopTime that
occurs after the target time.serviceId - the localized service id whose service dates we'll
considerinterval - a range of departure times to considertargetTime - - time in UTCMap<LocalizedServiceId,List<Date>> getNextDepartureServiceDates(ServiceIdIntervals serviceIdIntervals, long targetTime)
getNextDepartureServiceDates(LocalizedServiceId, ServiceInterval, long)
. This method does the same thing, except that it works with multiple
service ids and intervals at the same time.serviceIdIntervals - - set of service ids and service intervalstargetTime - List<Date> getPreviousArrivalServiceDates(LocalizedServiceId serviceId, ServiceInterval interval, long targetTime)
StopTime
before the target time at a particular stop . By calling this method with
the serviceId and service interval for the specified stop, we return the
set of service dates that potentially overlap or the previous service date
if none do, guaranteeing that at least one service date instantiates a
StopTime that occurs before the target time.serviceId - the localized service id whose service dates we'll
considerinterval - a range of arrival times to considertargetTime - - time in UTCMap<LocalizedServiceId,List<Date>> getPreviousArrivalServiceDates(ServiceIdIntervals serviceIdIntervals, long targetTime)
getPreviousArrivalServiceDates(LocalizedServiceId, ServiceInterval, long)
. This method does the same thing, except that it works with multiple
service ids and intervals at the same time.serviceIdIntervals - - set of service ids and service intervalstargetTime - Copyright © 2013 OneBusAway. All Rights Reserved.