ProgramSchedule

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
`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()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD