RetryPolicy
@RequiresApi(value = 21)
@ExperimentalRetryPolicy
public interface RetryPolicy
Defines a strategy for retrying upon initialization failures of the CameraProvider. When the initialization task is interrupted by an error or exception during execution, the task will determine whether to be rescheduled based on the specified RetryPolicy.
Several predefined retry policies are available:
NEVER: Never retries the initialization.DEFAULT: The default retry policy, which retries initialization up to a maximum timeout ofgetDefaultRetryTimeoutInMillis, providing a general-purpose approach for handling most errors.RETRY_UNAVAILABLE_CAMERA: The retry policy automatically retries upon encountering errors like theDEFAULTpolicy, and specifically designed to handle potential device inconsistencies in reporting available camera instances. In cases where the initial camera configuration fails due to the device underreporting (i.e., not accurately disclosing all available camera instances) the policy proactively triggers a reinitialization attempt. If the cameras are not successfully configured withingetDefaultRetryTimeoutInMillis, the initialization is considered a failure.
If no RetryPolicy is specified, DEFAULT will be used as the default.
Examples of configuring the RetryPolicy:
// Configuring {RetryPolicy#RETRY_UNAVAILABLE_CAMERA} to the CameraXConfig
ProcessCameraProvider.configureInstance(
CameraXConfig.Builder.fromConfig(Camera2Config.defaultConfig())
.setCameraProviderInitRetryPolicy(RetryPolicy.RETRY_UNAVAILABLE_CAMERA)
.build()
);
...
Configuring a customized RetryPolicy:
ProcessCameraProvider.configureInstance(CameraXConfig.Builder.fromConfig(
Camera2Config.defaultConfig()).setCameraProviderInitRetryPolicy(
executionState -> {
if (executionState.getExecutedTimeInMillis() > 10000L
|| executionState.getNumOfAttempts() > 10
|| executionState.getStatus() == ExecutionState.STATUS_CONFIGURATION_FAIL) {
return RetryConfig.NOT_RETRY;
} else if (executionState.getStatus() == ExecutionState.STATUS_CAMERA_UNAVAILABLE) {
return RetryConfig.DEFAULT_DELAY_RETRY;
} else {
Log.d("CameraX", "Unknown error occur: " + executionState.getCause());
return RetryConfig.MINI_DELAY_RETRY;
}
}).build());
...
In the second example, the custom retry policy retries the initialization up to 10 times or for a maximum of 10 seconds. If an unknown error occurs, the retry policy delays the next retry after a delay defined by MINI_DELAY_RETRY. The retry process stops if the status is STATUS_CONFIGURATION_FAIL. For STATUS_CAMERA_UNAVAILABLE, the retry policy applies DEFAULT_DELAY_RETRY.
Summary
Nested types |
|---|
@ExperimentalRetryPolicyA builder class for customizing RetryPolicy behavior. |
@ExperimentalRetryPolicyProvides insights into the current execution state of the camera initialization process. |
@ExperimentalRetryPolicyRepresents the outcome of a |
@ExperimentalRetryPolicyA builder class for creating and customizing |
Constants |
|
|---|---|
default static final @NonNull RetryPolicy |
This retry policy increases initialization success by automatically retrying upon encountering errors. |
default static final @NonNull RetryPolicy |
A retry policy that prevents any retry attempts and immediately halts the initialization upon encountering an error. |
default static final @NonNull RetryPolicy |
This retry policy automatically retries upon encountering errors and specifically designed to handle potential device inconsistencies in reporting available camera instances. |
Public methods |
|
|---|---|
default static long |
Retrieves the default timeout value, in milliseconds, used for initialization retries. |
default long |
Returns the maximum allowed retry duration in milliseconds. |
abstract @NonNull RetryPolicy.RetryConfig |
onRetryDecisionRequested(Called to request a decision on whether to retry the initialization process. |
Constants
DEFAULT
default static final @NonNull RetryPolicy DEFAULT
This retry policy increases initialization success by automatically retrying upon encountering errors.
By default, it continues retrying for a maximum of getDefaultRetryTimeoutInMillis milliseconds. To adjust the timeout duration to specific requirements, utilize RetryPolicy.Builder.
Example: Create a policy based on DEFAULT with a 10-second timeout:
RetryPolicy customTimeoutPolicy =
new RetryPolicy.Builder(RetryPolicy.DEFAULT).setTimeoutInMillis(10000L).build();
NEVER
default static final @NonNull RetryPolicy NEVER
A retry policy that prevents any retry attempts and immediately halts the initialization upon encountering an error.
RETRY_UNAVAILABLE_CAMERA
default static final @NonNull RetryPolicy RETRY_UNAVAILABLE_CAMERA
This retry policy automatically retries upon encountering errors and specifically designed to handle potential device inconsistencies in reporting available camera instances. If the initial camera configuration fails due to underreporting, the policy automatically attempts reinitialization.
By default, it perseveres for a maximum of getDefaultRetryTimeoutInMillis milliseconds before conceding initialization as unsuccessful. For finer control over the timeout duration, utilize RetryPolicy.Builder.
Example: Create a policy based on RETRY_UNAVAILABLE_CAMERA with a 10-second timeout:
RetryPolicy customTimeoutPolicy = new RetryPolicy.Builder(
RetryPolicy.RETRY_UNAVAILABLE_CAMERA).setTimeoutInMillis(10000L).build();
Public methods
getDefaultRetryTimeoutInMillis
default static long getDefaultRetryTimeoutInMillis()
Retrieves the default timeout value, in milliseconds, used for initialization retries.
| Returns | |
|---|---|
long |
The default timeout duration, expressed in milliseconds. This value determines the maximum time to wait for a successful initialization before considering the process as failed. |
getTimeoutInMillis
default long getTimeoutInMillis()
Returns the maximum allowed retry duration in milliseconds. Initialization will be terminated if retries take longer than this timeout. A value of 0 indicates no timeout is enforced.
The default value is 0 (no timeout).
| Returns | |
|---|---|
long |
The retry timeout in milliseconds. |
onRetryDecisionRequested
abstract @NonNull RetryPolicy.RetryConfig onRetryDecisionRequested(
@NonNull RetryPolicy.ExecutionState executionState
)
Called to request a decision on whether to retry the initialization process.
| Parameters | |
|---|---|
@NonNull RetryPolicy.ExecutionState executionState |
Information about the current execution state of the camera initialization. |
| Returns | |
|---|---|
@NonNull RetryPolicy.RetryConfig |
A RetryConfig indicating whether to retry, along with any associated delay. |