org.ocap.ui
Class MultiScreenManager

java.lang.Object
  extended by org.ocap.ui.MultiScreenManager
All Implemented Interfaces:
ResourceServer

public abstract class MultiScreenManager
extends Object
implements ResourceServer

The MultiScreenManager class is an abstract, singleton management class implemented by an OCAP host platform that provides multiscreen management services.

For other semantic constraints and behavior that apply, see the OCAP Multiscreen Manager (MSM) Extension specification.

Since:
MSM I01
Author:
Glenn Adams
See Also:
ResourceServer

Method Summary
 void addMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)
          Add a listener to be notified upon the occurence of multiscreen configuration events.
 void addPlayerScreenDevices(Player player, HScreenDevice[] devices)
          Add screen device(s) to a media player.
 void addResourceStatusListener(ResourceStatusListener listener)
          Add resource status listener.
 HScreen[] findScreens(ServiceContext context)
          Find accessible screen(s) associated with specific service context.
 HScreen[] getCompatibleScreens(VideoOutputPort port)
          Obtain the set of accessible screens that are compatible with an output port.
 HScreen getDefaultScreen()
          Obtain the default HScreen instance.
 HScreen getEmptyScreen()
          Obtain the singleton empty HScreen instance.
static MultiScreenManager getInstance()
          Gets the singleton instance of the MultiScreenManager.
 MultiScreenConfiguration getMultiScreenConfiguration()
          Obtain currently active per-platform display multiscreen configuration.
 MultiScreenConfiguration getMultiScreenConfiguration(HScreen screen)
          Obtain the multiscreen configuration of a specific screen.
 MultiScreenConfiguration[] getMultiScreenConfigurations()
          Obtain the set of all current multiscreen configurations supported by this platform, irrespective of their configuration type.
 MultiScreenConfiguration[] getMultiScreenConfigurations(String screenConfigurationType)
          Obtain multiscreen configurations of a specific configuration type.
 HScreen getOutputPortScreen(VideoOutputPort port)
          Obtain the screen associated with an output port.
 HScreenDevice[] getPlayerScreenDevices(Player player)
          Obtain the set of screen devices currently assigned for use by a (JMF) media player.
 HScreen[] getScreens()
          Obtain the set of accessible HScreen instances.
 boolean isEmptyScreen(HScreen screen)
          Determines if an instance of HScreen is equivalent, in terms of constraint satisfaction, to the empty HScreen.
 boolean isEmptyScreenDevice(HScreenDevice device)
          Determines if an instance of HScreenDevice is equivalent, in terms of constraint satisfaction, to the empty HScreenDevice of the specific sub-type.
 void moveServiceContexts(HScreen src, HScreen dst, ServiceContext[] contexts)
          Atomically move a set of specific service context from one HScreen instance to another HScreen instance.
 void removeMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)
          Remove a listener previously added to be notified upon the occurence of multiscreen configuration events.
 void removePlayerScreenDevices(Player player, HScreenDevice[] devices)
          Remove screen device(s) from a media player.
 void removeResourceStatusListener(ResourceStatusListener listener)
          Remove resource status listener.
 void requestMultiScreenConfigurationChange(MultiScreenConfiguration configuration, Dictionary serviceContextAssociations)
          Request change to the currently active per-platform display multiscreen configuration.
 boolean sameResources(HScreenDevice device1, HScreenDevice device2)
          Determines if two HScreenDevice instances represent the same underlying platform resources and underlying resource state, i.e., are equivalent with respect to these underlying resources.
 boolean sameResources(HScreen screen1, HScreen screen2)
          Determines if two HScreen instances represent the same underlying platform resources and underlying resource state, i.e., are equivalent with respect to these underlying resources.
 boolean sameResources(ServiceContext sc1, ServiceContext sc2)
          Determines if two ServiceContext instances represent the same underlying platform resources and underlying resource state, i.e., are equivalent with respect to these underlying resources.
 void setMultiScreenConfiguration(MultiScreenConfiguration configuration, Dictionary serviceContextAssociations)
          Set currently active per-platform display multiscreen configuration.
 void swapServiceContexts(HScreen screen1, HScreen screen2, ServiceContext[] exclusions)
          Atomically swap service contexts between two HScreen instances.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.davic.resources.ResourceServer
addResourceStatusEventListener, removeResourceStatusEventListener
 

Method Detail

getScreens

public HScreen[] getScreens()
Obtain the set of accessible HScreen instances.

The set of HScreen instances returned SHALL be determined as follows: when called by an OCAP application that is granted MonitorAppPermission("multiscreen.configuration"), then an HScreen instance SHALL be returned for each display screen and each logical screen exposed through any accessible MultiScreenConfiguration instance at the time of this method's invocation; otherwise, an HScreen instance SHALL be returned for each display screen and each logical screen with which an accessible ServiceContext is associated (either directly or indirectly) for the purpose of presentation or potential presentation.

The first HScreen instance in the returned HScreen[] array SHALL be by the same value returned by the getDefaultScreen() method of this class. Subsequent elements of the returned array do not follow a prescribed order, and an application SHALL NOT rely upon the order of these subsequent elements.

The set of HScreen instances returned by this method MAY change over the course of an application's lifecycle, such as when a screen is added to or removed from an accessible multiscreen configuration; however, the HScreen instance reference that represents an application's default HScreen SHALL remain constant over the application's lifecycle. That is, from the perspective of a given application instance, an MSM implementation SHALL always return the same HScreen instance reference as the first element of the returned array of HScreen instances.

Any HScreen instance returned by the this method SHALL NOT be equivalent to the empty HScreen during the interval between the time when the method returns and the time when a MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_CHANGING or MultiScreenContextEvent.MULTI_SCREEN_CONTEXT_SERVICE_CONTEXT_CHANGED event is generated and dispatched.

Each HScreen instance returned by this method MAY return different sets of HScreenDevice instances from its getHBackgroundDevices(), getHVideoDevices(), and getHGraphicsDevices() methods over the course of an application's lifecycle; however, as described below under the definition of the getDefaultScreen() method, the set of default HBackgroundDevice, HVideoDevice, and HGraphicsDevice instances returned via these methods from a default HScreen instance SHALL remain constant over an application's lifecycle, while the underlying device resources and configurations of these default HScreenDevice instances MAY change.

Any background, video, or graphics screen device, i.e., HBackgroundDevice, HVideoDevice, or HGraphicsDevice, of any HScreen returned by this method SHALL NOT be equivalent to the empty HScreenDevice of its specific sub-type during the interval between the time when this method returns and the time when a MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_CHANGING or MultiScreenContextEvent.MULTI_SCREEN_CONTEXT_SERVICE_CONTEXT_CHANGED event is generated.

The number of HScreenDevice instances returned from the getHBackgroundDevices(), getHVideoDevices(), and getHGraphicsDevices() methods of an HScreen instance returned by this method MAY change over the lifecycle of that HScreen instance. If they do change, then a MultiScreenContextEvent.MULTI_SCREEN_CONTEXT_DEVICES_CHANGED SHALL be generated and dispatched to all registered MultiScreenContextListener instances.

If the number of HScreenDevice instances of a particular type increases or remains the same (for a given HScreen instance), then any reference to a non-default HScreenDevice instance previously returned to the application SHALL remain viable, and SHALL, at the option of the MSM implementation, either (1) be reused to represent the new underlying device resources of that type of screen device or (2) be reset to the empty HScreenDevice of the appropriate sub-type as defined above. In the former case, the reused HScreenDevice instance SHALL be present in the set of screen devices returned from getHBackgroundDevices(), getHVideoDevices(), or getHGraphicsDevices() method according to its screen device type; in the latter case, the HScreenDevice instance whose state is reset to the empty HScreenDevice state SHALL NOT be present in the set of screen devices returned by these methods.

If the number of HScreenDevice instances of a particular type decreases (for a given HScreen instance), then any reference to a non-default HScreenDevice instance previously returned to the application SHALL remain viable, SHALL be reset to the empty screen device state, and SHALL NOT be present in the set of screen devices returned by the HScreen instance.

The net effect of the above specified behavior is that an application that accesses only its default HScreen and default HScreenDevice instances can continue to access and use those instances without any knowledge of the existence of MSM functionality. In contrast, an application that accesses non-default HScreen instances or non-default HScreenDevice instances needs to monitor changes to the current per-platform and per-display multiscreen configurations as well as changes to the set of screen devices associated with a non-default screen.

