com.sun.dtv.ui
Class Screen

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

All Implemented Interfaces:

ScarceResource

public class Screen

extends Object

implements ScarceResource

This class is a representation of a TV screen. Such a screen consists on a number of planes dedicated for several purposes like video, graphics, subtitles and background. All of these will be combined together before being displayed. In case a platform supports more than one display it would handle an instance of this class for each. Audio output is also supported where needed. Also, there is a number of UserInputDevices dedicated to this Screen. These user input devices can be used to control this particular screen.

Although every plane of a screen device has it's own setup, all of them must have certain properties in common. Conflicting setups of several planes for the same screen are not supported.

Method Summary

void	addKeyboardToScreen() Add a keyboard as user input device to this Screen.
void	addMouseToScreen() Add a mouse as user input device to this Screen.
void	addPlane(Plane plane) Adds the specified plane to this screen.
void	addRemoteControlToScreen() Add a remote control as user input device to this Screen.
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 screen.
Plane[]	getAllPlanes() Returns a list of all planes for this screen.
static Screen[]	getAvailableScreens() Returns all Screens in this system.
PlaneSetup	getBestSetup(PlaneSetupPattern[] patterns) Returns a PlaneSetup from an Plane which is present on this Screen that best matches at least one of the specified PlaneSetupPatterns.
PlaneSetup[]	getCoherentPlaneSetups(PlaneSetupPattern[] patterns) Return a coherent set of PlaneSetups matching a set of patterns.
static Screen	getCurrentScreen() Returns the Screen the caller is displayed on.
static Screen	getDefaultScreen() Returns the default Screen for this application.
static Screen[]	getInstances() Return the list of all existing instances of Screen, whether they are already reserved or not.
Keyboard	getKeyboard() Returns the keyboard which can be used to control this screen if any.
Mouse	getMouse() Returns the mouse which can be used to control this screen if any.
RemoteControl	getRemoteControl() Returns the TV remote control which can be used to control this screen if any.
Dimension	getScreenAspectRatio() Returns the aspect ratio of the video output signal represented by this Screen.
UserInputDevice[]	getSupportedUserInputDevices() Returns a list of UserInputDevices that are associated to this Screen.
UserInputEventManager	getUserInputEventManager() Return the UserInputEventManager of this screen.
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.
boolean	isKeyboardSupported() Indicates whether this screen can be controlled using a keyboard.
boolean	isMouseSupported() Indicates whether this screen can be controlled using a mouse.
boolean	isRemoteControlSupported() Indicates whether this screen can be controlled using a TV remote control.
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.
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 screen.
void	reserve(boolean force, long timeout, ScarceResourceListener listener) 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.
static Screen	reserveOne(boolean force, long timeoutms, ScarceResourceListener listener) Returns a reserved instance out of the pool of all Screen instances.
boolean	setCoherentPlaneSetups(PlaneSetup[] setups) Modify the settings for a set of Planes, based on their PlaneSetups supplied.

Methods inherited from class java.lang.Object

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

Method Detail

getAvailableScreens

public static Screen[] getAvailableScreens()

Returns all Screens in this system.

Returns:

an array of Screens representing all Screens in this system.

getDefaultScreen

public static Screen getDefaultScreen()

Returns the default Screen for this application.

Returns:

the default Screen for this application.

addKeyboardToScreen

public void addKeyboardToScreen()

Add a keyboard as user input device to this Screen. As a consequence, implementation should create a Keyboard instance and add it to this screen. The user is not allowed to create a Keyboard instance directly.

addMouseToScreen

public void addMouseToScreen()

Add a mouse as user input device to this Screen. As a consequence, implementation should create a Mouse instance and add it to this screen. The user is not allowed to create a Mouse instance directly.

addRemoteControlToScreen

public void addRemoteControlToScreen()

Add a remote control as user input device to this Screen. As a consequence, implementation should create a RemoteControl instance and add it to this screen. The user is not allowed to create a RemoteControl instance directly.

getAllPlanes

public Plane[] getAllPlanes()

Returns a list of all planes for this screen.

Returns:

an array of Plane objects or null if none exist.

addPlane

public void addPlane(Plane plane)

Adds the specified plane to this screen.

Parameters:

plane - the plane to be added

getCoherentPlaneSetups

public PlaneSetup[] getCoherentPlaneSetups(PlaneSetupPattern[] patterns)
                                    throws IllegalArgumentException

Return a coherent set of PlaneSetups matching a set of patterns. One PlaneSetup will be returned for each PlaneSetupPattern provided as input.

Coherent means that all the required properties are respected in all of the patterns provided and that a setup can be returned for each pattern provided.

Conflicts between patterns are resolved as discussed in the description of PlaneSetupPattern.

Parameters:

patterns - an array of objects describing desired setups.

Returns:

an array of non-null objects describing a coherent set of screen plane setups or null if no such coherent set is possible.

