com.sun.dtv.ui
Class Plane

java.lang.Object
  com.sun.dtv.ui.Plane

All Implemented Interfaces:

ScarceResource

public abstract class Plane
extends Object
implements ScarceResource

An instance of the Screen class represents one video output signal of a TV device. If a TV device has more than one independent video output signals, one instance of this class for every signal will be needed. A single video output signal is composed out of the contents of several planes supported by the screen. Any contributing plane is an instance of a class derived from the Plane abstract class.

A given Screen may support any number of these objects as far as the API is concerned however some form of profiling may restrict this (e.g. there is usually just one background plane).

Each Plane can have several variants of setups in form of instances of PlaneSetup. Only one of those setups can be active at any point of time. The currently valid setup can be determined for any Plane using the getCurrentSetup method. Assuming an application has the sufficient rights to do so, it can also modify the currently valid setup by using the setCurrentSetup method.

By creating an instance of PlaneSetupPattern it is possible to populate criteria for the choice of the best setup by defining a number of preferences each with a priority. The implementation then matches this pattern against the range of possible setups, trying to find one which matches at least all mandatory preferences (priorities REQUIRED and REQUIRED_NOT). If this is not possible, then the method call shall fail and not return any setup. Other priorities PREFERRED and PREFERRED_NOT are not mandatory, but should be respected as much as possible.

See Also:

ScarceResource.reserve(boolean, long, com.sun.dtv.resources.ScarceResourceListener), ScarceResource.release()

Constructor Summary

protected

Plane() For use of specific plane classes subclassing Plane.

Method Summary

void	addPlaneSetupListener(PlaneSetupListener listener) Add an PlaneSetupListener to this plane.
void	addPlaneSetupListener(PlaneSetupListener listener, PlaneSetupPattern pattern) Add an PlaneSetupListener to this plane.
static void	addResourceTypeListener(ResourceTypeListener listener) Adds a ResourceTypeListener to the implementation.
void	addScarceResourceListener(ScarceResourceListener listener) Register a listener for events about changes in the state of the ownership of this plane.
PlaneSetup	getBestSetup(PlaneSetupPattern pattern) Returns the best possible setup taking into account the criteria defined in this PlaneSetupPattern or null.
PlaneSetup	getBestSetup(PlaneSetupPattern[] patterns) Returns the best possible setup taking into account the criteria defined in one of the PlaneSetupPattern objects within the array argument or null.
Capabilities	getCapabilities() Returns the Capabilities object associated with this Plane.
static Plane	getCurrentPlane() Returns the Plane the caller is displayed on.
PlaneSetup	getCurrentSetup() Returns the current PlaneSetup for this Plane.
PlaneSetup	getDefaultSetup() Returns the default PlaneSetup associated with this Plane.
String	getID() Returns this Plane's identification string.
static Plane[]	getInstances() Return the list of all existing instances of Plane, whether they are already reserved or not.
PlaneSetup[]	getSetups() Returns all available PlaneSetup objects associated with this Plane.
boolean	isAvailable() Checks whether the given resource is currently available for reservation.
void	release() Releases this resource.
void	removePlaneSetupListener(PlaneSetupListener listener) Remove an PlaneSetupListener from this plane.
static void	removeResourceTypeListener(ResourceTypeListener listener) Removes a previously attached listener.
void	removeScarceResourceListener(ScarceResourceListener listener) Remove a listener for events about changes in the state of the ownership of this plane.
void	reserve(boolean force, long timeout, ScarceResourceListener listener) Requests reservation of the given scarce resource instance.
static Plane	reserveOne(boolean force, long timeoutms, ScarceResourceListener listener) Returns a reserved instance out of the pool of all Plane instances.
boolean	setPlaneSetup(PlaneSetup setup) Set the setup for this Plane.

Methods inherited from class java.lang.Object

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

Constructor Detail

Plane

protected Plane()

For use of specific plane classes subclassing Plane.

Method Detail

getID

public String getID()

Returns this Plane's identification string.

Returns:

an identification string

getSetups

public PlaneSetup[] getSetups()

Returns all available PlaneSetup objects associated with this Plane. Some of these may be valid for this plane only at particular times or for particular modes of the plane.

Returns:

an array of PlaneSetup objects

See Also:

PlaneSetup

getDefaultSetup

public PlaneSetup getDefaultSetup()

Returns the default PlaneSetup associated with this Plane. There is only one default setup, this could be e.g. a minimal setup.

Returns:

the default PlaneSetup of this Plane

See Also:

PlaneSetup

getBestSetup

public PlaneSetup getBestSetup(PlaneSetupPattern pattern)

Returns the best possible setup taking into account the criteria defined in this PlaneSetupPattern or null.

For details of the algorithm for the selection of a setup, see getBestSetup(PlaneSetupPattern[])

Parameters:

pattern - - a PlaneSetupPattern object used to deliver criteria for a valid PlaneSetup. If this parameter is null the default setup is choosen.

Returns:

a PlaneSetup object fulfilling the criteria as specified in the PlaneSetupPattern or null if there is none.

getBestSetup

public PlaneSetup getBestSetup(PlaneSetupPattern[] patterns)

Returns the best possible setup taking into account the criteria defined in one of the PlaneSetupPattern objects within the array argument or null. The PlaneSetupPattern objects are considered in the order they appear in the parameter array.

For details of the algorithm for the selection of a setup, see getBestSetup(PlaneSetupPattern[])

Parameters:

patterns - the PlaneSetupPattern array used to deliver criteria for a valid PlaneSetup.

Returns:

a PlaneSetup object fulfilling the criteria as specified in one of the PlaneSetupPattern objects within the paramter array

getCurrentSetup

public PlaneSetup getCurrentSetup()

Returns the current PlaneSetup for this Plane.

Returns:

the current PlaneSetup for this Plane.

See Also:

PlaneSetup

setPlaneSetup

public boolean setPlaneSetup(PlaneSetup setup)
                      throws SecurityException,
                             SetupException

Set the setup for this Plane.

As the Plane of a Screen is a ScarceResource, this method can only be called by an application which has reserved this plane before using the appropriate means provided by the ScarceResource mechanism. Calling this method is also subject to the platform's security policy, and the following rules decide about a successful call:

• Choosing a setup being not valid for that plane at that time or due to a particular mode the plane is in causes an SetupException to be thrown.
• Choosing a setup that is not conflicting with any setup of one of the other planes on the same Screen causes this setup to be selected.
• Choosing a setup that conflicts with any setup of one of the other planes on this Screen not being under control of the calling application due to platform security policy causes a SecurityException to be thrown.
• Choosing a setup that conflicts with any setup of one of the other planes on this Screen not being under control of the calling application due to another application owning the right to control the other plane and the platform not giving that right to this application causes a SecurityException to be thrown.
• Choosing a setup that conflicts with any setup of one of the other planes on this Screen being under control of the calling application due to either this or no application having reserved the plane, then the setup of the other plane changes automatically (without any effect to the resource ownership of the other plane).

If the setup of another plane has been changed as a consequence to the call of this method, the change should be reflected by calling an appropriate method of the concerned plane's API.

Applications can prevent or limit changes to setups of other, not intended, planes by using constants PlaneSetupPattern.NO_GRAPHICS_IMPACT, PlaneSetupPattern.NO_SUBTITLE_IMPACT, PlaneSetupPattern.NO_VIDEO_IMPACT, PlaneSetupPattern.NO_STILLVIDEO_IMPACT and PlaneSetupPattern.NO_BACKGROUND_IMPACT in their setup patterns.

If changing the specified setup has been successful, the plane shall fire at least one PlaneSetupEvents for all currently registered listeners.

Parameters:

setup - the PlaneSetup to which this plane should be set.

Returns:

A boolean indicating whether the setup has been successfully changed. Please be aware that in case the return value is false, there is no warranty that the setup of the plane is the same one as it has been before the call

