org.dvb.spi.selection.SelectionProvider Maven / Gradle / Ivy


package org.dvb.spi.selection;

import org.dvb.spi.SystemBoundProvider;
//import org.dvb.spi.si.simple.ProgramReference;
//import org.dvb.spi.si.simple.ServiceComponentDescription;
import javax.tv.service.selection.ServiceContext;
import javax.tv.service.selection.ServiceContextEvent;
import javax.tv.media.MediaSelectControl;
import javax.tv.media.MediaSelectEvent;
import javax.tv.locator.Locator;


/**
 * A provider of service selection.  For example, a SelectionProvider
 * can be installed in an always-running service-unbound xlet to
 * provide the ability to reach services that do not have standarized
 * SI signalling in an IPTV network.
 * 
 * The process for determining which Provider (if any) shall be used
 * to present a transport independent service is defined by the following 
 * steps in the order given.
 * 

 * 1) Consult the service list. If the service appears in the service
 * list then make an selection between the available sources of that
 * Service as defined by ServiceContext.select(Service).
 * 

 * 2) If there one Provider registered to support the locator scheme
 * of the locator for the Service, ask that Provider to present that
 * service. The service selection operation shall fail if the provider
 * cannot present it.
 * 

 * 3) If more than one Provider has registed as supporting the locator
 * scheme of the locator for the Service, offer the Service to each 
 * Provider in turn until either one of them does not fail or no more
 * Providers are available in which case the service selection operation
 * shall fail.
 * 

 * NOTE: If the performance penalty of polling multiple Providers
 * for the same locator scheme is undesirable, service providers / operators
 * using multiple Providers should ensure they use different Locator schemes.
 * 

 * Providers should select the transport dependent locators
 * returned such that there is no collision the transport dependent
 * locators returned by other Providers that may offer the same 
 * transport independent service. Where an MHP terminal is managed
 * by a service provider / operator, the service provider / operator
 * should enforce this if they permit more than one Provider to be
 * installed.
 * 

 * Where there is a collision and a transport dependent locator
 * can be accessed by more than one Provider, the selection of 
 * which to use is implementation dependent.
 * 
 * 
A SelectionProvider may inform the implementation of the
 * actual location of a service by two mechanisms.
 * 

 * For services which are already present in the network,
 * the actual location can be passed in ServiceReference
 * objects. These can be provided by the getServiceList
 * method when a provider is first installed and later by
 * the SelectionProviderContext. For these services, the
 * implementation shall use this actual location to present
 * the service without calling the select method. A session
 * shall be created using the ServiceReference used to present
 * the service in order that the provider can be notified
 * when the service is no longer used. The session instance
 * should be created once the platform has started finding
 * the service (e.g. during tuning or after sending an IGMP
 * join request) in order to avoid delaying the presentation
 * of the service. 
 * 
For services whose actual location is not passed
 * in a ServiceReference (e.g. services not already present
 * in the network), the implementation shall use the select
 * method to obtain the actual location.
 * 
 * The mechanism by which the actual location of a service
 * is determined may change dynamically, e.g. as the set of
 * services available in the network changes.
 *
 * @see org.dvb.spi.Provider#getServiceProviderInterfaces()
 * @since MHP 1.1.3
 **/


public interface SelectionProvider extends SystemBoundProvider {

    /** 
     * Called by the platform to register its handler for events
     * originating in the provider. This method shall be called
     * after providerRegistered and before any other methods on
     * the provider are called. Only one handler can be registered
     * at any one time.
     * @param c the handler
     **/
    public void init(SelectionProviderContext c);

    /**
     * Give a list of the services provided by this provider.  
     * The services returned from this method shall be merged into the platform
     * service list as returned by javax.tv.service.SIManager.filterServices (null).
     * Where the transport independent identification of a service is equal to one
     * already in the service list then that transport independent service shall
     * acquire an additional transport dependent service.
     * Where the transport independent identification of a service is not equal to
     * one already in the service list, a new service shall be added to the service
     * list and SIChangeEvents generated to appropriate listeners.
     * The list of services returned shall include both those
     * where the actual location is returned in the ServiceReference
     * and those where the actual location is to be returned from
     * a later call to the select method.
     * @return a list of ServiceReference instances.
     *
     * @see  org.dvb.spi.selection.SelectionProviderContext#serviceListChanged(ServiceReference[])
     **/
    public ServiceReference[] getServiceList();

    /**
     * Called by the platform to create a session to manage the presentation
     * of a service. A new session shall be created for each service to be
     * presented by a provider.
     * @param service the service whose presentation is managed through this session 
     * @return a session
     */
    public SelectionSession newSession(ServiceReference service);


    /**
     * Returns the list of locator schemes handled by this provider.
     * This list should not change over time; it is expected that platforms
     * will usually call this method exactly once, after installation of
     * a provider.  There is no method to unregister
     * a scheme other than unregistering the provider.
     **/
    public LocatorScheme[] getSupportedLocatorSchemes();



    /**
     * Called by the terminal to request service description
     * information from an SI source.
     * The output shall be returned in an array of the same size
     * and order as the input. If information is not available on
     * any service listed in the input then the corresponding
     * entry in the results array shall be null.
     *
     * @param services  References
     * identifying the services whose descriptions are requested
     *
     * @return an array of service descriptions
     */
    public ServiceDescription[] getServiceDescriptions( 
	    ServiceReference[] services);
}