org.ocap.ui
Interface MultiScreenConfigurableContext

All Superinterfaces:
MultiScreenContext, ResourceProxy

public interface MultiScreenConfigurableContext
extends MultiScreenContext, ResourceProxy

This interface provides a set of tools for accomplishing the following:

  1. modifying the mapping of logical HScreens to display HScreens including the area (extent) on the display HScreen where a logical HScreen appears, its visibility, and its z-order (among other HScreens);
  2. modifying the z-order of HScreenDevices within an HScreen;
  3. modifying the set of ServiceContexts associated with an HScreen;
  4. modifying the association of display HScreens and corresponding VideoOutputPort instances;
  5. modifying the set of HScreenDevices whose generated audio constitute the set of audio sources of an HScreen;
  6. modifying the current audio focus assignment of a display HScreen;
  7. reserving and releasing reservation of underlying screen and screen device resources;
  8. obtaining a reference to current resource client that has reserved screen and its underlying resources;
  9. establishing the currently active per-display multiscreen configuration of a display HScreen;

If an HScreen instance may be exposed to an OCAP application and if that HScreen is configurable with respect to the functionality defined by this interface, then an MSM implementation SHALL support the MultiScreenConfigurableContext interface on every such HScreen instance.

An MSM implementation MAY support this interface on an HScreen instance that is not configurable with respect to the functionality defined by this interface.

A given implementation of this interface is not required to support any or all defined configuration changes, but MAY, due to hardware or other constraints, support only specific configuration changes. If an implementation of this interface does not support a specific configuration change, then an attempt to perform that change SHALL cause an IllegalStateException to be raised, as described under each method defined below.

Since:
MSM I01
Author:
Glenn Adams
See Also:
MultiScreenContext, ResourceProxy

Field Summary
static int CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS
          Configurable parameter identifying configurability of audio focus.
static int CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE
          Configurable parameter identifying configurability of audio source(s).
static int CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER
          Configurable parameter identifying configurability of screen device z-order.
static int CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA
          Configurable parameter identifying configurability of screen's associated display area.
static int CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN
          Configurable parameter identifying configurability of screen's associated display screen.
static int CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT
          Configurable parameter identifying configurability of screen's associated output port(s).
static int CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT
          Configurable parameter identifying configurability of screen's associated service context(s).
static int CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY
          Configurable parameter identifying configurability of screen's visibility.
static int CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER
          Configurable parameter identifying configurability of screen's z-order.
 
Fields inherited from interface org.ocap.ui.MultiScreenContext
SCREEN_TYPE_DISPLAY, SCREEN_TYPE_LOGICAL
 
Method Summary
 void addAudioSources(HScreenDevice[] devices, boolean mixWithAudioFocus)
          Add audio source(s) for this screen.
 void addOutputPorts(VideoOutputPort[] ports, boolean removeExisting)
          Add video output port(s) to which screen is mapped.
 void addServiceContexts(ServiceContext[] contexts, boolean associateDefaultDevices)
          Add service context(s) to this screen.
 void assignAudioFocus()
          Assign audio focus to this screen.
 boolean checkServiceContextCompatibility(ServiceContext context)
          Test compatibility of service context with screen.
 ResourceClient getClient()
          Obtain the resource client that currently holds the reservation on the underlying screen and screen resources associated with this HScreen instance.
 Object[] getDiscreteParameterSpace(int parameter)
          Obtain the discrete, (sub)set of values of of the value type space of a configurable parameter.
 boolean hasDiscreteParameterSpace(int parameter)
          Determine if a supported configurable parameter has a discrete or continuously variable value space.
 boolean isConfigurableParameter(int parameter)
          Determine if configurable parameter is supported as configurable (as opposed to fixed) by the platform implementation for some screen.
 void releaseScreen()
          Atomically release underlying resources of screen.
 void removeAudioSources(HScreenDevice[] devices)
          Remove audio source(s) for this screen.
 void removeOutputPorts(VideoOutputPort[] ports)
          Remove video output port(s) to which screen is mapped.
 void removeServiceContexts(ServiceContext[] contexts)
          Remove service context(s) from screen.
 void requestMultiScreenConfigurationChange(MultiScreenConfiguration configuration, Dictionary serviceContextAssociations)
          Request that the currently active multiscreen configuration for this display screen be changed.
 boolean reserveScreen(ResourceClient client, Object requestData)
          Atomically reserve underlying resources of this screen.
 void setDisplayArea(HScreenRectangle rect)
          Set area of display screen to which logical screen is mapped.
 void setDisplayScreen(HScreen screen)
          Associate logical screen with display screen.
 void setMultiScreenConfiguration(MultiScreenConfiguration configuration, Dictionary serviceContextAssociations)
          Set currently active multiscreen configuration for this display screen (i.e., choose among the set of subsets of logical screens that may be associated with this display screen at a given time).
 void setVisible(boolean visible)
          Set screen visibility.
 void setZOrder(HScreenDevice[] devices)
          Set the screen device z-order within this screen for a set of screen devices.
 void setZOrder(int order)
          Set screen z-order.
 
