javax.tv.service.guide.ProgramSchedule Maven / Gradle / Ivy
/**
This is not an official specification document, and usage is restricted.
NOTICE
(c) 2005-2008 Sun Microsystems, Inc. All Rights Reserved.
Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below.
Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative use only. For example,
this file and any files generated from it may be used to generate other documentation,
such as a unified set of documents of API signatures for a platform
that includes technologies expressed as Java APIs.
This file may also be used to produce "compilation stubs,"
which allow applications to be compiled and validated for such platforms.
By contrast, no permission is given for you to incorporate this file,
in whole or in part, in an implementation of a Java specification.
Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.
This work corresponds to the API signatures of JSR 927: Java TV API 1.1.1.
In the event of a discrepency between this work and the JSR 927 specification,
which is available at http://www.jcp.org/en/jsr/detail?id=927, the latter takes precedence.
*/
package javax.tv.service.guide;
import javax.tv.locator.*;
import javax.tv.service.SIRequest;
import javax.tv.service.SIRequestor;
import java.util.Date;
import javax.tv.service.SIException;
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(javax.tv.service.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,
javax.tv.service.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,
javax.tv.service.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,
javax.tv.service.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,
javax.tv.service.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();
}