MultiScreenManager

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.ocap.ui
Class MultiScreenManager

    java.lang.Object
      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 `ServiceContext`s 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:

  - if exactly one of `screen1` and `screen2` is equivalent to the empty `HScreen`, then the two screens are not equivalent with respect to underlying resources;
  - if, for each screen device, `BD1`, returned by `screen1.getHBackgroundDevices()` there is not exactly one screen device, `BD2`, returned by `screen2.getHBackgroundDevices()` such that `sameResources(BD1,BD2)` returns `true`, then the two screens are not equivalent with respect to underlying resources;
  - if, for each screen device, `VD1`, returned by `screen1.getHVideoDevices()` there is not exactly one screen device, `VD2`, returned by `screen2.getHVideoDevices()` such that `sameResources(VD1,VD2)` returns `true`, then the two screens are not equivalent with respect to underlying resources;
  - if, for each screen device, `GD1`, returned by `screen1.getHGraphicsDevices()` there is not exactly one screen device, `GD2`, returned by `screen2.getHGraphicsDevices()` such that `sameResources(GD1,GD2)` returns `true`, then the two screens are not equivalent with respect to underlying resources;
  - if, given an equivalent set of template arguments, `screen1.getBestConfiguration(..)` and `screen2.getBestConfiguration(..)` would not return (nominally unordered) sets of equivalent `HScreenConfiguration` instances, then the two screens are not equivalent with respect to underlying resources;
  - if, given an eqivalent set of screen configuration arguments, `screen1.getCoherentScreenConfigurations(..)` and `screen2.getCoherentScreenConfigurations(..)` would not return sets of equivalent `HScreenConfiguration` instances, then the two screens are not equivalent with respect to underlying resources;
  - if, given an eqivalent set of screen configuration arguments, `screen1.setCoherentScreenConfigurations(..)` and `screen2.setCoherentScreenConfigurations(..)` would not return the same value or would not modify the set of screen devices associated with the specified screen configuration arguments such that those screen devices remain equivalent, then the two screens are not equivalent with respect to underlying resources;
  - if none the above conditions apply, then `screen1` and `screen2` are deemed equivalent with respect to underlying resources;

  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:

  - if `device1` and `device2` are not of the same sub-type, `HBackgroundDevice`, `HVideoDevice`, or `HGraphicsDevice`, then the two screen devices are not equivalent with respect to underlying resources;
  - if exactly one of `device1` and `device2` is equivalent to the empty `HScreenDevice` of the appropriate sub-type, then the two screen devices are not equivalent with respect to underlying resources;
  - if `device1.getFlickerFilter()` and `device2.getFlickerFilter()` would not return the same value, then the two screen devices are not equivalent with respect to underlying resources;
  - if `device1.getInterlaced()` and `device2.getInterlaced()` would not return the same value, then the two screen devices are not equivalent with respect to underlying resources;
  - if `device1.getPixelAspectRatio()` and `device2.getPixelAspectRatio()` would not return equivalent values, then the two screen devices are not equivalent with respect to underlying resources;
  - if `device1.getPixelResolution()` and `device2.getPixelResolution()` would not return equivalent values, then the two screen devices are not equivalent with respect to underlying resources;
  - if `device1.getScreenArea()` and `device2.getScreenArea()` would not return equivalent values, then the two screen devices are not equivalent with respect to underlying resources;
  - if given equivalent `HScreenConfiguration` instances, `SC1` and `SC2`, as arguments, `device1.getOffset(SC1)` and `device2.getOffset(SC2)` would not return equivalent values, then the two screen devices are not equivalent with respect to underlying resources;
  - if given equivalent `HScreenConfiguration` instances, `SC1` and `SC2`, and equivalent `Point` instances, `P1` and `P2`, as arguments, `device1.convertTo(SC1,P1)` and `device2.convertTo(SC2,P2)` would not return equivalent values, then the two screen devices are not equivalent with respect to underlying resources;
  - if `device1.getConfigurations()` and `device2.getConfigurations()` would not return (nominally unordered) sets of equivalent `HScreenConfiguration` instances, then the two screens are not equivalent with respect to underlying resources;
  - if `device1.getCurrentConfiguration()` and `device2.getCurrentConfiguration()` would not return equivalent `HScreenConfiguration` instances, then the two screens are not equivalent with respect to underlying resources;
  - if `device1.getDefaultConfiguration()` and `device2.getDefaultConfiguration()` would not return equivalent `HScreenConfiguration` instances, then the two screens are not equivalent with respect to underlying resources;
  - if, given an equivalent template arguments or sets of template arguments, `device1.getBestConfiguration(..)` and `device2.getBestConfiguration(..)` would not return sets of equivalent `HScreenConfiguration` instances, then the two screens are not equivalent with respect to underlying resources;
  - if `device1` and `device2` are instances of `HBackgroundDevice` and if `device1.setBackgroundConfiguration(..)` and `device2.setBackgroundConfiguration(..)` would not return the same value when equivalent `HBackgroundConfiguration` instances are specified as arguments, then the two screens are not equivalent with respect to underlying resources;
  - if `device1` and `device2` are instances of `HVideoDevice` and if (1) `device1.setVideoConfiguration(..)` and `device2.setVideoConfiguration(..)` would not return the same value when equivalent `HVideoConfiguration` instances are specified as arguments, (2) `device1.getVideoSource()` and `device1.getVideoSource()` would not return nominally equivalent video sources, or (3) `device1.getVideoController()` and `device1.getVideoController()` would not return nominally equivalent video controllers, then the two screens are not equivalent with respect to underlying resources;
  - if `device1` and `device2` are instances of `HGraphicsDevice` and if `device1.setGraphicsConfiguration(..)` and `device2.setGraphicsConfiguration(..)` would not return the same value when equivalent `HGraphicsConfiguration` instances are specified as arguments, then the two screens are not equivalent with respect to underlying resources;
  - if none the above conditions apply, then `device1` and `device2` are deemed equivalent with respect to underlying resources;

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD