Provides a mechanism for GEM applications to control internet clients that may be present on an GEM such as a web browser or email client.

This package provides a mechanism for GEM applications to control internet clients that may be present on an GEM such as a web browser or email client. The API makes no assumptions about whether an internet client and downloaded GEM application can run simultaneously, and in some cases starting an internet client may result in the calling application being killed.

The API consists of two main class hierarchies. InternetClientService and its clients provide a mechanism to get a locator for a resident internet client so that it can be started, and also provide any functionality that does not require the client to be started. This can include adding bookmarks or getting the capabilities of the clients. The second major part of the API is the InternetClient class and its subclasses. These provide an interface to a running instance of an internet client and support the operations that can only be carried out when the client is running.

The internet client API uses the JavaTV service navigation API for accessing resident applications. Any effect that the invocation of a resident internet client has on the lifecycle of a downloaded application is dependent on the service context in which the resident application is started (using ServiceContext.select() ). If the internet client is started in the same service context as the downloaded application, then the downloaded application will be terminated, following the usual semantics of the service selection API. The basic concepts are introduced below and then a few scenarios are explored to illustrate combinations or broadcast application versus resident application execution.

Concepts

The first implication of resident applications is that it should be feasible for broadcast applications to isolate, browse, and select such services. The collection of javax.tv.service.* packages provides the framework for the solution to this requirement.

The class ServiceType in the javax.tv.service package defines various kinds of services. This is extended in this API to provide additional service types for Internet clients. The javax.tv framework lets a client filter the services known to a platform to create a ServiceCollection. The client would first create an instance of ServiceTypeFilter

	public ServiceTypeFilter(ServiceType type)

where the ServiceType in the signature would be the instance for the resident service in question. The client would then filter the services known to the platform to isolate the resident services of this type. The ServiceCollection interface provides the filter operation.

	public ServiceCollection createServiceCollection(ServiceFilter filter)

Given the ServiceCollection, the client can iterate over the resident services to find a specific resident service. The last step is to select() the resident service. The ServiceContext interface of the javax.tv.service.selection package provides the operation:

	public void select(Service selection)
		throws java.lang.SecurityException

The select() method is asynchronous and returns before attempting to allocate resources to execute the service.

If the implementation determines that it can not realize the service due to scarce resources, it forwards a SelectionFailedEvent (of the javax.tv.service. selection package) with the reason code INSUFFICIENT_RESOURCES. The ServiceContextListener interface fields the event:

	public void receiveServiceContextEvent(ServiceContextEvent e)

Thus the client should implement an instance of the ServiceContextListener interface and register interest in service context events. The ServiceContext interface provides the mechanism:


	public void addListener(ServiceContextListener listener)

		throws java.lang.IllegalStateException

The semantics of a ServiceContext are that at most a single Service can execute within a ServiceContext at a time. Since the premise is that a broadcast service selects a resident service, there are two scenarios of interest.

The first scenario presumes that the broadcast service wants to select the resident service but not survive. It expects the selection to cause its termination. The broadcast service in this case should create an instance of ServiceContextFactory. The operation on ServiceContextFactory itself is:

	public static ServiceContextFactory getInstance()

The broadcast application then requests the service contexts that are visible to the broadcast application:

	public abstract ServiceContext getServiceContext(XletContext ctx)

which returns its ServiceContext. The broadcast application selects the resident application within its service context:

	public void select(Locator selection)
		throws InvalidLocatorException, java.lang.SecurityException,
			java.lang.IllegalStateException

which causes the broadcast application to terminate.

The premise of the second scenario is that the broadcast application wants to survive the selection of the resident service. In this case the broadcast again creates a ServiceContextFactory but then creates a ServiceContext which is not its ServiceContext:

	public abstract ServiceContext createServiceContext()
		throws InsufficientResourcesException,
			java.lang.SecurityException

The broadcast application selects the resident application. Since the operation is on a ServiceContext that is not its ServiceContext, the broadcast application survives the selection.

One subtle aspect of the invocation patterns is that the platform does not know whether the broadcast application will attempt to select a resident application versus another broadcast application until the broadcast application invokes the select() operation. For example, assume the platform supports a single broadcast application plus a single resident application. Further assume that, after the broadcast application creates a second ServiceContext, it selects a second broadcast application rather than a resident application. If the locator is valid, the operation succeeds, but the broadcast application then receives a SelectionFailedEvent.

Likewise assume the platform supports multiple broadcast applications but not (for the present) a resident application. If the broadcast application selects a resident application, and if the locator is valid, the operation succeeds, but the broadcast application then receives a SelectionFailedEvent. (The second case is rather improbable. If the platform does not support resident applications, it is not clear how the broadcast application could obtain a valid locator to a broadcast application. The platform would have to support resident applications in concept, but not at the instant the broadcast applications selects a resident application.)