Throws:

SecurityException - if the application currently does not have sufficient rights to change the setup for this plane

SetupException - if the specified setup is either not a valid one for this plane, or if it conflicts with other planes' setups and this conflict cannot be solved

addPlaneSetupListener

public void addPlaneSetupListener(PlaneSetupListener listener)

Add an PlaneSetupListener to this plane. This listener will be notifier whenever the plane's setup will be modified. If one listener has already been added before, further calls to this method will add further references to the same listener. As a consequence, these references will then receive multiple copies of one single event.

Parameters:

listener - the PlaneSetupListener to be added to this plane.

See Also:

removePlaneSetupListener(com.sun.dtv.ui.event.PlaneSetupListener)

addPlaneSetupListener

public void addPlaneSetupListener(PlaneSetupListener listener,
                                  PlaneSetupPattern pattern)

Add an PlaneSetupListener to this plane. This listener will be notified whenever the plane's setup will be modified so that it is no longer compatible with the specified PlaneSetupPattern. If one listener has already been added before, further calls to this method will add further references to the same listener. As a consequence, these references will then receive multiple copies of one single event.

Note that if the plane setup does not match the specified pattern, then the listener should be added and a PlaneSetupEvent immediately generated for the specified PlaneSetupListener.

Parameters:

listener - the PlaneSetupListener to be added to this plane.

pattern - the PlaneSetupPattern which is to be used to determine compatibility with the plane's setup.

See Also:

removePlaneSetupListener(com.sun.dtv.ui.event.PlaneSetupListener)

removePlaneSetupListener

public void removePlaneSetupListener(PlaneSetupListener listener)

Remove an PlaneSetupListener from this plane. If the specified listener has not been registered before, the method has no effect. If multiple references to a single listener have been registered, any call to this method will only remove one reference.

Parameters:

listener - the PlaneSetupListener to be removed from this plane.

See Also:

addPlaneSetupListener(com.sun.dtv.ui.event.PlaneSetupListener), addPlaneSetupListener(com.sun.dtv.ui.event.PlaneSetupListener, com.sun.dtv.ui.PlaneSetupPattern)

addScarceResourceListener

public void addScarceResourceListener(ScarceResourceListener listener)

Register a listener for events about changes in the state of the ownership of this plane. If this listener has already been added before, further calls will add further references to the listener. As a consequence, these references will receive multiple copies of one single event.

Parameters:

listener - the object to be informed of state changes

See Also:

removeScarceResourceListener(com.sun.dtv.resources.ScarceResourceListener)

removeScarceResourceListener

public void removeScarceResourceListener(ScarceResourceListener listener)

Remove a listener for events about changes in the state of the ownership of this plane. This method has no effect if the specified listener has not been registered before.

Parameters:

listener - the object which is no longer interested

See Also:

addScarceResourceListener(com.sun.dtv.resources.ScarceResourceListener)

reserve

public void reserve(boolean force,
                    long timeout,
                    ScarceResourceListener listener)
             throws IllegalArgumentException,
                    TimeoutException

Requests reservation of the given scarce resource instance. The method will block until this instance is available. The method returns normally only if the reservation succeeded. All other cases are handled by exceptions.

First, if there is a security manager, its checkPermission method is called with the permission ScarceResourcePermission(name, "reserve"). If force is moreover set to true, then the permission is also checked on ScarceResourcePermission(name, "force").

During the reservation process, if that resource instance is already allocated, the implementation must notify the current owner of that resource about the reservation request via the ScarceResourceListener interface:

• either by ScarceResourceListener.releaseRequested() if force is false,
• or by ScarceResourceListener.releaseForced() in the other case.

The listener will be used for such notification only until this resource is released. After releasing, the implementation must not call any of the listener's interface methods.

After that first event, the implementation will proceed accordingly and release (or not) the requested resource. In case the implementation releases the resource, it will trigger a ScarceResourceListener.released() event to the original listening owner of the resource to inform him that the resource does not belong to him anymore.