Methods inherited from interface org.ocap.ui.MultiScreenContext
addMultiScreenConfigurationListener, addScreenContextListener, getAudioFocus, getAudioSources, getDisplayArea, getDisplayScreen, getID, getMultiScreenConfiguration, getMultiScreenConfigurations, getMultiScreenConfigurations, getOutputPorts, getScreenCategory, getScreenType, getServiceContexts, getVisible, getZOrder, getZOrder, removeMultiScreenConfigurationListener, removeScreenContextListener
 

Field Detail

CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE

static final int CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE
Configurable parameter identifying configurability of audio source(s).

Configuration of the audio source(s) of a screen is accomplished by using the addAudioSources(..) and removeAudioSources(..) methods defined by this interface.

If the HScreen instance referenced by this interface supports configuration of its audio source(s), then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE) SHALL return true.

If hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE) returns true, then getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_SOURCE) SHALL return a value of type HScreenDevice[], where each entry in the value array is an accessible screen device of this screen that can serve as an audio source for this screen.

Since:
MSM I01
See Also:
HScreen, HScreenDevice, Constant Field Values

CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS

static final int CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS
Configurable parameter identifying configurability of audio focus.

Configuration of the audio focus of a screen is accomplished by using the assignAudioFocus(..) method defined by this interface.

If the HScreen instance referenced by this interface supports configuration of its audio source(s), then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS) SHALL return true.

If hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS) returns true, then getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_AUDIO_FOCUS) SHALL return a value of type HScreen[], where each entry in the value array is an accessible screen that can serve as an audio focus screen.

If this screen is a display screen, then the returned entries SHALL be restricted to those logical screens that are currently mapped to this display screen that can be assigned audio focus. Because a display screen can always be assigned audio focus directly (as opposed to assigning audio focus to some logical screen mapped to the display screen), the display screen is not itself included in the returned entries.

If this screen is a logical screen and if this logical screen is mapped to a display screen and is capable of being assigned audio focus, then the returned array SHALL contain only this screen; otherwise, the returned array SHALL be empty.

Since:
MSM I01
See Also:
HScreen, Constant Field Values

CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER

static final int CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER
Configurable parameter identifying configurability of screen device z-order.

Configuration of device z-order of a screen is accomplished by using the setZOrder(HScreenDevice[]) method defined by this interface.

If the HScreen instance referenced by this interface supports configuration of the z-order of its screen device(s), then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER) SHALL return true.

If hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER) returns true, then getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER) SHALL return a value of type HScreenDevice[][], where each entry in the value array is an array of screen devices whose order matches a supported z-ordering of those screen devices, where the first entry of such an array of screen devices is back-most in z-order (i.e., device z-order of zero).

Example:

The following assumptions apply:

  1. screen has one background device (B1), one video device (V1), and two graphics devices (G1 and G2);
  2. two orderings of graphics devices are supported: (1) B1<V1<G1<G2 and (2) B1<V1<G2<G1;
 MultiScreenConfigurableContext msxx = (MultiScreenConfigurableContext) HScreen.getDefaultHScreen();
 Object[] values = msxx.getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DEVICE_Z_ORDER);
 ASSERT ( values != null );
 ASSERT ( values instanceof HScreenDevice[][] );
 ASSERT ( values.length == 2 );
 HScreenDevice[] order1 = (HScreenDevice[]) values[0];
 ASSERT ( order1 != null );
 ASSERT ( order1.length == 4 );
 ASSERT ( order1[0] instanceof HBackgroundDevice );
 ASSERT ( order1[1] instanceof HVideoDevice );
 ASSERT ( order1[2] instanceof HGraphicsDevice );
 ASSERT ( order1[2].getIDstring().equals ( "G1" ) );
 ASSERT ( order1[3] instanceof HGraphicsDevice );
 ASSERT ( order1[2].getIDstring().equals ( "G2" ) );
 HScreenDevice[] order2 = (HScreenDevice[]) values[1];
 ASSERT ( order2 != null );
 ASSERT ( order2.length == 4 );
 ASSERT ( order2[0] instanceof HBackgroundDevice );
 ASSERT ( order2[1] instanceof HVideoDevice );
 ASSERT ( order2[2] instanceof HGraphicsDevice );
 ASSERT ( order2[2].getIDstring().equals ( "G2" ) );
 ASSERT ( order2[3] instanceof HGraphicsDevice );
 ASSERT ( order2[2].getIDstring().equals ( "G1" ) );
 

Since:
MSM I01
See Also:
HScreen, HScreenDevice, HBackgroundDevice, HVideoDevice, HGraphicsDevice, Constant Field Values

CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA

static final int CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA
Configurable parameter identifying configurability of screen's associated display area.

Configuration of the display area of a (logical) screen is accomplished by using the setDisplayArea(HScreenRectangle) method defined by this interface.

If the HScreen instance referenced by this interface is a display screen, then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA) SHALL return false; otherwise, if this logical screen supports configuration of its display area, then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA) SHALL return true.

If hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA) returns true, then getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_AREA) SHALL return a value of type HScreenRectangle[], where each entry in the value array is a supported display area.

Since:
MSM I01
See Also:
HScreen, HScreenRectangle, Constant Field Values

CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN

static final int CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN
Configurable parameter identifying configurability of screen's associated display screen.

Configuration of the display screen of a (logical) screen is accomplished by using the setDisplayScreen(HScreen) method defined by this interface.

If the HScreen instance referenced by this interface is a display screen, then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN) SHALL return false; otherwise, if this logical screen supports configuration of its display screen, then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN) SHALL return true.

If hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN) returns true, then getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_DISPLAY_SCREEN) SHALL return a value of type HScreen[], where each entry in the value array is an accessible display screen to which this logical screen MAY be mapped.

Since:
MSM I01
See Also:
HScreen, Constant Field Values

CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT

static final int CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT
Configurable parameter identifying configurability of screen's associated output port(s).

Configuration of the output port(s) of a screen is accomplished by using the addOutputPorts(..) and removeOutputPorts(..) methods defined by this interface.

If the HScreen instance referenced by this interface supports configuration of its video output port(s), then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT) SHALL return true.

If hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT) returns true, then getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_OUTPUT_PORT) SHALL return a value of type VideoOutputPort[], where each entry in the value array is an accessible video output port to which this screen may be directly mapped.

Since:
MSM I01
See Also:
HScreen, VideoOutputPort, Constant Field Values

CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT

static final int CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT
Configurable parameter identifying configurability of screen's associated service context(s).

Configuration of the service context(s) of a screen is accomplished by using the addServiceContexts(..) and removeServiceContexts(..) methods defined by this interface, and by using the swapServiceContexts(..) and moveServiceContexts(..) methods defined by MultiScreenManager.

If the HScreen instance referenced by this interface supports configuration of its output port(s), then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT) SHALL return true.

If hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT) returns true, then getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_SERVICE_CONTEXT) SHALL return a value of type ServiceContext[], where each entry in the value array is an accessible service context that can be associated with this screen.

