public interface PowerManaged
PowerManaged
interface provides methods that a Device
class may implement to control how the
underlying device hardware resource is managed by the power management facility of the device.
The power management states defined are device as well as host device-dependent. For devices on a
microcontroller unit, there may be no distinction between POWER_OFF
, LOW_POWER
and
LOWEST_POWER
and they may for example all be supported by clock-gating the unused devices. Conversely, a
device external to the host device could support the four power management modes and could especially be
powered off.
A power state change may be dictated by the power management facility of the device or it may be requested by the
power management facility on behalf of the application itself or of another application (see
requestPowerStateChange
). A power state change for a specific device may be requested
by another application if the device or some of the underlying device hardware resources are
shared. This is, for example, the case on a GPIOPin
instance: another application may have opened a different
GPIO pin controlled by the same GPIO controller; the application will get notified of any power state changes
requested by the other application. Devices currently open by an application whose power managements
are logically or physically dependent belong to the same power management group (see PowerManaged.Group
).
An application may register to get notified of power state changes. When notified, the application may take the
following actions:
POWER_OFF
or
LOWEST_POWER
to/from POWER_ON
, as the device state/context may not be
preserved.POWER_ON
to LOWEST_POWER
if the application is currently using or is about
to use the designated device.POWER_ON
to LOWEST_POWER
shorter than
the specified duration if the application anticipates it will use the designated device earlier than the
specified duration.enablePowerSaving
methods the default power saving strategy of the platform applies.
This strategy is platform as well as implementation-dependent. It may define power saving rules (changing
the power state of a device when certain conditions are met) that may or may not differ from device
device to device. It may, for example, consist in forcefully changing all devices' power state to
LOWEST_POWER
upon some condition; in such a situation, attempting to access the device without restoring
its state/configuration may result in unexpected behavior. Therefore an application should always either:
enablePowerSaving
methods) the effective
set of enabled power states is the intersection of the individually sets of enabled power states (bitwise AND). This
corresponds to the power states enabled for the group. If one of the device is subsequently closed the
power states enabled for the group MUST reflect the change.
POWER_ON
to LOW_POWER
POWER_ON
to LOWEST_POWER
POWER_ON
to POWER_OFF
LOW_POWER
to LOWEST_POWER
LOW_POWER
to POWER_OFF
LOWEST_POWER
to POWER_OFF
requestPowerStateChange
has expired the device's power state always transitions to
POWER_ON
.PowerSavingHandler
Modifier and Type | Interface and Description |
---|---|
static interface |
PowerManaged.Group
The
Group interface provides methods for registering for power state changes of devices belonging
to the same power management group. |
Modifier and Type | Field and Description |
---|---|
static int |
LOW_POWER
Low power mode (may save less power while preserving more device context/state than
LOWEST_POWER , hence allowing for a faster return to full performance). |
static int |
LOWEST_POWER
Lowest power mode (may save more power while preserving less device context/state than
LOW_POWER , hence only allowing for a slower return to full performance). |
static int |
POWER_OFF
Power has been fully removed from the device (for example from an external device).
|
static int |
POWER_ON
Fully powered on.
|
static long |
UNLIMITED_DURATION
Unlimited or unknown power state change requested duration.
|
Modifier and Type | Method and Description |
---|---|
void |
disablePowerSaving()
Disables application-dictated power saving for the
Device instance. |
void |
enablePowerSaving(int powerStates)
Enables application-dictated power saving for the
Device instance. |
void |
enablePowerSaving(int powerStates,
PowerSavingHandler handler)
Enables application-dictated power saving for the
Device instance and registers a
PowerSavingHandler instance to get asynchronously notified when the power management facility is about to
change the power state of the Device instance, hence allowing the application to veto the power state
change on the device. |
PowerManaged.Group |
getGroup()
Returns the power management
Group this device belongs to. |
int |
getPowerState()
Returns the current power state of the
Device instance. |
long |
requestPowerStateChange(int powerState,
long duration)
Requests the change of the device's current power state to the specified power state for the specified
duration.
|
static final int LOW_POWER
LOWEST_POWER
, hence allowing for a faster return to full performance).
When transitioning from this state to POWER_ON
no state/configuration restoration of the device
device must be needed.
This bit flag can be bitwise-combined (OR) with other power state bit flags.static final int LOWEST_POWER
LOW_POWER
, hence only allowing for a slower return to full performance).
When transitioning from this state to POWER_ON
some state/configuration restoration of the device
device may be needed. This state/configuration restoration of the device may be handled by a
PowerSavingHandler
.
This bit flag can be bitwise-combined (OR) with other power state bit flags.static final int POWER_OFF
POWER_ON
a complete state/configuration restoration of the
device may be needed. This state/configuration restoration of the device may be handled by
a PowerSavingHandler
.
This bit flag can be bitwise-combined (OR) with other power state bit flags.static final int POWER_ON
static final long UNLIMITED_DURATION
void disablePowerSaving() throws java.io.IOException, ClosedDeviceException
Device
instance. The power saving strategy of the
platform applies.
If a PowerSavingHandler
instance was registered using
enablePowerSaving(int, jdk.dio.power.PowerSavingHandler)
it will be unregistered.ClosedDeviceException
- if the device has been closed.java.lang.SecurityException
- if the caller does not have the required permission.java.io.IOException
- if some other I/O error occurs.void enablePowerSaving(int powerStates) throws java.io.IOException, ClosedDeviceException
Device
instance. Only the specified power states
are enabled for the Device
instance. Any attempt by another application to change the power state of
the Device
instance to a state different from those specified will be automatically vetoed. The power
management facility will not forcefully change the power state of the Device
instance to a state
different from those specified unless in case of urgency.
By using the requestPowerStateChange
method an application may override this directive and
request a power state change to a state other than those specified.
Note that the POWER_ON
state is always implicitly enabled.
Subsequent calls to this method silently override any previous settings of enabled power states as well as
registered PowerSavingHandler
.powerStates
- bitwise OR of enabled power states: LOW_POWER
, LOWEST_POWER
or POWER_OFF
.java.lang.IllegalArgumentException
- if powerStates
is not a bitwise OR of the defined power state values.java.lang.SecurityException
- if the caller does not have the required permission.ClosedDeviceException
- if the device has been closed.java.io.IOException
- if some other I/O error occurs.void enablePowerSaving(int powerStates, PowerSavingHandler handler) throws java.io.IOException, ClosedDeviceException
Device
instance and registers a
PowerSavingHandler
instance to get asynchronously notified when the power management facility is about to
change the power state of the Device
instance, hence allowing the application to veto the power state
change on the device. Only the specified power states are enabled for the Device
instance. Any
attempt by another application to change the power state of the Device
instance to a state different
from those specified will be automatically vetoed. The power management facility will not forcefully change the
power state of the Device
instance to a state different from those specified unless in case of
urgency.
By using the requestPowerStateChange
method an application may override this directive and
request a power state change to a state other than those specified.
Note that the POWER_ON
state is always implicitly enabled.
Since only the specified power states are enabled, the application will only be notified of changes to these
states (including the POWER_ON
state).
Subsequent calls to this method silently override any previous settings of enabled power states as well as
registered PowerSavingHandler
.powerStates
- bitwise OR of enabled power states: LOW_POWER
, LOWEST_POWER
or POWER_OFF
.handler
- the PowerSavingHandler
instance to be notified when a power state change is requested or confirmed for the
device.java.lang.IllegalArgumentException
- if powerStates
is not a bitwise OR of the defined power state values.java.lang.SecurityException
- if the caller does not have the required permission.ClosedDeviceException
- if the device has been closed.java.io.IOException
- if some other I/O error occurs.int getPowerState() throws java.io.IOException, ClosedDeviceException
Device
instance. If application-dictated power saving is
disabled (see disablePowerSaving
the power state depends on the power saving strategy of the platform.Device
instance: POWER_ON
, LOW_POWER
,
LOWEST_POWER
or POWER_OFF
.java.lang.SecurityException
- if the caller does not have the required permission.ClosedDeviceException
- if the device has been closed.java.io.IOException
- if some other I/O error occurs.long requestPowerStateChange(int powerState, long duration) throws java.io.IOException, ClosedDeviceException
PowerSavingHandler
instance has been registered by the current application, it will not get notified
of the requested power state change (neither its request nor its confirmation); it will only get notified when returning back to the POWER_ON
state
or of any interleaving power state changes requested by the system or by other applications.
If the device is already in the requested power state no notification will be performed and the remaining
duration of the current state will be set to the smallest of the requested duration and the currently remaining
duration.
Any invalid power state request (see Valid Power State Transitions) is automatically
vetoed and 0
is returned.
A transition to the POWER_ON
state can never be vetoed such as to not deny device access to other
applications and the duration
parameter is ignored and always assumed to be UNLIMITED_DURATION
.powerState
- the new power state of the Device
instance: POWER_ON
, LOW_POWER
,
LOWEST_POWER
or POWER_OFF
.duration
- the expected duration (in milliseconds) of the requested power state change or
UNLIMITED_DURATION
if unlimited or unknown.UNLIMITED_DURATION
if an unlimited/unknown duration was requested) or 0
if
the requested power state change has been vetoed.java.lang.IllegalArgumentException
- if powerState
is not one of the defined power state values or if duration
is not
greater than 0
or equal to UNLIMITED_DURATION
.java.lang.SecurityException
- if the caller does not have the required permission.ClosedDeviceException
- if the device has been closed.java.io.IOException
- if some other I/O error occurs.PowerManaged.Group getGroup() throws java.io.IOException, ClosedDeviceException
Group
this device belongs to.
A compliant implementation MAY return the same Group
instance (application-wise)
upon subsequent calls
to this PowerManaged
Device
instance or to other
PowerManaged
Device
instances belonging to that same
power management Group
(until that Group
is closed - see PowerManaged.Group
).Group
this device belongs to.java.lang.SecurityException
- if the caller does not have the required permission.ClosedDeviceException
- if the device has been closed.java.io.IOException
- if some other I/O error occurs.Copyright © 2012, 2014, Oracle and/or its affiliates. All rights reserved.
Legal Notices