The application may control the time to wait for such a resource to be available by setting timeoutms. In case the duration of the reservation exceeds the time expressed in timeoutms, a TimeoutException is thrown.

Under normal operation, resources are released using the release method. However, in the case where the application does not release resources when requested or the application is terminated, the implementation must release all resources allocated to the application to allow other applications to be notified of changes in resource allocation and to be able to reserve them. See the Resource Cleanup section of the application lifecycle.

Specified by:

reserve in interface ScarceResource

Parameters:

force - If true, this method will withdraw the resource from the current owner. If false, the implementation will block and wait until the resource is made available (using release()) or until timeoutms.

timeout - A positive amount of time in millisecond until which this method will wait for the resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.

listener - The listener to be attached to receive notification about the status of the resource.

Throws:

IllegalArgumentException - If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.

TimeoutException - If the time specified in timeoutms is over and the resource could not be reserved.

reserveOne

public static Plane reserveOne(boolean force,
                               long timeoutms,
                               ScarceResourceListener listener)
                        throws IllegalArgumentException,
                               TimeoutException

Returns a reserved instance out of the pool of all Plane instances. This method either returns with the instance or throws an exception according to the situation.

This method behaves exactly as the reserve() method.

Parameters:

force - If true, this method is allowed to withdraw any given resource from its current owner. If false, the implementation will block and wait until a resource of the given type is made available (using release()) or until timeoutms milliseconds.

timeoutms - A positive amount of time in millisecond until which this method will wait for any resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.

listener - The listener to be attached to receive notification about the status of the resource.

Returns:

The instance of type Plane that has been reserved.

Throws:

IllegalArgumentException - If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.

TimeoutException - If the time specified in timeoutms is over and the resource could not be reserved.

See Also:

reserve(boolean, long, com.sun.dtv.resources.ScarceResourceListener)

release

public void release()

Releases this resource.

The resource will be made available to another application across the platform. After calling this method, it is no more possible to interact with the given resource: calls to critical methods of that scarce resource must be ignored and may throw IllegalStateException. This assertion is valid and the behavior required for any class implementing the ScarceResource interface. In order to interact again with the given resource, the application must call the reserve() method and become the owner again.

The implementation may dispose any system resources that this object is using. After the implementation must not call any of the methods of the listener that was attached at reservation time.

If the resource was already available (i.e. not reserved), this method does nothing.

Specified by:

release in interface ScarceResource

isAvailable

public boolean isAvailable()

Checks whether the given resource is currently available for reservation. The returned value gives the current situation and does not guarantee that the resource will still be available at a later moment e.g. at reservation time: another application may have taken that resource in the meantime.

Specified by:

isAvailable in interface ScarceResource

Returns:

A boolean set to true if the given resource is currently available for reservation.

getCapabilities

public Capabilities getCapabilities()

Returns the Capabilities object associated with this Plane.

Returns:

the Capabilities object associated with this Plane

getCurrentPlane

public static Plane getCurrentPlane()

Returns the Plane the caller is displayed on.

Returns:

the current plane

getInstances

public static Plane[] getInstances()

Return the list of all existing instances of Plane, whether they are already reserved or not.

Returns:

list of all existing instances of Plane

addResourceTypeListener

public static void addResourceTypeListener(ResourceTypeListener listener)
                                    throws NullPointerException

Adds a ResourceTypeListener to the implementation. Whenever a reserve() or a release() is called on any resources of the same type, the implementation will call the listener's corresponding methods.

Parameters:

listener - The listener that is triggered for events on resources of the same type.

Throws:

NullPointerException - If listener is null.

See Also:

removeResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)

removeResourceTypeListener

public static void removeResourceTypeListener(ResourceTypeListener listener)
                                       throws NullPointerException

Removes a previously attached listener. If the listener was not attached before, this method does nothing.

Parameters:

listener - The listener that is triggered for events on resources of the same type.

Throws:

NullPointerException - If listener is null.

See Also:

addResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)