javax.microedition.broadcast.platform
Class PlatformProviderSelector

java.lang.Object
  javax.microedition.broadcast.platform.PlatformProviderSelector

public class PlatformProviderSelector
extends java.lang.Object

PlatformProviderSelector provides the methods for discovering the underlying broadcast platform providers and selecting one of them for use. A PlatformProvider selection establishes the source, communication protocol and the physical transmission medium of the broadcast services.

By default, a platform provider is selected in the beginning of the application lifecycle. In very rare cases, for example, if the broadcast receiver has never been used before after the purchase, a PlatformProvider might not selected. In general case, the implementation remembers the previous PlatformProvider selection (independently of the way the selection was made - by a Java application or by a native application). However, it is a good idea to use getCurrentProvider() method to check if there is a selected provider in the beginning of the application.

When selecting a PlatformProvider, there are two ways to identify the PlatformProvider before the actual selection. The first way is to first use discover() method to search for available providers, then pick one from getAvailableProviders() and select that by select(PlatformProvider) method; the alternative way, that can be used only if the application knows the frequency and the id of the provider beforehand, is to create a PlatformProvider instance with createPlatformProvider(int, long, java.lang.String) method and then select that by select(PlatformProvider) method.

The device might have a default PlatformProvider that can be queried by using the getDefaultProvider() method.

See Also:

ServiceContext, ServiceGuide

Method Summary

static void	abort() Stops the current search for the available platform providers.
static void	addListener(PlatformProviderSelectorListener ppl) Registers a listener.
static PlatformProvider	createPlatformProvider(int frequency, long id, java.lang.String name) Instantiates a PlatformProvider directly based on the broadcast frequency and the ID number.
static void	discover() Starts a search for the available platform providers.
static PlatformProvider[]	getAvailableProviders() Returns available PlatformProviders (that have been found by discovering).
static PlatformProvider	getCurrentProvider() Queries the current platform provider.
static java.util.Date	getCurrentProviderDate() Returns the current time of the selected broadcast network provider.
static PlatformProvider	getDefaultProvider() Returns the default PlatformProvider.
static void	removeListener(PlatformProviderSelectorListener ppl) Unregisters a listener.
static void	select(PlatformProvider pp) Selects a platform provider.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

abort

public static void abort()

Stops the current search for the available platform providers. If there is no currently active discovery, the method does nothing. It is implementation dependent if the array returned from getAvailableProviders contains the found PlatformProviders from the aborted discovery or the found PlatformProviders from the previous discovery or a combination of them.

When discovery is aborted PlatformProviderSelectorListener.update() is called before this method returns to notify the reached progress, number of found service providers and that the discovery is not continuing.

addListener

public static void addListener(PlatformProviderSelectorListener ppl)

Registers a listener.

Parameters:

ppl - The listener to add. If null is given or if the given listener is already added, the method is silently ignored.

createPlatformProvider

public static PlatformProvider createPlatformProvider(int frequency,
                                                      long id,
                                                      java.lang.String name)
                                               throws UnsupportedOperationException

Instantiates a PlatformProvider directly based on the broadcast frequency and the ID number.

This method can be used in place of discover() and getAvailableProviders() to identify a provider manually, if the application has direct access to the available frequency and ID. This creation method does not do any kind of validation or selection of the PlatformProvider; it just instantiates a PlatformProvider instance that can be used with select method, which does the validation and selection if the frequency and the ID information matches with an actual provider in broadcast.

Parameters are validated only if manual identification of PlatformProviders is supported.

Parameters:

frequency - The broadcast frequency of the provider in kilohertz.

id - The ID of the provider.

name - The name of the provider. The name is not used as identifier when selecting this provider, but it is only stored for toString method of the PlatformProvider. When this provider is selected, the name will be replaced by the name transmitted in broadcast.

Returns:

The PlatformProvider given the information;

Throws:

UnsupportedOperationException - if the implementation does not support manually identifying PlatformProviders.

java.lang.IllegalArgumentException - if the given frequency is zero or negative number

java.lang.NullPointerException - if name is null.

discover

public static void discover()

Starts a search for the available platform providers.

This method updates the list of available service providers. Result is the best estimation of the available service providers after the discovery has been completed. For instance, the list may be unchanged when there is no radio coverage.

The mechanism to discover the available platform providers is implementation dependent. For example, some implementations may perform a frequency scan and others may be based on a direct reception of the frequency table via a mobile link. Because of this, the time it takes for the discovery process may vary greatly across different implementations.

This method is asynchronous and applications should use a PlatformProviderSelectorListener to monitor the progress. The listener is notified at least once during each discovery: when discovery is completed or when discovery is aborted.

Discovery is typically a mutually exclusive operation while a ServiceContext is in PRESENTING or in PRESENTATION_PENDING state. Therefore, you might get RESOURCE_UNAVAILABLE event to ServiceContextListener when using this method. However, selected platform remains selected after the discover finishes if the platform is still available.

Calling discover again while another discover is in progress is a no-op.

See Also:

PlatformProviderSelectorListener

getAvailableProviders

public static PlatformProvider[] getAvailableProviders()

Returns available PlatformProviders (that have been found by discovering). The list returned might change during the discovering. The list might be non-empty even in the beginning of the lifecycle of the application, since the implementation might remember the available platform providers from the previous runs of the application or native applications can also affect this list.

Returns:

available PlatformProviders in the order they were found in the latest discovering. If no platform providers are available the returned array will have a length of zero.

getCurrentProvider

public static PlatformProvider getCurrentProvider()

Queries the current platform provider. If no platform provider has been selected, null will be returned. The implementation might remember the previous selection from a previous run of a Java or a native application.

Returns:

the currently selected platform provider or null if no platform provider has been selected

getCurrentProviderDate

public static java.util.Date getCurrentProviderDate()

Returns the current time of the selected broadcast network provider.

Returns:

The current network's time. The return value must not be null.

Throws:

java.lang.IllegalStateException - if there is no selected broadcast network provider.

getDefaultProvider

public static PlatformProvider getDefaultProvider()
                                           throws BroadcastServiceException

Returns the default PlatformProvider.

Returns:

The default PlatformProvider. The return value must not be null.

Throws:

BroadcastServiceException - if the implementation does not have a default platform provider.

removeListener

public static void removeListener(PlatformProviderSelectorListener ppl)

Unregisters a listener.

Parameters:

ppl - The listener to unregister. If null is given or if the given listener is already removed, the method is silently ignored.

select

public static void select(PlatformProvider pp)

Selects a platform provider.

If there is a platform provider previously selected, it will be de-selected. And any ServiceGuides that are associated with the previous platform provider will be invalidated. After each call to select, applications should obtain a new set of ServiceGuides. See ServiceGuide.getDefaultServiceGuide() and ServiceGuide.getAllServiceGuides().

This method may take some time to complete.

Throws:

java.lang.NullPointerException - if the argument is null.

java.lang.IllegalArgumentException - the given PlatformProvider is not available