If a non-default HScreen instance that was previously referenced by an application is reset to the empty screen state as a result of a multiscreen configuration change, the application can detect this fact by comparing the set of HScreen instance references that were obtained prior to an appropriate MultiScreenConfigurationEvent with those obtainable after the event. After this event, those HScreen instances that were reset to the empty state will no longer be present in the array of HScreen instances returned by this method. Furthermore, those previously obtained HScreen instances can be queried as to whether they were reset by using the isEmptyScreen(HScreen) method defined by this class. Lastly, if the application continues to make use of such a reset HScreen instance, then its behavior is well defined and immutable.

Similarly, if a non-default HScreenDevice instance that was previously referenced by an application is reset to the empty screen device state as a result of a multiscreen configuration change, the application can detect this fact by comparing the set of HScreenDevice instance references that were obtained prior to an appropriate MultiScreenContextEvent with those obtainable after the event. After this event, those HScreenDevice instances that were reset to the empty state will no longer be accessible through set of accessible HScreen instances returned by this method. Furthermore, they can be queried as to whether they were reset by using the isEmptyScreenDevice(HScreenDevice) method defined by this class. Lastly, if the application continues to make use of such a reset HScreenDevice instance, then its behavior is well defined and immutable.

If an HScreen instance, S, does not implement the MultiScreenConfigurableContext interface (e.g., because it was not configurable when created and the MSM implementation selectively implements this interface on specific instances of HScreen) and if the new underlying screen resources are configurable (and thus this interface would be implemented on an HScreen instance that represents this set of underlying screen resources), then the MSM implementation SHALL NOT reuse S to represent a new set of underlying screen resources upon a multiscreen configuration change, but SHALL instead reset S to the empty state.

Returns:
A non-empty array of HScreen instances as described above.
Since:
MSM I01
See Also:
MultiScreenConfiguration, MultiScreenConfigurableContext, MultiScreenConfigurationEvent, MultiScreenConfigurationListener, MultiScreenContextEvent, MultiScreenContextListener, HScreen, HScreenDevice, HBackgroundDevice, HVideoDevice, HGraphicsDevice, MonitorAppPermission

getDefaultScreen

public HScreen getDefaultScreen()
Obtain the default HScreen instance.

The HScreen instance returned by this method SHALL represent the currently active set of default, underlying screen devices and their currently active HAVi screen configurations. In addition, it MAY represent a set of currently active non-default, underlying screen devices and their configurations.

The returned default HScreen instance is intended to be the default from the perspective of the calling application or the application on whose behalf this method is invoked. If invoked by the platform implementation in a context that does not imply a specific application, then the returned value is not defined and SHALL be implementation dependent, including, e.g., returning null.

Over the course of an application's lifecycle, the reference returned from this method SHALL remain constant. Furthermore, the set of default HScreenDevice instances returned by the getDefaultHBackgroundDevice(), getDefaultHVideoDevice(), and getDefaultHGraphicsDevice() methods of this default HScreen instance SHALL similarly remain constant over the application's lifecycle. Notwithstanding this constancy of reference, the underlying device resources and the underlying configurations of these device resources MAY change over the course of an application's lifecycle.

Any non-default background, video, or graphics screen device, i.e., HBackgroundDevice, HVideoDevice, or HGraphicsDevice, of any HScreen returned by this method SHALL NOT be equivalent to the empty HScreenDevice of its specific sub-type during the interval between the time when this method returns and the time when a MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_CHANGING or MultiScreenContextEvent.MULTI_SCREEN_CONTEXT_SERVICE_CONTEXT_CHANGED event is generated.

If any HScreenConfiguration (or derived screen device type specific) parameter of any of the default HScreenDevice instances returned by the above cited methods changes over the course of an application's lifecycle, then an appropriate HScreenConfigurationEvent SHALL be generated and dispatched to all registered HScreenConfigurationListener instances. Similarly, if any value that would be returned by any of the query (get*) methods of the MultiScreenContext interface implemented by this default HScreen instance changes, then an appropriate MultiScreenContextEvent SHALL be generated and dispatched to all registered MultiScreenContextListener instances.

