|
|||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
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 |
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 following section introduces the basic concepts and then explores a few scenarios to illustrate combinations
or broadcast application versus resident application execution.
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. Given the Service
, the client can recover
its locator:
public Locator getLocator()
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(Locator selection) throws InvalidLocatorException, java.lang.SecurityException, java.lang.IllegalStateException
The semantics of select()
are that the implementation first examines the
locator of the signature. If the locator is found to be valid, the operation
returns. The implementation does not stall while it attempts to allocate
resources to download the service, and then attempts 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.)