javax.tv.service.guide

Interface ProgramSchedule

public interface ProgramSchedule

This interface represents a collection of program events for a given service ordered by time. It provides the current, next and future program events.

Note that all time values are in UTC time.

See Also:

java.util.Date, ProgramEvent, ReadPermission

Method Summary

Methods

Modifier and Type	Method and Description
void	addListener(ProgramScheduleListener listener) Registers a ProgramScheduleListener to be notified of changes to program events on this ProgramSchedule.
Locator	getServiceLocator() Reports the transport-dependent locator referencing the service to which this ProgramSchedule belongs.
void	removeListener(ProgramScheduleListener listener) Unregisters a ProgramScheduleListener.
SIRequest	retrieveCurrentProgramEvent(SIRequestor requestor) Retrieves the current ProgramEvent.
SIRequest	retrieveFutureProgramEvent(Date time, SIRequestor requestor) Retrieves the program event for the specified time.
SIRequest	retrieveFutureProgramEvents(Date begin, Date end, SIRequestor requestor) Retrieves all known program events on this service for the specified time interval.
SIRequest	retrieveNextProgramEvent(ProgramEvent event, SIRequestor requestor) Retrieves a event which follows the specified event.
SIRequest	retrieveProgramEvent(Locator locator, SIRequestor requestor) Retrieves a program event matching the locator.

Method Detail

retrieveCurrentProgramEvent

SIRequest retrieveCurrentProgramEvent(SIRequestor requestor)

Retrieves the current ProgramEvent. The resulting ProgramEvent is available for immediate viewing.

This method delivers its results asynchronously. If the caller does not have javax.tv.service.ReadPermission(pe.getLocator()) (where pe is the current program event), this method will result in an SIRequestFailureType of DATA_UNAVAILABLE.

Parameters:

requestor - The SIRequestor to be notified when this retrieval operation completes.

Returns:

An SIRequest object identifying this asynchronous retrieval request.

See Also:

ProgramEvent, ReadPermission

retrieveFutureProgramEvent

SIRequest retrieveFutureProgramEvent(Date time,
                                   SIRequestor requestor)
                                     throws SIException

Retrieves the program event for the specified time. The specified time will fall between the resulting program event's start time (inclusive) and end time (exclusive).

This method delivers its results asynchronously. If the caller does not have javax.tv.service.ReadPermission(pe.getLocator()) (where pe is the program event at the specified time), this method will result in an SIRequestFailureType of DATA_UNAVAILABLE.

Parameters:

time - The time of the program event to be retrieved.

requestor - The SIRequestor to be notified when this retrieval operation completes.

Returns:

An SIRequest object identifying this asynchronous retrieval request.

Throws:

SIException - If time does not represent a future time value.

See Also:

ProgramEvent, ReadPermission

retrieveFutureProgramEvents

SIRequest retrieveFutureProgramEvents(Date begin,
                                    Date end,
                                    SIRequestor requestor)
                                      throws SIException

Retrieves all known program events on this service for the specified time interval. A program event pe is retrieved by this method if the time interval from pe.getStartTime() (inclusive) to pe.getEndTime() (exclusive) intersects the time interval from begin (inclusive) to end (exclusive) specified by the input parameters.

This method returns data asynchronously. Only program events pe for which the caller has javax.tv.service.ReadPermission(pe.getLocator()) will be retrieved. If no program events meet this criteria, this method will result in an SIRequestFailureType of DATA_UNAVAILABLE.

Parameters:

begin - Time identifying the beginning of the interval.

end - Time identifying the end of the interval.

requestor - The SIRequestor to be notified when this retrieval operation completes.

Returns:

An SIRequest object identifying this asynchronous retrieval request.

Throws:

SIException - If end represents a time value before begin, or if end does not represent a future time value.

See Also:

ProgramEvent, ReadPermission

retrieveNextProgramEvent

SIRequest retrieveNextProgramEvent(ProgramEvent event,
                                 SIRequestor requestor)
                                   throws SIException

Retrieves a event which follows the specified event.

This method delivers its results asynchronously. If the caller does not have javax.tv.service.ReadPermission(pe.getLocator()) (where pe is the next program event), this method will result in an SIRequestFailureType of DATA_UNAVAILABLE.

Parameters:

event - A reference event.

requestor - The SIRequestor to be notified when this retrieval operation completes.

Returns:

An SIRequest object identifying this asynchronous retrieval request.

Throws:

SIException - If event does not belong to this ProgramSchedule.

See Also:

ProgramEvent, ReadPermission

retrieveProgramEvent

SIRequest retrieveProgramEvent(Locator locator,
                             SIRequestor requestor)
                               throws InvalidLocatorException,
                                      SecurityException

Retrieves a program event matching the locator. Note that the event must be part of this schedule.

This method returns data asynchronously.

Parameters:

locator - Locator referencing the ProgramEvent of interest.

requestor - The SIRequestor to be notified when this retrieval operation completes.

Returns:

An SIRequest object identifying this asynchronous retrieval request.

Throws:

InvalidLocatorException - If locator does not reference a valid ProgramEvent in this ProgramSchedule.

SecurityException - If the caller does not have javax.tv.service.ReadPermission(locator).

See Also:

ProgramEvent, ReadPermission

addListener

void addListener(ProgramScheduleListener listener)

Registers a ProgramScheduleListener to be notified of changes to program events on this ProgramSchedule. Subsequent changes will be indicated through instances of ProgramScheduleEvent, with this ProgramSchedule as the event source and an SIChangeType of ADD, REMOVE, MODIFY, or CURRENT_PROGRAM_EVENT. Only changes to ProgramEvent instances p for which the caller has javax.tv.service.ReadPermission(p.getLocator()) will be reported.

This method is only a request for notification. No guarantee is provided that the SI database will detect all, or even any, changes to the ProgramSchedule, or whether such changes will be detected in a timely fashion.

If the specified ProgramScheduleListener is already registered, no action is performed.

Parameters:

listener - A ProgramScheduleListener to be notified of changes to program events on this ProgramSchedule.

See Also:

ProgramEvent, ProgramScheduleEvent, ProgramScheduleChangeType, ReadPermission

removeListener

void removeListener(ProgramScheduleListener listener)

Unregisters a ProgramScheduleListener. If the specified ProgramScheduleListener is not registered, no action is performed.

Parameters:

listener - A previously registered listener.

getServiceLocator

Locator getServiceLocator()

Reports the transport-dependent locator referencing the service to which this ProgramSchedule belongs. Note that applications may use this method to establish the identity of a ProgramSchedule after it has changed.

Returns:

The transport-dependent locator referencing the service to which this ProgramSchedule belongs.

See Also:

ProgramScheduleEvent.getProgramSchedule()