public class PowerManager extends EventManager
Applications should use the getInstance()
method to get the single
instance of this object, and should call the class methods to make queries
for power state information.
Modifier | Constructor and Description |
---|---|
protected |
PowerManager()
Prevent other class from instantiating.
|
Modifier and Type | Method and Description |
---|---|
boolean |
enableRadio(boolean state,
boolean urgent)
Switches the radio (RF unit) of a device on or off.
|
int |
getBatteryLevel()
Used for retrieving the current level (percent of battery charge remaining)
of the main battery or batteries.
|
int |
getEstimatedTimeRemaining()
Used for getting an estimate of how much time remains before battery
power ceases.
|
static PowerManager |
getInstance()
Returns a reference to the single instance of the PowerManger object.
|
int |
getPowerState()
Gets the current system power state.
|
boolean |
isUsingExternalPower()
Used for checking if an external power source is being used.
|
void |
rebootDevice(boolean urgent)
Initiates a reboot of the device.
|
void |
setPowerState(int state,
boolean urgent)
Puts the system in the state specified in the parameter
state . |
addEventListener, addEventListener, addEventListener, addEventListener, addEventListener, getCurrent, getSystemEventNames, post, registerApplication, registerApplication, registerApplication, registerApplication, registerApplication, removeEventListener, unregisterApplication
public static PowerManager getInstance()
public int getPowerState()
EventManager.getCurrent
(PowerStateEvent.POWER_STATE
)
.PowerStateEvent.POWER_STATE_OFF
,
PowerStateEvent.POWER_STATE_SUSPEND
,
PowerStateEvent.POWER_STATE_SLEEP
,
PowerStateEvent.POWER_STATE_REGULATED_LOW_POWER
,
PowerStateEvent.POWER_STATE_REGULATED_HIGH_POWER
, or
PowerStateEvent.POWER_STATE_FULL_POWER
.java.lang.SecurityException
- If the application does not have EventPermission
with the name "POWER_STATE" and action equals
"read".public void setPowerState(int state, boolean urgent) throws PowerManagerException, java.lang.SecurityException
state
.
If the state
parameter equals to POWER_STATE_OFF
and the call succeeds, the switch to POWER_STATE_OFF
is expected
to take place as soon as possible, but there MUST be enough time for the
method to return and for orderly stopping all running applications.
Also an EventListener
may be registered who has to handle the event
of this power state change. If this handler is going to "hang", the system
can only wait a certain time of course before switching to state
POWER_STATE_OFF
. The length of this timeout period is
implementation-dependent.
Applications suites that want to call this method with the urgent
parameter set to false
have to require the
PowerStatePermission
with name "set".
Applications suites that want to call this method with the urgent
parameter set to true
have to require the
PowerStatePermission
with name "setUrgent". Implementations are
recommended to grant this permission only to pre-installed system
applications though.
state
- the state that the system is going to transit to, MUST be one
of PowerStateEvent.POWER_STATE_OFF
,
PowerStateEvent.POWER_STATE_SUSPEND
,
PowerStateEvent.POWER_STATE_SLEEP
,
PowerStateEvent.POWER_STATE_REGULATED_LOW_POWER
,
PowerStateEvent.POWER_STATE_REGULATED_HIGH_POWER
, or
PowerStateEvent.POWER_STATE_FULL_POWER
.
If the state
is identical to the current one at the
time this method is called, the call has no effect: no state
transition takes place and no PowerStateEvent
is created.urgent
- If urgent
is set to true
, force
the system to change state regardless of any objections which
may be posted by applications to reject the state change.
In circumstances like a low power emergency shutdown,
urgent
should be set to true
.PowerManagerException
- A PowerManagerException
MUST
be thrown with error code STATE_TRANSITION_FAILURE
if an error is encountered during the state change process. A
PowerManagerException
MUST be thrown with error code
ILLEGAL_STATE_TRANSITION_REQUEST
if an unrecognized
state
value is passed to the method or when there
is an invalid state transition request. A
PowerManagerException
MUST be thrown with error code
KEEP_CURRENT_STATE
if the state change does not
take place by calling this method.java.lang.SecurityException
- A SecurityException
MUST
be thrown if the caller does not have the valid permission to
initiate the call.public int getBatteryLevel()
EventManager.getCurrent
(PowerStateEvent.BATTERY_LEVEL
)
.0
-100
), or -1
if battery
capacity information is not available, or Integer.MAX_VALUE
if battery capacity information is not available and an
external power source is currently being used.java.lang.SecurityException
- If the application does not have EventPermission
with the name "BATTERY_LEVEL" and action equals
"read".public int getEstimatedTimeRemaining()
-1
if no estimate is available, or Integer.MAX_VALUE
if an external power source is currently applied.public boolean isUsingExternalPower()
true
if an external power source is being
used (implying infinite power remaining). Returns false if
running from internal batteries, in which case the battery level
and estimated seconds remaining should be monitored.public boolean enableRadio(boolean state, boolean urgent) throws PowerManagerException, java.lang.SecurityException
Applications suites that want to call this method with the urgent
parameter set to false
have to require the
PowerStatePermission
with name "set".
Applications suites that want to call this method with the urgent
parameter set to true
have to require the
PowerStatePermission
with name "setUrgent". Implementations are
recommended to grant this permissions only to pre-installed system
applications though.
state
- true
in order to switch the radio on,
false
to switch it offurgent
- If urgent
is set to true
, force
the system to change the radio state regardless of any objections
which may be posted by applications to reject the state change.PowerManagerException
- A PowerManagerException
MUST
be thrown with error code KEEP_CURRENT_STATE
if an
error is encountered during the radio state change process.java.lang.SecurityException
- A SecurityException
MUST
be thrown if the caller does not have the valid permission to
initiate the call.public void rebootDevice(boolean urgent) throws PowerManagerException, java.lang.SecurityException
PowerStateEvent.POWER_STATE_OFF
, as it would happen by a call
to setPowerState
(
PowerStateEvent.POWER_STATE_OFF
, urgent)
, but dispositions
are made, that the device boots again aferward. The power state the
device is in after rebooting is implementation dependent.
If the call succeeds, the switch to POWER_STATE_OFF
is expected
to take place as soon as possible, but there MUST be enough time for the
method to return and for orderly stopping all running applications.
Also an EventListener
may be registered who has to handle the event
of this power state change. If this handler is going to "hang", the system
can only wait a certain time of course before switching to state
POWER_STATE_OFF
. The length of this timeout period is
implementation-dependent.
Applications suites that want to call this method with the urgent
parameter set to false
have to require the
PowerStatePermission
with name "set".
Applications suites that want to call this method with the urgent
parameter set to true
have to require the
PowerStatePermission
with name "setUrgent". Implementations are
recommended to grant this permissions only to pre-installed system
applications though.
urgent
- If urgent
is set to true
, force
the system to reboot regardless of any objections which
may be posted by applications to reject the state change.PowerManagerException
- A PowerManagerException
MUST
be thrown with error code STATE_TRANSITION_FAILURE
if an error is encountered during the rebooting process. A
PowerManagerException
MUST be thrown with error code
ILLEGAL_STATE_TRANSITION_REQUEST
if a state
transition to PowerStateEvent.POWER_STATE_OFF
is invalid.java.lang.SecurityException
- A SecurityException
MUST
be thrown if the caller does not have the valid permission to
initiate the call.Copyright (c) 2014, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.