Since:
MSM I01
See Also:
HScreen, ServiceContext, Constant Field Values

CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY

static final int CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY
Configurable parameter identifying configurability of screen's visibility.

Configuration of the visibility of a screen is accomplished by using the setVisible(boolean) method defined by this interface.

If the HScreen instance referenced by this interface supports configuration of its visibility, then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY) SHALL return true, but hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_VISIBILITY) SHALL return false, implying that if visibility is configurable, then a continuous parameter space (i.e., both true and false) applies.

Since:
MSM I01
See Also:
HScreen, Constant Field Values

CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER

static final int CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER
Configurable parameter identifying configurability of screen's z-order.

Configuration of the z-order of a screen is accomplished by using the setZOrder(int) method defined by this interface.

If the HScreen instance referenced by this interface supports configuration of its z-order (with respect to other screens within its multiscreen configuration), then isConfigurableParameter(CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER) SHALL return true.

If hasDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER) returns true, then getDiscreteParameterSpace(CONFIGURABLE_SCREEN_PARAMETER_Z_ORDER) SHALL return a value of type Integer[], where each value entry v in the value array is such that v.intValue() returns a supported z-order index for this screen in the context of this screen's multiscreen configuration.

Since:
MSM I01
See Also:
HScreen, Constant Field Values
Method Detail

isConfigurableParameter

boolean isConfigurableParameter(int parameter)
Determine if configurable parameter is supported as configurable (as opposed to fixed) by the platform implementation for some screen.

Parameters:
parameter - a configurable screen parameter enumeration value as defined above.
Returns:
If the platform implementation supports either continuous or discrete variation of the specified parameter on this screen, then returns true; otherwise, returns false.
Since:
MSM I01

hasDiscreteParameterSpace

boolean hasDiscreteParameterSpace(int parameter)
                                  throws IllegalArgumentException
Determine if a supported configurable parameter has a discrete or continuously variable value space.

In the present context, a "continuously" configurable parameter means the platform supports or can approximate all values of the parameter's value type, while "discrete" means only certain, enumerable values of the parameter's value type may be used as reported by getDiscreteParameterSpace(..).

Parameters:
parameter - a configurable screen parameter enumeration value as defined above.
Returns:
If the platform implementation supports a discrete, (sub)set of values of of the value type space of the specified parameter on this screen, then returns true; otherwise, returns false, in which case all values of the value type space are supported (or approximated).
Throws:
IllegalArgumentException - if isConfigurableParameter(parameter) returns false.
Since:
MSM I01

getDiscreteParameterSpace

Object[] getDiscreteParameterSpace(int parameter)
                                   throws IllegalArgumentException
Obtain the discrete, (sub)set of values of of the value type space of a configurable parameter.

The actual runtime type of the array and the array's elements returned by this method SHALL be as defined for the specified configurable parameter as documented by each configurable parameter's specification above.

Unless indicated otherwise by the definition of a specific configurable parameter, the order of entries in the array returned by this method is not defined by this specification, and SHALL be considered implementation dependent by an interoperable application.

A set of supported discrete parameters MAY change for a given screen and a given configurable parameter over the lifetime of a screen based upon the dynamic state of the screen's underlying resources; however, such a change, if it occurs, SHALL NOT occur outside the time interval between the completion of dispatching MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_CHANGING event and the completion of dispatching the corresponding MultiScreenConfigurationEvent.MULTI_SCREEN_CONFIGURATION_CHANGED event.

Parameters:
parameter - a configurable screen parameter enumeration value as defined above.
Returns:
an array of object instances, each of which denote a discrete value of the specified parameter that is supported (or approximatable) by the platform.
Throws:
IllegalArgumentException - if isConfigurableParameter(parameter) or hasDiscreteParameterSpace(parameter) returns false.
Since:
MSM I01

setVisible

void setVisible(boolean visible)
                throws SecurityException,
                       IllegalStateException
Set screen visibility.

