javax.tv.xlet.package.html Maven / Gradle / Ivy
Provides interfaces used by applications and the application manager
to communicate. This package defines two entities: the
Xlet and the XletContext. The central
function of this set of interfaces is to model and manage the states
an application can be in. Xlet is an interface that must
be implemented by the primary class of an application. When an
application is loaded, one instance of this primary class is created.
The application is controlled via method calls on this instance.
Methods of Xlet are used by the application manager to
deliver state change requests to the application. An application is
provided with an instance of XletContext, which it can
use to deliver state change notifications to the application manager.
Each Xlet receives its own instance of
XletContext. An application might have a graphical
representation, or it might be a headless "service."
This interface allows an application manager to create,
initialize, start, pause, and destroy an application.
The following is a description of the Xlet state model.
Note that an Xlet is not required to maintain an explicit
internal model of its state; however it must nonetheless behave as
described by the following model.
State Name
Description
Loaded
The application has been loaded but has not been initialized.
This state is entered:
- After the application's
Xlet instance has been
created. This causes the xlet's no-argument
constructor to be called. The application typically does little or no
initialization in this step. If an exception is thrown from the
constructor, the application is considered to be destroyed; it will
receive no further Xlet callbacks, and its resources will
be eligible for reclamation.
Note: This state is entered only once per application
instance.
Paused
The application is initialized and quiescent.
It should keep itself ready to become
active quickly. As a secondary goal, it should attempt to minimize
resource usage.
This state is entered:
- From the Loaded state after the {@link Xlet#initXlet} method
returns successfully.
- From the Active state after the {@link Xlet#pauseXlet}
method returns successfully.
- From the Active state upon entering the
{@link XletContext#notifyPaused} method.
Active
The application is functioning normally and executing.
This state is entered:
- From the Paused after the {@link Xlet#startXlet} method
returns successfully.
Note: Applications that are in the Paused state may
identify to the application manager that they would like to be brought
into the Active state by calling
{@link XletContext#resumeRequest}. Calling this method provides
no guarantee that their startXlet method will be called.
Destroyed
The application has released all of its resources and terminated.
This state is entered:
- When the
Xlet's {@link Xlet#destroyXlet} method
returns successfully. The destroyXlet() method shall
release all resources held and perform any necessary clean up so the
application may be garbage collected.
- Upon entering the {@link XletContext#notifyDestroyed}
method. The
Xlet must perform its clean-up actions before
calling the notifyDestroyed() method.
- When the
Xlet fails to respond to a state change
notification within a reasonable amount of time. The precise length
of time is implementation dependent.
Note: This state is only entered once, and is the terminal
state. Once an application is in the destroyed state, all of its
resources are eligible for reclamation.
Each application will be loaded by a unique class loader, and will get
a distinct copy of each user defined class. It is impossible for
xlets to communicate by sharing instances through static data members
of user defined classes.
A Java TV API implementation must include a mechanism for loading,
launching and destroying xlets.
If a suitable API is available on the target platform, applications
may create their own additional classloaders. Each such classloader
must have its application's classloader as an ancestor.