javax.tv.service.navigation.ServiceList 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.navigation;
import javax.tv.locator.*;
import javax.tv.service.Service;
/**
* ServiceList represents an ordered list of
* Service objects based on a specific grouping rule
* defined by a ServiceFilter. The objects in a
* ServiceList are numbered from 0 to size()
* -1.
*
* A ServiceList is immutable. In other words,
* once a ServiceList instance is created, the elements
* in the list and their order will never change. All classes that
* implement the ServiceList interface are required to
* maintain this property.
*
* @see javax.tv.service.Service
* @see ServiceFilter
* @see #size
*
*/
public interface ServiceList
{
/**
* Generates a new ServiceList containing the
* same elements as the current list, sorted in ascending
* order by service name. The sort order is implementation dependent,
* but should be sensible when presented to a user.
*
* @return A ServiceList sorted by service name.
*
* @see Service#getName
*/
public ServiceList sortByName();
/**
* Generates a new ServiceList containing the
* same elements as the current list, sorted in ascending
* order by service number.
*
* @return A ServiceList sorted by service number.
*
* @throws SortNotAvailableException If any of the
* Service objects in this ServiceList
* do not implement the ServiceNumber interface.
*
* @see javax.tv.service.ServiceNumber
*/
public ServiceList sortByNumber() throws SortNotAvailableException;
/**
* Reports the Service corresponding to the specified
* locator if it is a member of this list.
*
* @param locator Specifies the Service to be searched for.
*
* @return The Service corresponding to
* locator, or null if the
* Service is not a member of this list.
*
* @throws InvalidLocatorException If locator does not
* reference a valid Service.
*/
public Service findService(Locator locator) throws InvalidLocatorException;
/**
* Creates a new ServiceList object that is a subset of
* this list, based on the conditions specified by a
* ServiceFilter object. This method may be used to
* generate increasingly specialized lists of Service
* objects based on multiple filtering criteria. If the filter is
* null, the resulting ServiceList will be
* a duplicate of this list.
*
* Note that the accept method of the given
* ServiceFilter will be invoked for each
* Service to be filtered using the same application
* thread that invokes this method.
*
* @param filter A filter constraining the requested service list,
* or null.
*
* @return A ServiceList object created based on the
* specified filtering rules.
*
* @see ServiceFilter#accept
*/
public ServiceList filterServices(ServiceFilter filter);
/**
* Generates an iterator on the Service elements
* in this list.
*
* @return A ServiceIterator on the
* Services in this list.
*/
public ServiceIterator createServiceIterator();
/**
* Tests if the indicated Service object is contained
* in the list.
*
* @param service The Service object for which to search.
*
* @return true if the specified Service
* is member of the list; false otherwise.
*/
public boolean contains(Service service);
/**
* Reports the position of the first occurrence of the
* indicated Service object in the list.
*
* @param service The Service object for which to search.
*
* @return The index of the first occurrence of the
* service, or -1 if service
* is not contained in the list.
*/
public int indexOf(Service service);
/**
* Reports the number of Service objects in the list.
*
* @return The number of Service objects in the list.
*/
public int size();
/**
* Reports the Service at the specified index position.
*
* @param index A position in the ServiceList.
*
* @return The Service at the specified index.
*
* @throws IndexOutOfBoundsException If index < 0 or
* index > size()-1.
*/
public Service getService(int index);
/**
* Compares the specified object with this ServiceList
* for equality. Returns true if and only if the
* specified object is also a ServiceList, both lists
* have the same size, and all corresponding pairs of elements in
* the two lists are equal. (Two elements e1 and e2 are equal if
* (e1==null ? e2==null : e1.equals(e2)).) In other words, two lists
* are defined to be equal if they contain the same elements in the
* same order.
*
* @param o The object to be compared for equality with this list.
*
* @return true if the specified object is equal to
* this list; false otherwise.
*/
public boolean equals(Object o);
/**
* Provides the hash code value for this ServiceList.
* Two ServiceList objects that are equal will have
* the same hash code.
*
* @return The hash code value of this ServiceList.
*/
public int hashCode();
}