javax.tv.service.navigation.ServiceList Maven / Gradle / Ivy
/*
* @(#)ServiceList.java 1.27 00/10/09
*
* 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.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.
*
* @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();
}