javax.tv.service.guide.ProgramSchedule Maven / Gradle / Ivy
/*
* @(#)ProgramSchedule.java 1.40 00/09/27
*
* Copyright 1998-2000 by Sun Microsystems, Inc.,
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
* All rights reserved.
*
* This software is the confidential and proprietary information
* of Sun Microsystems, Inc. ("Confidential Information"). You
* shall not disclose such Confidential Information and shall use
* it only in accordance with the terms of the license agreement
* you entered into with Sun.
*/
package javax.tv.service.guide;
import javax.tv.service.SIRequest;
import javax.tv.service.SIRequestor;
import java.util.Date;
import javax.tv.service.SIException;
import javax.tv.locator.*;
import javax.tv.service.SIChangeListener;
/**
* 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 java.util.Date java.util.Date
* @see javax.tv.service.guide.ProgramEvent
* @see javax.tv.service.ReadPermission
*/
public interface ProgramSchedule {
/**
* 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.
*
* @param requestor The SIRequestor to be notified
* when this retrieval operation completes.
*
* @return An SIRequest object identifying this
* asynchronous retrieval request.
*
* @see ProgramEvent
* @see javax.tv.service.ReadPermission
*/
public SIRequest retrieveCurrentProgramEvent(SIRequestor requestor);
/**
* 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.
*
* @param time The time of the program event to be retrieved.
*
* @param requestor The SIRequestor to be notified
* when this retrieval operation completes.
*
* @return An SIRequest object identifying this
* asynchronous retrieval request.
*
* @throws SIException If time does not represent a
* future time value.
*
* @see ProgramEvent
* @see javax.tv.service.ReadPermission
*/
public SIRequest retrieveFutureProgramEvent(Date time,
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.
*
* @param begin Time identifying the beginning of the interval.
*
* @param end Time identifying the end of the interval.
*
* @param requestor The SIRequestor to be notified
* when this retrieval operation completes.
*
* @return 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 ProgramEvent
* @see javax.tv.service.ReadPermission
*/
public SIRequest retrieveFutureProgramEvents(Date begin,
Date end,
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.
*
* @param event A reference event.
*
* @param requestor The SIRequestor to be notified
* when this retrieval operation completes.
*
* @return An SIRequest object identifying this
* asynchronous retrieval request.
*
* @throws SIException If event does not belong to this
* ProgramSchedule.
*
* @see ProgramEvent
* @see javax.tv.service.ReadPermission
*/
public SIRequest retrieveNextProgramEvent(ProgramEvent event,
SIRequestor requestor)
throws SIException;
/**
* Retrieves a program event matching the locator. Note that
* the event must be part of this schedule.
*
* This method returns data asynchronously.
*
* @param locator Locator referencing the ProgramEvent
* of interest.
*
* @param requestor The SIRequestor to be notified
* when this retrieval operation completes.
*
* @return An SIRequest object identifying this
* asynchronous retrieval request.
*
* @throws InvalidLocatorException If locator does not
* reference a valid ProgramEvent in this
* ProgramSchedule.
*
* @throws SecurityException If the caller does not have
* javax.tv.service.ReadPermission(locator).
*
* @see ProgramEvent
* @see javax.tv.service.ReadPermission
*/
public SIRequest retrieveProgramEvent(Locator locator,
SIRequestor requestor)
throws InvalidLocatorException, SecurityException;
/**
* 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.
*
* @param listener A ProgramScheduleListener to be notified of
* changes to program events on this ProgramSchedule.
*
* @see ProgramEvent
* @see ProgramScheduleEvent
* @see ProgramScheduleChangeType
* @see javax.tv.service.ReadPermission
*/
public void addListener(ProgramScheduleListener listener);
/**
* Unregisters a ProgramScheduleListener. If the
* specified ProgramScheduleListener is not registered, no
* action is performed.
*
* @param listener A previously registered listener.
*/
public void removeListener(ProgramScheduleListener listener);
/**
* 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.
*
* @return The transport-dependent locator referencing the service to
* which this ProgramSchedule belongs.
*
* @see ProgramScheduleEvent#getProgramSchedule
**/
public Locator getServiceLocator();
}