If any HScreen instance returned by this method implements the MultiScreenConfigurableContext interface, then every HScreen instance returned by this method SHALL implement the MultiScreenConfigurableContext interface irrespective of whether the underlying screen resources represented by any returned HScreen instance is configurable or not.

Returns:
An HScreen instance as described above.
Since:
MSM I01
See Also:
MultiScreenConfiguration, MultiScreenContext, MultiScreenConfigurableContext, MultiScreenContextEvent, MultiScreenContextListener, HScreen, HScreenDevice, HBackgroundDevice, HVideoDevice, HGraphicsDevice, HScreenConfiguration, HScreenConfigurationEvent

findScreens

public HScreen[] findScreens(ServiceContext context)
Find accessible screen(s) associated with specific service context. A given service context may be associated with zero, one, or multiple HScreen instances.

Find the set of accessible HScreen instances with which a specified ServiceContext is associated. An HScreen instance is accessible (by some application) if the getScreens() method returns (or would return) that instance (when invoked by the same application at the time this method is invoked).

Parameters:
context - a ServiceContext instance.
Returns:
An array of HScreen instances or null. If the specified ServiceContext is associated with some accessible HScreen, then that HScreen SHALL be present in the returned array which SHALL be non-null and non-empty; otherwise, null is returned, indicating that the ServiceContext is not associated with any HScreen.
Since:
MSM I01
See Also:
HScreen, ServiceContext

getOutputPortScreen

public HScreen getOutputPortScreen(VideoOutputPort port)
Obtain the screen associated with an output port.

Given a specific VideoOutputPort instance, obtain the HScreen instance that is associated with that port for the purpose of presentation.

Parameters:
port - a VideoOutputPort instance.
Returns:
The HScreen instance associated with the specified port or null if no association exists.
Since:
MSM I01
See Also:
HScreen, VideoOutputPort

getCompatibleScreens

public HScreen[] getCompatibleScreens(VideoOutputPort port)
Obtain the set of accessible screens that are compatible with an output port.

Given a specific VideoOutputPort instance, obtain the subset of HScreen instances (of the larger set returned by getScreens()) that may be associated with that port for the purpose of presentation.

Parameters:
port - a VideoOutputPort instance.
Returns:
A (possibly empty) array of HScreen instances that may be associated with the specified port.
Since:
MSM I01
See Also:
HScreen, VideoOutputPort

getMultiScreenConfigurations

public MultiScreenConfiguration[] getMultiScreenConfigurations()
                                                        throws SecurityException
Obtain the set of all current multiscreen configurations supported by this platform, irrespective of their configuration type.

The set of multiscreen configuration instances returned by this method SHALL include all per-platform multiscreen configurations (composed solely of display screens) and all per-display multiscreen configurations (composed of no more than one display screen and any number of logical screens).

The order of multiscreen configurations returned by this method is not defined by this specification.

Returns:
An array of MultiScreenConfiguration instances.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.configuration").
Since:
MSM I01
See Also:
MultiScreenConfiguration, MonitorAppPermission

getMultiScreenConfigurations

public MultiScreenConfiguration[] getMultiScreenConfigurations(String screenConfigurationType)
                                                        throws SecurityException
Obtain multiscreen configurations of a specific configuration type.

Parameters:
screenConfigurationType - one of the following values: (1) an element of the following enumeration of constants defined by MultiScreenConfiguration: { SCREEN_CONFIGURATION_DISPLAY, SCREEN_CONFIGURATION_NON_PIP, SCREEN_CONFIGURATION_PIP, SCREEN_CONFIGURATION_POP, SCREEN_CONFIGURATION_GENERAL }, or (2) some other platform-dependent value not pre-defined as a multiscreen configuration type.

The set of multiscreen configuration instances returned by this method SHALL include all multiscreen configurations of the specified type that appear in the array returned by getMultiScreenConfigurations().

The order of multiscreen configurations returned by this method is not defined by this specification.

Returns:
An array of MultiScreenConfiguration instances or null, depending on whether the specified configuration type is supported or not.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.configuration").
Since:
MSM I01
See Also:
MultiScreenConfiguration, MonitorAppPermission

