Package org.onebusaway.gtfs.services.calendar

Interface CalendarService

All Known Subinterfaces:
GtfsDataService
All Known Implementing Classes:
CalendarServiceImpl, GtfsDataServiceImpl
public interface CalendarService
While the set of 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.
Author:
bdferris

  • Method Details

    • getServiceIds

      Set<AgencyAndId> getServiceIds()
      Returns:
      the set of all service ids used in the data set

    • getServiceDatesForServiceId

      Set<ServiceDate> getServiceDatesForServiceId(AgencyAndId serviceId)
      Parameters:
      serviceId - the target service id
      Returns:
      the set of all service dates for which the specified service id is active

    • getServiceIdsOnDate

      Set<AgencyAndId> getServiceIdsOnDate(ServiceDate date)
      Determine the set of service ids that are active on the specified service date.
      Parameters:
      date - the target service date
      Returns:
      the set of service ids that are active on the specified service date

    • getTimeZoneForAgencyId

      TimeZone getTimeZoneForAgencyId(String agencyId)
      Returns the instantiated TimeZone for the specified agency id
      Parameters:
      agencyId - Agency.getId()
      Returns:
      the time zone for the specified agency, or null if the agency was not found

    • getLocalizedServiceIdForAgencyAndServiceId

      LocalizedServiceId getLocalizedServiceIdForAgencyAndServiceId(String agencyId, AgencyAndId serviceId)
      Given an agency id and a service id, we return a 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.
      Parameters:
      agencyId - the id of the Agency whose timezone info we will use
      serviceId - the service id to use
      Returns:
      a localized service id with timezone info attached, or nul if the specified agency could not be found

    • getDatesForLocalizedServiceId

      List<Date> getDatesForLocalizedServiceId(LocalizedServiceId localizedServiceId)

    • isLocalizedServiceIdActiveOnDate

      boolean isLocalizedServiceIdActiveOnDate(LocalizedServiceId localizedServiceId, Date serviceDate)

    • isLocalizedServiceIdActiveInRange

      boolean isLocalizedServiceIdActiveInRange(LocalizedServiceId localizedServiceId, ServiceInterval activeService, AgencyServiceInterval serviceInterval)

    • getServiceDatesWithinRange

      List<Date> getServiceDatesWithinRange(LocalizedServiceId serviceId, ServiceInterval interval, Date from, Date to)
      Given the specified localized service id, which has a corresponding set of localized service dates, determine the sublist of service dates that, when extended with the specified 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)
      Parameters:
      serviceId - the localized service id whose service dates we'll consider
      interval - a range of arrival and departure times to consider
      from - - the min portion of the target time interval
      to - - the max portion of the target time interval
      Returns:
      the list of localized service dates that would make the specified service interval overlap with the specified from-to time range

    • getServiceDatesWithinRange

      Map<LocalizedServiceId,List<Date>> getServiceDatesWithinRange(ServiceIdIntervals serviceIdIntervals, Date from, Date to)
      See the description from 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.
      Parameters:
      serviceIdIntervals - - a set of service ids and service intervals
      from - - time interval min
      to - - time interval max
      Returns:
      the list of active service dates, keyed by service id

    • getServiceDateDeparturesWithinRange

      List<Date> getServiceDateDeparturesWithinRange(LocalizedServiceId serviceId, ServiceInterval interval, Date from, Date to)
      See the description from getServiceDatesWithinRange(LocalizedServiceId, ServiceInterval, Date, Date) . This method does the same thing, except that it only considers departure times.
      Parameters:
      serviceId - the localized service id whose service dates we'll consider
      interval - a range of departure times to consider
      from - - the min portion of the target time interval
      to - - the max portion of the target time interval
      Returns:
      the list of active service dates

    • getServiceDateDeparturesWithinRange

      Map<LocalizedServiceId,List<Date>> getServiceDateDeparturesWithinRange(ServiceIdIntervals serviceIdIntervals, Date from, Date to)
      See the description from 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.
      Parameters:
      serviceIdIntervals - - a set of service ids and service intervals
      from - - time interval min
      to - - time interval max
      Returns:
      the list of active service dates, keyed by service id

    • getServiceDateArrivalsWithinRange

      List<Date> getServiceDateArrivalsWithinRange(LocalizedServiceId serviceId, ServiceInterval interval, Date from, Date to)
      See the description from getServiceDatesWithinRange(LocalizedServiceId, ServiceInterval, Date, Date) . This method does the same thing, except that it only considers arrival times.
      Parameters:
      serviceId - the localized service id whose service dates we'll consider
      interval - a range of arrival times to consider
      from - - the min portion of the target time interval
      to - - the max portion of the target time interval
      Returns:
      the list of active service dates

    • getServiceDateArrivalsWithinRange

      Map<LocalizedServiceId,List<Date>> getServiceDateArrivalsWithinRange(ServiceIdIntervals serviceIdIntervals, Date from, Date to)
      See the description from 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.
      Parameters:
      serviceIdIntervals - - a set of service ids and service intervals
      from - - time interval min
      to - - time interval max
      Returns:
      the list of active service dates, keyed by service id

    • getNextDepartureServiceDates

      List<Date> getNextDepartureServiceDates(LocalizedServiceId serviceId, ServiceInterval interval, long targetTime)
      Computes the list of service dates whose departure service interval (min to max departure time) overlaps the specified target time. If no intervals overlaps, then the next service date whose full service interval comes immediately after (but does overlap) the target time is returned. This method is useful for finding the next scheduled 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.
      Parameters:
      serviceId - the localized service id whose service dates we'll consider
      interval - a range of departure times to consider
      targetTime - - time in UTC
      Returns:
      the set of overlapping and next service dates

    • getNextDepartureServiceDates

      Map<LocalizedServiceId,List<Date>> getNextDepartureServiceDates(ServiceIdIntervals serviceIdIntervals, long targetTime)
      See the description for getNextDepartureServiceDates(LocalizedServiceId, ServiceInterval, long) . This method does the same thing, except that it works with multiple service ids and intervals at the same time.
      Parameters:
      serviceIdIntervals - - set of service ids and service intervals
      targetTime -
      Returns:
      the set of overlapping and next service dates

    • getPreviousArrivalServiceDates

      List<Date> getPreviousArrivalServiceDates(LocalizedServiceId serviceId, ServiceInterval interval, long targetTime)
      Computes the list of service dates whose arrival service interval (min to max departure time) overlaps the specified target time. If not intervals overlap, then the previous service date whose full service interval comes immediately before (but does overlap) the target time is returned. This method is useful for finding the previous scheduled 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.
      Parameters:
      serviceId - the localized service id whose service dates we'll consider
      interval - a range of arrival times to consider
      targetTime - - time in UTC
      Returns:
      the set of overlapping and previous service dates

    • getPreviousArrivalServiceDates

      Map<LocalizedServiceId,List<Date>> getPreviousArrivalServiceDates(ServiceIdIntervals serviceIdIntervals, long targetTime)
      See the description for getPreviousArrivalServiceDates(LocalizedServiceId, ServiceInterval, long) . This method does the same thing, except that it works with multiple service ids and intervals at the same time.
      Parameters:
      serviceIdIntervals - - set of service ids and service intervals
      targetTime -
      Returns:
      the set of overlapping and previous service dates

    • setData

      void setData(CalendarServiceData data)
      Update the underlying data structures.
      Parameters:
      data -