Throws:

IllegalArgumentException - if a zero-length array is passed as an argument

See Also:

setCoherentPlaneSetups(com.sun.dtv.ui.PlaneSetup[])

setCoherentPlaneSetups

public boolean setCoherentPlaneSetups(PlaneSetup[] setups)
                               throws SecurityException,
                                      IllegalArgumentException,
                                      SetupException

Modify the settings for a set of Planes, based on their PlaneSetups supplied.

Parameters:

setups - the array of setups that should be applied (where possible).

Returns:

A boolean indicating whether all PlaneSetups could be applied successfully. If none of the PlaneSetups could be applied successfully, the setup after this method may not match the setup of the planes prior to this method being called: applications should investigate whether a partial change of settings has been made for each plane.

Throws:

IllegalArgumentException - if the parameter array is empty.

SecurityException - if the application does not have sufficient rights to set the PlaneSetup for any of the planes.

SetupException - if an element of the specified PlaneSetup array is not valid for any of the planes.

See Also:

getCoherentPlaneSetups(com.sun.dtv.ui.PlaneSetupPattern[])

getBestSetup

public PlaneSetup getBestSetup(PlaneSetupPattern[] patterns)

Returns a PlaneSetup from an Plane which is present on this Screen that best matches at least one of the specified PlaneSetupPatterns. If this is not possible, null is returned.

Best in the sense of this method means that the setups satisfy a number as high as possible of preferences with priorities PREFERRED and PREFERRED_NOT as well as all preferences with priorities REQUIRED and REQUIRED_NOT. Setups are chosen by applying the following algorithm, based on the priorities as supplied to setPreference. The setup of choice:

• MUST satisfy all the preferences whose priority was REQUIRED
• MUST NOT satisfy any of the preferences whose priority was REQUIRED_NOT
• SHOULD satisfy as many as possible of the preferences whose priority was PREFERRED.
• SHOULD satisfy as few as possible of the preferences whose priority was PREFERRED_NOT.

Preferences whose priority was DONT_CARE are ignored.

This method returns null if no setup exists that satisfies all REQUIRED and REQUIRED_NOT priorities.

Parameters:

patterns - the array of PlaneSetupPattern objects to choose from.

Returns:

an PlaneSetup object that is the best matching possible setup, or null if none can be found.

getScreenAspectRatio

public Dimension getScreenAspectRatio()

Returns the aspect ratio of the video output signal represented by this Screen.

Returns:

the aspect ration of the video output signal.

addScarceResourceListener

public void addScarceResourceListener(ScarceResourceListener listener)

Register a listener for events about changes in the state of the ownership of this screen. 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 screen. 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 Screen reserveOne(boolean force,
                                long timeoutms,
                                ScarceResourceListener listener)
                         throws IllegalArgumentException,
                                TimeoutException

Returns a reserved instance out of the pool of all Screen 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 Screen 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.

getSupportedUserInputDevices

public UserInputDevice[] getSupportedUserInputDevices()

Returns a list of UserInputDevices that are associated to this Screen.

Returns:

a list of UserInputDevices that are associated to this Screen

isKeyboardSupported

public boolean isKeyboardSupported()

Indicates whether this screen can be controlled using a keyboard.

Returns:

true if a keyboard is supported, false otherwise.

getKeyboard

public Keyboard getKeyboard()

Returns the keyboard which can be used to control this screen if any.

Returns:

the Keyboard object representing the keyboard which can be used to control this screen, null if there is none.

isRemoteControlSupported

public boolean isRemoteControlSupported()

Indicates whether this screen can be controlled using a TV remote control.

Returns:

true if TV remote control is supported, false otherwise.

getRemoteControl

public RemoteControl getRemoteControl()

Returns the TV remote control which can be used to control this screen if any.

Returns:

the RemoteControl object representing the TV remote control which can be used to control this screen, null if there is none.

isMouseSupported

public boolean isMouseSupported()

Indicates whether this screen can be controlled using a mouse.

Returns:

true if a mouse is supported, false otherwise.

getMouse

public Mouse getMouse()

Returns the mouse which can be used to control this screen if any.

Returns:

the Mouse object representing the mouse which can be used to control this screen, null if there is none.

getUserInputEventManager

public UserInputEventManager getUserInputEventManager()

Return the UserInputEventManager of this screen. Any screen owns a fixed instance of UserInputEventManager in order to be able to handle user input events coming from several applications. The UserInputEventManager is created together with the screen, it cannot be set or changed. Applications should use this method in order to gain access to the manager in order to apply for exclusive or non-exclusive access to UserInputEvents.

Returns:

the UserInputEventManager of this screen.

getCurrentScreen

public static Screen getCurrentScreen()

Returns the Screen the caller is displayed on.

Returns:

the current screen.

getInstances

public static Screen[] getInstances()

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

Returns:

list of all existing instances of Screen.

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)