If this screen is a logical screen, then cause it to be marked as visible (if previously hidden) or hidden (if previously visible); otherwise, if this screen is a display screen, then cause all logical screens mapped to this display screen to be marked as visible (if previously hidden) or hidden (if previously visible).

Parameters:
visible - a boolean value indicating whether this logical HScreen or the logical screens mapped to this display HScreen should be made visible or hidden (non-visible) on its associated display HScreen.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalStateException - if the visibility for this HScreen cannot be changed, e.g., if the platform uses a permanent visibility setting.
Since:
MSM I01

setZOrder

void setZOrder(int order)
               throws SecurityException,
                      IllegalStateException
Set screen z-order.

Cause this logical HScreen to change its z-order among other logical HScreens mapped to the same display HScreen.

Parameters:
order - a positive integer value indicating the new z-order to assign to this logical HScreen.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalStateException - if this HScreen's type is not SCREEN_TYPE_LOGICAL or if the z-order for this HScreen cannot be changed, e.g., if the platform uses a permanent z-order setting.
Since:
MSM I01

setZOrder

void setZOrder(HScreenDevice[] devices)
               throws SecurityException,
                      IllegalArgumentException,
                      IllegalStateException
Set the screen device z-order within this screen for a set of screen devices.

Atomically set the z-order of the specified set of HScreenDevice within this screen where the following constraints apply:

If no exception is thrown by this method, then the set of specified HScreenDevice instances will be ordered such that MultiScreenContext.getZOrder(HScreenDevice) when invoked on this screen with any of the specified devices will return a z-order index that preserves the relative order of the specified devices.

If fewer than the entire set of HScreenDevice instances associated with this screen is provided in the devices argument, then the resulting relative order of unspecified devices with respect to specified devices is not defined, except that the constraints defined by MultiScreenContext.getZOrder(HScreenDevice) SHALL apply to the total ordering of devices in this screen after this method returns.

Parameters:
devices - an ordered array of HScreenDevice instances that are associated with this screen.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalArgumentException - if device is not an HScreenDevice of this screen.
IllegalStateException - if (1) the z-order for the specified HScreenDevice cannot be changed, e.g., if the platform uses a permanent z-order setting for screen devices in this screen, or (2) the order of specified devices does not permit the assignment of z-order indices that satisfies the above constraints.
Since:
MSM I01

addAudioSources

void addAudioSources(HScreenDevice[] devices,
                     boolean mixWithAudioFocus)
                     throws SecurityException,
                            IllegalArgumentException,
                            IllegalStateException
Add audio source(s) for this screen.

Add one or more HScreenDevice instances to the set of audio sources from which presented audio is selected (and mixed) for the purpose of audio presentation from this screen.

If a specified audio source is already designated as an audio source for this screen, but mixWithAudioFocus differs from that specified when it was added as an audio source, then the new mixWithAudioFocus value applies.

Parameters:
devices - a non-empty array of HScreenDevice instances, where each such instance contributes to a mixed, audio presentation from this screen.
mixWithAudioFocus - if true, then the specified screen devices contribute (mix) audio to (with) any audio output associated with any video output port with which this screen is associated (directly or indirectly) regardless of whether or not this screen is assigned audio focus; if false, then they contribute audio only when this screen is assigned audio focus.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalArgumentException - if devices is not a non-empty array or some entry of devices is not an HScreenDevice of this screen.
IllegalStateException - if (1) the audio sources for this HScreen cannot be changed, e.g., if the platform uses a permanent audio source setting for screen devices in this screen, or (2) if multiple audio sources are specified and audio mixing is not supported.
Since:
MSM I01

removeAudioSources

void removeAudioSources(HScreenDevice[] devices)
                        throws SecurityException,
                               IllegalArgumentException,
                               IllegalStateException
Remove audio source(s) for this screen.

Removes all or some non-empy set of specific HScreenDevice instances from the set of audio sources of this HScreen. If devices is null, then all audio sources are removed.