getMultiScreenConfiguration

public MultiScreenConfiguration getMultiScreenConfiguration(HScreen screen)
Obtain the multiscreen configuration of a specific screen.

A given HScreen instance SHALL be associated with either zero or exactly one multiscreen configuration instance; however, since a single underlying screen MAY be potentially shared (multiply referenced) by multiple HScreen instances, an underlying screen (and its constituent resources) MAY be associated with more than one multiscreen configuration.

Parameters:
screen - an HScreen instance
Returns:
The MultiScreenConfiguration instance of which the specified HScreen is a constituent screen or null if the specified HScreen is orphaned (i.e., not owned by a multiscreen configuration, e.g., as would be the case if it were an empty screen).
Since:
MSM I01
See Also:
MultiScreenConfiguration

getMultiScreenConfiguration

public MultiScreenConfiguration getMultiScreenConfiguration()
Obtain currently active per-platform display multiscreen configuration.

Returns:
The currently active per-platform display MultiScreenConfiguration instance.
Since:
MSM I01
See Also:
MultiScreenConfiguration

setMultiScreenConfiguration

public void setMultiScreenConfiguration(MultiScreenConfiguration configuration,
                                        Dictionary serviceContextAssociations)
                                 throws SecurityException,
                                        IllegalStateException,
                                        IllegalStateException
Set currently active per-platform display multiscreen configuration.

If the specified configuration is the current per-platform display multiscreen configuration, then, unless SecurityException applies, return from this method without producing any side effect.

If the specified configuration is not the current per-platform display multiscreen configuration and if SecurityException, IllegalArgumentException, and IllegalStateException do not apply, then perform the synchronous per-platform multiscreen configuration change processing defined by the OCAP Multiscreen Manager (MSM) Extension specification.

If the serviceContextAssociations argument is specified (i.e., not null), then any ServiceContext instance that is accessible to the invoking application SHALL be associated with either no screen or the applicable screen(s) in the specified (new) per-platform multiscreen configuration (or in its per-display multiscreen configurations). If no association matches some accessible ServiceContext, if some accessible ServiceContext instance is not present in the specified associations, or if it is present but no such applicable screen exists in the new per-platform multiscreen configuration (or in its per-display multiscreen configurations), then the ServiceContext instance SHALL be associated with the default service context association screen of the specified multiscreen configuration, i.e., the screen returned by configuration.getDefaultServiceContextScreen().

For the purpose of matching accessible ServiceContext instances whose references appear as keys in a specified serviceContextAssociations dictionary, the virtual method equals(Object) on these keys SHALL be used, in which case it is assumed that this method behaves identically to the default implementation of Object.equals(Object).

Note: In the context of a given application instance, the MSM host implementation should maintain a one-to-one relationship between ServiceContext instances exposed to that application and collections of underyling service context resources. If the MSM host implementation fails to maintain this relationship, then when consulting a serviceContextAssociations dictionary, the MSM implemenation may consider two distinct collections of underlying service context resources to be the same service context, e.g., if at different times, a single ServiceContext instance references distinct underlying collections of resources, or may consider a single collection of underlying service context resources to be two distinct service contexts, e.g., if at a given time, two distinct ServiceContext instances reference the same underlying collection of resources.

The state of the decoder format conversion (DFC) component of a video pipeline being used to process video associated with a service context that is implicitly swapped or moved between screens by this method SHALL NOT be affected by performance of this method.

