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 Detail

      • 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

      • isLocalizedServiceIdActiveOnDate

        boolean isLocalizedServiceIdActiveOnDate​(LocalizedServiceId localizedServiceId,
                                         Date serviceDate)

      • 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

      • 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

      • 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

      • 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

      • 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

      • setData

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