Parameters:
devices - either null or a non-empty set of HScreenDevice instances.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalArgumentException - if devices is not null and some HScreenDevice entry is not associated with this HScreen instance.
IllegalStateException - if a specified HScreenDevice used as an audio source for this HScreen cannot be changed, e.g., if the platform uses a permanent association of audio sources with the specified HScreenDevice.
Since:
MSM I01

assignAudioFocus

void assignAudioFocus()
                      throws SecurityException,
                             IllegalStateException
Assign audio focus to this screen.

At any given time, a display screen SHALL assign audio focus to itself or or exactly one logical screen that maps to it (the display screen). When audio focus is (newly) assigned to a logical screen of a display screen and that logical screen does not currently have audio focus assigned to it, then audio focus SHALL be removed from any other logical screen that is mapped to that display screen and assigned instead to the newly assigned logical screen.

If no logical screen is mapped to a given display screen or no logical screen mapped to a given display screen is assigned audio focus, then the display screen SHALL assign itself audio focus (by default). Audio focus MAY be explicitly assigned to a display screen by using this method on a display screen instance.

The audio focus screen of a display screen is the screen whose currently selected audio sources are assigned to be rendered on all (implied) audio presentation devices of all video output ports to which the display screen is mapped. If the screen to which audio focus is assigned has no audio source, i.e., has an empty set of audio sources, then audio (as produced by or potentially produced by the OCAP platform) SHALL NOT be rendered by any (implied) audio presentation device of all video output ports to which the display screen is mapped.

Note: Each distinct display screen may have a distinct logical screen to which audio focus is assigned for the purpose of rendering audio of the display screen (and its collection of mapped logical screens).

Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalStateException - if audio focus cannot be assigned to this HScreen or the current audio focus cannot be changed.
Since:
MSM I01

addOutputPorts

void addOutputPorts(VideoOutputPort[] ports,
                    boolean removeExisting)
                    throws SecurityException,
                           IllegalStateException
Add video output port(s) to which screen is mapped.

If this HScreen is a logical screen rather than a display screen, then it SHALL be considered to function as equivalent to a display screen for the purpose of mapping to the specified video output port(s); i.e., the logical screen is treated as if it were a main display screen on its own accord.

Parameters:
ports - a non-empty array of VideoOutputPort instances.
removeExisting - if true, then remove association with existing screen (if such association exists) before adding to new screen;
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalStateException - if (1) the specified VideoOutputPort is already associated with a different HScreen and removeExisting is not true, (2) this HScreen cannot be mapped to some specified VideoOutputPort due to some platform specific hardware constraint, or (3) the set of VideoOutputPort instances to which this HScreen is mapped cannot be changed, e.g., if the platform uses a permanent association with a specific set of VideoOutputPort instances.
Since:
MSM I01

removeOutputPorts

void removeOutputPorts(VideoOutputPort[] ports)
                       throws SecurityException,
                              IllegalArgumentException,
                              IllegalStateException
Remove video output port(s) to which screen is mapped.

Removes all or some non-empty set of specific VideoOutputPort instances from the set of video output ports to which this HScreen is mapped. If ports is null, then all video output ports associations are removed.

Parameters:
ports - either null or a non-empty array of VideoOutputPort instances.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalArgumentException - if ports is not null and some VideoOutputPort entry is not associated with this HScreen instance.
IllegalStateException - if a specified VideoOutputPort for this HScreen cannot be changed, e.g., if the platform uses a permanent association with the specified VideoOutputPort.
Since:
MSM I01

setDisplayScreen

void setDisplayScreen(HScreen screen)
                      throws SecurityException,
                             IllegalStateException
Associate logical screen with display screen.

Associates this logical HScreen with a display HScreen.

Parameters:
screen - a display HScreen instance or null. If null, and if this method executes without an exception, then upon return, this logical HScreen is no longer associated with a display HScreen.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalStateException - if (1) this HScreen's type is not SCREEN_TYPE_LOGICAL, (2) the specified screen is not null and its screen type is not SCREEN_TYPE_DISPLAY, or (3) the display HScreen associated with this logical HScreen cannot be changed, e.g., if the platform uses a permanent association with a specific display HScreen.
Since:
MSM I01