Parameters:
configuration - a MultiScreenConfiguration instance to become the currently active per-platform display multiscreen configuration.
serviceContextAssociations - if not null, then a Dictionary instance whose keys are ServiceContext instances and whose values are String instances, where the string values are defined as follows: (1) if the string value is "-", then no screen applies (in which case a matching service context is not associated with any screen after the configuration change), (2) otherwise, if the string value is "*", then all screens of the new screen configuration apply, (3) otherwise, if the string value is a screen identifier as returned by MultiScreenContext.getID(), then that screen applies, (4) otherwise, if the string value is a screen category as returned by MultiScreenContext.getScreenCategory(), then any screen of the new configuration with that category applies, (5) otherwise, if the string value is a semicolon separated list of screen identifiers, then each screen of the new configuration with a matching identifier applies, (6) otherwise, if the string value is a semicolon separated list of screen categories, then each screen of the new configuration with a matching category applies, (7) otherwise, if the string value is a semicolon separated list of screen identifiers or screen categories, then each screen of the new configuration with a matching identifier or category applies, (8) otherwise, the default service context association screen of the new configfuration applies.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.configuration").
IllegalArgumentException - if configuration is not a per-platform multiscreen configuration that would be returned by MultiScreenManager.getMultiScreenConfigurations(SCREEN_CONFIGURATION_DISPLAY).
IllegalStateException - if the MSM implementation (1) does not permit activation of the specified multiscreen configuration, (2) if this method was previously called and the change processing steps are not yet complete, or (3) if activation is not otherwise permitted at the time of method invocation.
Since:
MSM I01
See Also:
MultiScreenConfiguration, MonitorAppPermission

requestMultiScreenConfigurationChange

public void requestMultiScreenConfigurationChange(MultiScreenConfiguration configuration,
                                                  Dictionary serviceContextAssociations)
                                           throws SecurityException,
                                                  IllegalStateException
Request change to the currently active per-platform display multiscreen configuration.

If the specified configuration is the current configuration, then, unless SecurityException applies, return from this method without producing any side effect.

If the specified configuration is not the current per-platform display multiscreen configuration and if SecurityException, IllegalArgumentException, and IllegalStateException do not apply, then initiate an asynchronous change to the current per-platform multiscreen configuration, where the semantics of setMultiScreenConfiguration() apply except that this method SHALL return immediately after MultiScreenConfiguration.MULTI_SCREEN_CONFIGURATION_CHANGING is generated (but before it is dispatched).

Parameters:
configuration - a MultiScreenConfiguration instance to become the currently active screen configuration.
serviceContextAssociations - either null or a Dictionary instance whose keys are ServiceContext instances and whose values are String instances, with semantics as defined by setMultiScreenConfiguration(..) above.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.configuration").
IllegalStateException - (1) if the MSM implementation does not permit activation of the specified multiscreen configuration, (2) if this method was previously called and the change processing steps are not yet complete, or (3) if activation is not otherwise permitted at the time of method invocation.
Since:
MSM I01
See Also:
MultiScreenConfiguration, MonitorAppPermission

addMultiScreenConfigurationListener

public void addMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)
Add a listener to be notified upon the occurence of multiscreen configuration events. If a listener has previously been added and not subsequently removed, then an attempt to add it again SHALL NOT produce a side effect.

Configuration events that apply to this MultiScreenManager singleton instance SHALL be restricted to those that affect the complement of usable display screens.

If an event defined by MultiScreenConfigurationEvent is generated, then the MSM implementation SHALL notify each registered screen configuration listener accordingly.

Parameters:
listener - a MultiScreenConfigurationListener instance.
Since:
MSM I01
See Also:
MultiScreenConfigurationEvent, MultiScreenConfigurationListener

removeMultiScreenConfigurationListener

public void removeMultiScreenConfigurationListener(MultiScreenConfigurationListener listener)
Remove a listener previously added to be notified upon the occurence of multiscreen configuration events. If the specified listener is not currently registered as a listener, then an attempt to remove it SHALL NOT produce a side effect.

Parameters:
listener - a MultiScreenConfigurationListener instance.
Since:
MSM I01
See Also:
MultiScreenConfigurationListener

addResourceStatusListener

public void addResourceStatusListener(ResourceStatusListener listener)
Add resource status listener.

Parameters:
listener - a ResourceStatusListener instance.
Since:
MSM I01

removeResourceStatusListener

public void removeResourceStatusListener(ResourceStatusListener listener)
Remove resource status listener.

Parameters:
listener - a ResourceStatusListener instance.
Since:
MSM I01

swapServiceContexts

public void swapServiceContexts(HScreen screen1,
                                HScreen screen2,
                                ServiceContext[] exclusions)
                         throws SecurityException,
                                IllegalStateException
Atomically swap service contexts between two HScreen instances.

