jdk.dio.power

Interface PowerSavingHandler

public interface PowerSavingHandler

The PowerSavingHandler interface defines methods for getting notified of power state change requests on a specific Device instance.
A PowerSavingHandler can be registered using the PowerManaged.enablePowerSaving(int, jdk.dio.power.PowerSavingHandler) method.

A power saving handler should implement the following requirements:

• it should be implemented to be as fast as possible; for example it should not call any operations that may block, nor pause the current thread.
• it should not throw any unchecked exception.

A compliant implementation of this specification MUST catch unchecked exceptions that may be thrown by a power saving handler and MAY guard against a hanging handler by timing out in order to guarantee the notification of all the registered power saving handlers. A compliant implementation of this specification MUST ignore such unresponsive or failing power saving handler invocations.

See Also:

PowerManaged

Method Summary

Methods

Modifier and Type	Method and Description
<P extends Device<? super P>> void	handlePowerStateChange(P device, PowerManaged.Group group, int currentState, int requestedState, long duration) Invoked to allow the application to handle a power state change (confirmation) on the designated Device instance or PowerManaged.Group instance.
<P extends Device<? super P>> long	handlePowerStateChangeRequest(P device, PowerManaged.Group group, int currentState, int requestedState, long duration) Invoked to allow the application to handle a vetoable power state change request on the designated Device instance or PowerManaged.Group instance.

Method Detail

handlePowerStateChangeRequest

<P extends Device<? super P>> long handlePowerStateChangeRequest(P device,
                                                               PowerManaged.Group group,
                                                               int currentState,
                                                               int requestedState,
                                                               long duration)

Invoked to allow the application to handle a vetoable power state change request on the designated Device instance or PowerManaged.Group instance. The application may veto the power state change by returning 0. Otherwise it should return a duration lesser or equal to the proposed state change duration. An application may veto altogether a power state change from PowerManaged.POWER_ON to PowerManaged.LOWEST_POWER if for example the application is currently using or is about to use the designated device. An application may grant a power state change duration lesser than the specified duration if for example the application anticipates it will use the designated device earlier than the specified duration.

Since a transition to the PowerManaged.POWER_ON state can never be vetoed such as to not deny device access to other applications this method is never invoked prior to a transition to the PowerManaged.POWER_ON state.

Once this method has been called on all the PowerSavingHandlers registered for the device the handlePowerStateChange method is invoked on these same PowerSavingHandlers with the smallest of the negotiated durations unless the power state change has been vetoed.

Parameters:

device - the Device instance for which a power state change is requested or null if this PowerSavingHandler is registered for group notifications.

group - the PowerManaged.Group instance that contains the Device instance for which a power state change is requested (never null).

currentState - the current power state: PowerManaged.POWER_ON, PowerManaged.LOW_POWER, PowerManaged.LOWEST_POWER or PowerManaged.POWER_OFF.

requestedState - the requested power state: PowerManaged.LOW_POWER, PowerManaged.LOWEST_POWER or PowerManaged.POWER_OFF.

duration - the expected duration (in milliseconds) of the new requested state; PowerManaged.UNLIMITED_DURATION if unlimited or unknown.

Returns:

a duration (in milliseconds) lesser or equal to duration or 0 if the power state change is vetoed or PowerManaged.UNLIMITED_DURATION if unlimited or unknown.

handlePowerStateChange

<P extends Device<? super P>> void handlePowerStateChange(P device,
                                                        PowerManaged.Group group,
                                                        int currentState,
                                                        int requestedState,
                                                        long duration)

Invoked to allow the application to handle a power state change (confirmation) on the designated Device instance or PowerManaged.Group instance. This method is invoked under two circumstances:

• once the handlePowerStateChangeRequest(P, jdk.dio.power.PowerManaged.Group, int, int, long) method of all the PowerSavingHandlers registered for the device has been called without veto
• upon an urgent (non-vetoable) power state change requested by the power management facility.

Parameters:

device - the Device instance for which a power state change is requested or null if this PowerSavingHandler is registered for group notifications.

group - the PowerManaged.Group instance that contains the Device instance for which a power state change is requested (never null).

currentState - the current power state: PowerManaged.POWER_ON, PowerManaged.LOW_POWER, PowerManaged.LOWEST_POWER or PowerManaged.POWER_OFF.

requestedState - the requested power state: PowerManaged.POWER_ON, PowerManaged.LOW_POWER, PowerManaged.LOWEST_POWER or PowerManaged.POWER_OFF.

duration - the duration (in milliseconds) of the new requested state; PowerManaged.UNLIMITED_DURATION if unlimited or unknown.