setDisplayArea

void setDisplayArea(HScreenRectangle rect)
                    throws SecurityException,
                           IllegalStateException
Set area of display screen to which logical screen is mapped.

Associates this logical HScreen with an area (extent) of its associated display HScreen.

Parameters:
rect - an HScreenRectangle instance specifying the area on the display HScreen associated with this logical HScreen that SHALL correspond to the extent of this logical HScreen.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalStateException - if (1) this HScreen's type is not SCREEN_TYPE_LOGICAL or (2) the area of the display HScreen associated with this logical HScreen cannot be changed, e.g., if the platform uses a permanent association with a specific area of the associated display HScreen.
Since:
MSM I01

checkServiceContextCompatibility

boolean checkServiceContextCompatibility(ServiceContext context)
                                         throws SecurityException,
                                                IllegalArgumentException
Test compatibility of service context with screen.

Determine if application may assign ServiceContext to this HScreen and if the specified ServiceContext is compatible with presentation on this HScreen.

Parameters:
context - a valid ServiceContext instance.
Returns:
A boolean value indicating if the specified ServiceContext instance can be assigned to this HScreen. If it can be assigned, true is returned; otherwise, false is returned.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalArgumentException - if the specified ServiceContext is not valid.
Since:
MSM I01

addServiceContexts

void addServiceContexts(ServiceContext[] contexts,
                        boolean associateDefaultDevices)
                        throws SecurityException,
                               IllegalStateException
Add service context(s) to this screen.

Add one or more ServiceContext instances to the set of service contexts associated with this HScreen in order to permit background, video, and graphics content from these ServiceContext instances to be presented on the HScreen's respective screen devices.

If a specified service context is already associated with the underlying screen represented by this interface, then that service context is not multiply associated with this screen, but the existing association remains intact; that is, a given service context SHALL be associated with a given (underlying) screen either once or not at all.

If more than one non-abstract service context is associated with a given screen, and if multiple video sources from the background based players of these multiple non-abstract service contexts are associated with a given HVideoDevice instance of the given screen, then the background based player from these multiple service contexts whose video content is to be displayed is determined according to the following ordered rules:

  1. If the owning application of one of the associated non-abstract service contexts holds a reservation on a given HVideoDevice of the screen, then background based player content from that service context is designated for presentation on that video device;
  2. Otherwise, the background based player of the associated non-abstract service context whose application is assigned the highest priority is designated for presentation on that video device;

If, after applying the above rules, multiple background based players of a given application are designated for presentation on a video device, then the player that was most recently started is given priority for video presentation.

Parameters:
contexts - a non-empty array of ServiceContext instances.
associateDefaultDevices - if true, then associate default screen devices of this screen with all ServiceMediaHandler instances currently associated with the specified ServiceContext instances; otherwise, if false, then do not perform this association with default screen devices.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalStateException - if some specified ServiceContext for this HScreen cannot be changed, e.g., if the platform uses a permanent association with a specific ServiceContext.
Since:
MSM I01

removeServiceContexts

void removeServiceContexts(ServiceContext[] contexts)
                           throws SecurityException,
                                  IllegalArgumentException,
                                  IllegalStateException
Remove service context(s) from screen.

Remove all or some non-empty set of specific ServiceContext instances from the set of service contexts associated with this HScreen. If contexts is null, then all service contexts are removed.

Parameters:
contexts - either null or a non-empty array of ServiceContext instances.
Throws:
SecurityException - if the calling thread has not been granted MonitorAppPermission("multiscreen.context").
IllegalArgumentException - if contexts is not null and some ServiceContext entry is not associated with this HScreen instance.
IllegalStateException - if a specified ServiceContext cannot be changed, e.g., if the platform uses a permanent association with a specified ServiceContext.
Since:
MSM I01

setMultiScreenConfiguration

void setMultiScreenConfiguration(MultiScreenConfiguration configuration,
                                 Dictionary serviceContextAssociations)
                                 throws SecurityException,
                                        IllegalArgumentException,
                                        IllegalStateException