This method is a convenience method for supporting the common function of swapping content presentation between screens. Similar results obtained by this method MAY also be accomplished by the more general mechanism of removing and adding service contexts to specific accessible screens by using the MultiScreenConfigurableContext.addServiceContext(..) and MultiScreenConfigurableContext.removeServiceContext(..) methods. Nevertheless, use of the more general method MAY result in more presentation transition artifacts than use of this method due to the atomic swap semantics of this method.

The state of the decoder format conversion (DFC) component of a video pipeline being used to process video associated with a service context that is being swapped by this method SHALL NOT be affected by performance of this method.

Parameters:
screen1 - an HScreen instance whose service contexts are to be swapped with those of screen2.
screen2 - an HScreen instance whose service contexts are to be swapped with those of screen1.
exclusions - if not null, then a non-empty array of ServiceContext instances to be excluded from the swap operation, i.e., whose screen associations are not to be affected by the swap.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.configuration").
IllegalStateException - if any of the following hold: (1) video is being presented as component video rather than background video in either screen, or (2) the ServiceContexts for the specified screens cannot be changed, e.g., if the platform uses a permanent association with a specific ServiceContext and a screen.
Since:
MSM I01
See Also:
HScreen, ServiceContext, MonitorAppPermission

moveServiceContexts

public void moveServiceContexts(HScreen src,
                                HScreen dst,
                                ServiceContext[] contexts)
                         throws SecurityException,
                                IllegalArgumentException,
                                IllegalStateException
Atomically move a set of specific service context from one HScreen instance to another HScreen instance.

This method is a convenience method for supporting the common function of moving content presentations between screens for a set of given service contexts. Similar results obtained by this method MAY also be accomplished by the more general mechanism of removing and adding the service context to specific accessible screens by using the MultiScreenConfigurableContext.addServiceContexts(..) and MultiScreenConfigurableContext.removeServiceContexts(..) methods. Nevertheless, use of the more general method MAY result in more presentation transition artifacts than use of this method due to the atomic move semantics of this method.

The state of the decoder format conversion (DFC) component of a video pipeline being used to process video associated with a service context that is being moved by this method SHALL NOT be affected by performance of this method.

Parameters:
src - an HScreen instance from which the specified service contexts are to be moved.
dst - an HScreen instance to which the specified service contexts are to be moved.
contexts - a non-empty array of ServiceContext instances to be moved from src screen to dst screen.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.configuration").
IllegalArgumentException - if some specified ServiceContext is not currently associated with the source HScreen instance, src.
IllegalStateException - if any of the following hold: (1) video is being presented as component video rather than background video in either screen; (2) some specified ServiceContext for the specified screens cannot be moved, e.g., if the platform uses a permanent association with a specific ServiceContext and a screen; or (3) a non-abstract ServiceContext is already associated with with the destination screen and the platform supports only one non-abstract ServiceContext per screen.
Since:
MSM I01
See Also:
MultiScreenConfigurableContext, HScreen, ServiceContext, MonitorAppPermission

getPlayerScreenDevices

public HScreenDevice[] getPlayerScreenDevices(Player player)
Obtain the set of screen devices currently assigned for use by a (JMF) media player.

Parameters:
player - a JMF Player instance to query for its set of screen devices.
Returns:
An array of HScreenDevice instances, which SHALL be empty if and only if there is no associated screen device.
Since:
MSM I01
See Also:
Player, HScreenDevice

addPlayerScreenDevices

public void addPlayerScreenDevices(Player player,
                                   HScreenDevice[] devices)
                            throws SecurityException,
                                   IllegalStateException
Add screen device(s) to a media player.

Parameters:
player - a JMF Player instance with which to associate the specified screen device(s).
devices - a non-empty array of HScreenDevice instances on which to present some type of rendered content from the specified media player.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalStateException - if any of the following hold: (1) the specified player is not in a stopped state; (2) the specified screen device is not compatible with the specified player; (3) some underlying screen device of devices is not available for use by this application, e.g., due to being exclusively reserved by another application; or (4) some underlying screen device of devices is already associated with a media player, and that device does not support association with multiple media players.
Since:
MSM I01
See Also:
Player, HScreenDevice

removePlayerScreenDevices

public void removePlayerScreenDevices(Player player,
                                      HScreenDevice[] devices)
                               throws SecurityException,
                                      IllegalArgumentException,
                                      IllegalStateException
