Package org.dvb.internet

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

See:
          Description

Interface Summary
EmailClient Interface supporting the operations required on an email client.
EmailClientService Service representing the resident email client
InternetClient Base interface for the internet clients.
InternetClientListener Interface for objects that wish to receive InternetClientEvents
InternetClientService The base class for the interface to resident applications that are supported by the internet access profile.
UsenetClient This interface supports the operations required on a Usenet news client.
UsenetClientService Service representing the resident usenet news client
WWWBrowser This interface provides support for the operations required on an WWW browser.
WWWBrowserService Service representing a resident WWW browser
 

Class Summary
CancelledByUserEvent Event indicating that an operation on an internet client failed because the operation was canceled by the user
HomePagePermission This class is for permissions related to the ability for an MHP application to set the home page of a WWW browser in the internet access profile.
InternetClientEvent Base class for all status events from internet clients.
InternetClientFailureEvent Event indicating that an operation on an internet client failed.
InternetClientSuccessEvent Event indicating that an operation on an internet client succeeded
InternetServiceFilter InternetServiceFilter represents a service type for a particular kind of internet client.
InternetServiceType Class representing the additional service types available in the Internet Access profile.
PermissionDeniedEvent Event indicating that an operation on an internet client failed due to the specified URL not being accessible by the client due to access controls on the server.
URLUnavailableEvent Event indicating that an operation on an internet client failed due to the specified URL not being available.
 

Exception Summary
ClientNotRunningException Exception thrown when a method of InternetClient or one of its subclasses is called while the client is not running, for instance if the client has been terminated by the user.
EntryExistsException Exception generated when an application tries to add a bookmark or address book entry that already exists
 

Package org.dvb.internet Description

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

This package provides a mechanism for MHP applications to control internet clients that may be present on an MHP such as a web browser or email client. The API makes no assumptions about whether an internet client and downloaded MHP 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.)