Set currently active multiscreen configuration for this display screen (i.e., choose among the set of subsets of logical screens that may be associated with this display screen at a given time).

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

If the specified configuration is not the current configuration for this display screen and if SecurityException, IllegalStateException, and IllegalStateException do not apply, then perform the synchronous display multiscreen configuration change processing defined in the OCAP Multiscreen Manager (MSM) Extension specification.

If a 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) multiscreen configuration. 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 multiscreen configuration, 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-display multiscreen configuration for this display screen.
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 one of this (display) screen's multiscreen configurations as would be returned by MultiScreenContext.getMultiScreenConfigurations().
IllegalStateException - if this screen is not a display screen or 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

void requestMultiScreenConfigurationChange(MultiScreenConfiguration configuration,
                                           Dictionary serviceContextAssociations)
                                           throws SecurityException,
                                                  IllegalArgumentException,
                                                  IllegalStateException
Request that the currently active multiscreen configuration for this display screen be changed.

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

If the specified configuration is not the current display configuration and if SecurityException, IllegalArgumentException, and IllegalStateException do not apply, then initiate an asynchronous change to the current 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").
IllegalArgumentException - if configuration is not one of this (display) screen's multiscreen configurations as would be returned by MultiScreenContext.getMultiScreenConfigurations().
IllegalStateException - if this screen is not a display screen or (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

getClient

ResourceClient getClient()
Obtain the resource client that currently holds the reservation on the underlying screen and screen resources associated with this HScreen instance.

Specified by:
getClient in interface ResourceProxy
Returns:
a ResourceClient instance or null if the underlying screen and screen resources associated with this HScreen are not reserved.
Since:
MSM I01

reserveScreen

boolean reserveScreen(ResourceClient client,
                      Object requestData)
Atomically reserve underlying resources of this screen.

Reserving a screen SHALL be considered equivalent to reserving all HScreenDevice instances associated with the screen, except that when the screen is reserved using this method, individual HScreenDevice instances SHALL not be released without first releasing all HScreenDevice instances and all underlying screen resources of this screen.

If when reserving a screen, some HScreenDevice of the screen is already reserved by another application, then that reservation must be successfully released (by the MSM implementation) prior to granting reservation to the screen; and, if it is not or cannot be released, then an attempt to reserve the screen SHALL fail (i.e., this method returns false).

If when reserving a screen, some HScreenDevice of the screen is already reserved by the reserving application, then that reservation SHALL be implicitly subsumed by the successful reservation of the entire screen.

If an attempt to reserve a screen using this method succeeds, i.e., returns true, then the getClient() method of all HScreenDevice instances of the screen SHALL return the same value as the getClient() method defined by this interface (as implemented by the concrete implementation of HScreen).

If this screen was previously unreserved and invocation of this method results in it becoming reserved, then, prior to returning from this method, a MultiScreenResourceEvent.MULTI_SCREEN_RESOURCE_SCREEN_RESERVED event SHALL be generated.

If the calling application already holds a reservation on this screen and if the specified client and requestData arguments are identical to those specified when the calling application was previously granted the reservation, then this method SHALL have no side effect and return true. However, if the calling application already holds a reservation on this screen but either the specified client or requestData argument differs from those specified when the calling application was previously granted the reservation, then (1) the specified client and requestData SHALL replace those previously specified, (2) the calling application SHALL retain the reservation, and (3) this method SHALL return true.

Parameters:
client - a ResourceClient instance.
requestData - either null or an Object instance that implements the java.rmi.Remote interface.
Returns:
true if underlying resources of screen were successfully reserved, otherwise false.
Since:
MSM I01
See Also:
Remote

releaseScreen

void releaseScreen()
Atomically release underlying resources of screen.

If the calling application does not hold a reservation on this screen, then this method SHALL have no side effect.

If this screen was previously reserved and invocation of this method results in it being no longer reserved (i.e., becoming unreserved), then, prior to returning from this method, a MultiScreenResourceEvent.MULTI_SCREEN_RESOURCE_SCREEN_RELEASED event SHALL be generated.

Since:
MSM I01