Remove screen device(s) from a media player.

Removes all or a non-empty set of HScreenDevice instances from the set of screen devices on which the specified media player is presented (or otherwise associated for presentation). If devices is null, then all screen device associations are removed.

Parameters:
player - a JMF Player instance from which to remove association with the specified screen device.
devices - either null or a non-empty set of HScreenDevice instances to be disassociated from the specified media player.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalArgumentException - if devices is not null and some entry of devices is not associated with the specified Player instance.
IllegalStateException - if the specified player is not in a stopped state.
Since:
MSM I01
See Also:
Player, HScreenDevice

getEmptyScreen

public HScreen getEmptyScreen()
Obtain the singleton empty HScreen instance.

Using this empty HScreen, it is possible to obtain a reference to the empty HScreenDevice, empty HScreenConfiguration, and empty HScreenConfigTemplate of each available sub-type, e.g., HBackgroundDevice, HVideoDevice, HGraphicsDevice, etc.

Note: The presence of this method is primarily aimed at supporting the testing of MSM functionality, such as the semantics of isEmptyScreen(), isEmptyScreenDevice(), sameResources(), etc.

Returns:
the empty HScreen singleton
Since:
MSM I01
See Also:
HScreen, HScreenDevice, HBackgroundDevice, HVideoDevice, HGraphicsDevice, HScreenConfiguration, HScreenConfigTemplate

isEmptyScreen

public boolean isEmptyScreen(HScreen screen)
Determines if an instance of HScreen is equivalent, in terms of constraint satisfaction, to the empty HScreen.

If screen does not implement MultiScreenConfigurableContext, then those constraints that pertain to MultiScreenConfigurableContext SHALL be deemed to be equivalent.

Parameters:
screen - an HScreen instance.
Returns:
true if the specified screen is equivalent to the empty HScreen.
Since:
MSM I01
See Also:
HScreen

isEmptyScreenDevice

public boolean isEmptyScreenDevice(HScreenDevice device)
Determines if an instance of HScreenDevice is equivalent, in terms of constraint satisfaction, to the empty HScreenDevice of the specific sub-type.

Parameters:
device - an HScreenDevice instance of one of the following sub-types: HBackgroundDevice, HVideoDevice, or HGraphicsDevice.
Returns:
true if the specified device is equivalent to the empty HScreenDevice of the matching sub-type.
Since:
MSM I01
See Also:
HScreenDevice

sameResources

public boolean sameResources(HScreen screen1,
                             HScreen screen2)
Determines if two HScreen instances represent the same underlying platform resources and underlying resource state, i.e., are equivalent with respect to these underlying resources.

For the purpose of determining equivalence, the following conditions SHALL apply:

Parameters:
screen1 - an HScreen instance.
screen2 - an HScreen instance.
Returns:
true if the specified screens are equivalent as described by the above conditions.
Since:
MSM I01
See Also:
HScreen, HScreenDevice, HScreenConfiguration

sameResources

public boolean sameResources(HScreenDevice device1,
                             HScreenDevice device2)
Determines if two HScreenDevice instances represent the same underlying platform resources and underlying resource state, i.e., are equivalent with respect to these underlying resources.

For the purpose of determining equivalence, the following conditions SHALL apply:

Parameters:
device1 - an HScreenDevice instance.
device2 - an HScreenDevice instance.
Returns:
true if the specified screens are equivalent as described by the above conditions.
Since:
MSM I01
See Also:
HScreen, HScreenDevice, HScreenConfiguration

sameResources

public boolean sameResources(ServiceContext sc1,
                             ServiceContext sc2)
Determines if two ServiceContext instances represent the same underlying platform resources and underlying resource state, i.e., are equivalent with respect to these underlying resources.

Parameters:
sc1 - a ServiceContext instance.
sc2 - a ServiceContext instance.
Returns:
true if the specified service contexts are equivalent (i.e., represent the same underlying resources and resource state).
Since:
MSM I01
See Also:
ServiceContext

getInstance

public static MultiScreenManager getInstance()
Gets the singleton instance of the MultiScreenManager.

Returns:
The MultiScreenManager instance.
Since:
MSM I01