loliball/media3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refine LoadErrorHandlingPolicy Javadoc

Browse Source 
PiperOrigin-RevId: 386453305
This commit is contained in:
olly 2021-07-23 15:43:05 +01:00 committed by bachinger
parent 2ee6d6d95d
commit 3488c047e8
2 changed files with 67 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
library/core/src/main/java/com/google/android/exoplayer2/upstream/DefaultLoadErrorHandlingPolicy.java
View File

@ -69,24 +69,24 @@ public class DefaultLoadErrorHandlingPolicy implements LoadErrorHandlingPolicy {
} }
/** /**
* Returns the fallback selection. * Returns whether a loader should fall back to using another resource on encountering an error,
* and if so the duration for which the failing resource should be excluded.
* *
* <p>The exclusion duration is given by {@link #DEFAULT_TRACK_EXCLUSION_MS} or {@link * <ul>
* #DEFAULT_LOCATION_EXCLUSION_MS} if the load error was not an {@link * <li>This policy will only specify a fallback if {@link #isEligibleForFallback} returns {@code
* #isRecoverableError(IOException) recoverable error}. In case of a recoverable error null is * true} for the error.
* returned to disable exclusion but retry the same load instead. * <li>This policy will always specify a location fallback rather than a track fallback if both
* * {@link FallbackOptions#isFallbackAvailable(int) are available}.
* <p>If alternative locations {@link * <li>When a fallback is specified, the duration for which the failing resource will be
* LoadErrorHandlingPolicy.FallbackOptions#isFallbackAvailable(int) are advertised}, {@link * excluded is {@link #DEFAULT_LOCATION_EXCLUSION_MS} or {@link
* #FALLBACK_TYPE_LOCATION} is selected until all locations are excluded, {@link * #DEFAULT_TRACK_EXCLUSION_MS}, depending on the fallback type.
* #FALLBACK_TYPE_TRACK} otherwise. * </ul>
*/ */
@Override @Override
@Nullable @Nullable
public FallbackSelection getFallbackSelectionFor( public FallbackSelection getFallbackSelectionFor(
FallbackOptions fallbackOptions, LoadErrorInfo loadErrorInfo) { FallbackOptions fallbackOptions, LoadErrorInfo loadErrorInfo) {
if (isRecoverableError(loadErrorInfo.exception)) { if (!isEligibleForFallback(loadErrorInfo.exception)) {
// Don't fallback. Retry the same load again.
return null; return null;
} }
// Prefer location fallbacks to track fallbacks, when both are available. // Prefer location fallbacks to track fallbacks, when both are available.
@ -130,23 +130,18 @@ public class DefaultLoadErrorHandlingPolicy implements LoadErrorHandlingPolicy {
} }
} }
/** /** Returns whether an error should trigger a fallback if possible. */
* Returns whether the error is considered recoverable. protected boolean isEligibleForFallback(IOException exception) {
*
* @param exception The exception.
* @return Whether the error is considered an recoverable error.
*/
protected boolean isRecoverableError(IOException exception) {
if (!(exception instanceof InvalidResponseCodeException)) { if (!(exception instanceof InvalidResponseCodeException)) {
return true; return false;
} }
InvalidResponseCodeException invalidResponseCodeException = InvalidResponseCodeException invalidResponseCodeException =
(InvalidResponseCodeException) exception; (InvalidResponseCodeException) exception;
return invalidResponseCodeException.responseCode != 403 // HTTP 403 Forbidden. return invalidResponseCodeException.responseCode == 403 // HTTP 403 Forbidden.
&& invalidResponseCodeException.responseCode != 404 // HTTP 404 Not Found. || invalidResponseCodeException.responseCode == 404 // HTTP 404 Not Found.
&& invalidResponseCodeException.responseCode != 410 // HTTP 410 Gone. || invalidResponseCodeException.responseCode == 410 // HTTP 410 Gone.
&& invalidResponseCodeException.responseCode != 416 // HTTP 416 Range Not Satisfiable. || invalidResponseCodeException.responseCode == 416 // HTTP 416 Range Not Satisfiable.
&& invalidResponseCodeException.responseCode != 500 // HTTP 500 Internal Server Error. || invalidResponseCodeException.responseCode == 500 // HTTP 500 Internal Server Error.
&& invalidResponseCodeException.responseCode != 503; // HTTP 503 Service Unavailable. || invalidResponseCodeException.responseCode == 503; // HTTP 503 Service Unavailable.
} }
} }

89
library/core/src/main/java/com/google/android/exoplayer2/upstream/LoadErrorHandlingPolicy.java
View File

@ -30,18 +30,20 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy; import java.lang.annotation.RetentionPolicy;
/** /**
* Defines how errors encountered by loaders are handled. * A policy that defines how load errors are handled.
* *
* <p>A loader that can choose between one of a number of resources can exclude a resource when a * <p>Some loaders are able to choose between a number of alternate resources. Such loaders will
* load error occurs. In this case, {@link #getFallbackSelectionFor(FallbackOptions, LoadErrorInfo)} * call {@link #getFallbackSelectionFor(FallbackOptions, LoadErrorInfo)} when a load error occurs.
* defines whether the resource should be excluded for a given {@link FallbackType fallback type}, * The {@link FallbackSelection} returned by the policy defines whether the loader should fall back
* and if so for how long. If the policy indicates that a resource should be excluded, the loader * to using another resource, and if so the duration for which the failing resource should be
* will exclude it for the specified amount of time unless all of the alternatives for the given * excluded.
* fallback type are already excluded.
* *
* <p>When exclusion does not take place, {@link #getRetryDelayMsFor(LoadErrorInfo)} defines whether * <p>When fallback does not take place, a loader will call {@link
* the load is retried. An error that's not retried will always be propagated. An error that is * #getRetryDelayMsFor(LoadErrorInfo)}. The value returned by the policy defines whether the failed
* retried will be propagated according to {@link #getMinimumLoadableRetryCount(int)}. * load can be retried, and if so the duration to wait before retrying. If the policy indicates that
* a load error should not be retried, it will be considered fatal by the loader. The loader may
* also consider load errors that can be retried fatal if at least {@link
* #getMinimumLoadableRetryCount(int)} retries have been attempted.
* *
* <p>Methods are invoked on the playback thread. * <p>Methods are invoked on the playback thread.
*/ */
@ -54,14 +56,13 @@ public interface LoadErrorHandlingPolicy {
@interface FallbackType {} @interface FallbackType {}
/** /**
* Fallback type that is using exclusion of locations (i.e., multiple URLs through which the same * Fallback to the same resource at a different location (i.e., a different URL through which the
* data is accessible). * exact same data can be requested).
*/ */
int FALLBACK_TYPE_LOCATION = 1; int FALLBACK_TYPE_LOCATION = 1;
/** /**
* Fallback type that is using exclusion of tracks (i.e., multiple URLs through which different * Fallback to a different track (i.e., a different representation of the same content; for
* representations of the same content are available; for example the same video encoded at * example the same video encoded at a different bitrate or resolution).
* different bitrates or resolutions).
*/ */
int FALLBACK_TYPE_TRACK = 2; int FALLBACK_TYPE_TRACK = 2;
@ -92,16 +93,16 @@ public interface LoadErrorHandlingPolicy {
/** Holds information about the available fallback options. */ /** Holds information about the available fallback options. */
final class FallbackOptions { final class FallbackOptions {
/** The number of total available alternative locations. */ /** The number of available locations. */
public final int numberOfLocations; public final int numberOfLocations;
/** The number of locations that are already excluded. */ /** The number of locations that are already excluded. */
public final int numberOfExcludedLocations; public final int numberOfExcludedLocations;
/** The number of total available tracks. */ /** The number of tracks. */
public final int numberOfTracks; public final int numberOfTracks;
/** The number of tracks that are already excluded. */ /** The number of tracks that are already excluded. */
public final int numberOfExcludedTracks; public final int numberOfExcludedTracks;
/** Creates an instance with the given values. */ /** Creates an instance. */
public FallbackOptions( public FallbackOptions(
int numberOfLocations, int numberOfLocations,
int numberOfExcludedLocations, int numberOfExcludedLocations,
@ -121,16 +122,19 @@ public interface LoadErrorHandlingPolicy {
} }
} }
/** The selection of a fallback option determining the fallback behaviour on load error. */ /** A selected fallback option. */
final class FallbackSelection { final class FallbackSelection {
/** The {@link FallbackType fallback type} to use. */ /** The type of fallback. */
@FallbackType public final int type; @FallbackType public final int type;
/** The exclusion duration of the {@link #type}, in milliseconds. */ /** The duration for which the failing resource should be excluded, in milliseconds. */
public final long exclusionDurationMs; public final long exclusionDurationMs;
/** /**
* Creates an instance with the given values. The exclusion duration, in milliseconds, needs to * Creates an instance.
* be a positive integer. *
* @param type The type of fallback.
* @param exclusionDurationMs The duration for which the failing resource should be excluded, in
* milliseconds. Must be non-negative.
*/ */
public FallbackSelection(@FallbackType int type, long exclusionDurationMs) { public FallbackSelection(@FallbackType int type, long exclusionDurationMs) {
checkArgument(exclusionDurationMs >= 0); checkArgument(exclusionDurationMs >= 0);
@ -140,33 +144,32 @@ public interface LoadErrorHandlingPolicy {
} }
/** /**
* Returns the {@link FallbackSelection fallback selection} that determines the exclusion * Returns whether a loader should fall back to using another resource on encountering an error,
* behaviour on load error. If null is returned the caller will disable exclusion. * and if so the duration for which the failing resource should be excluded.
* *
* <p>If {@link FallbackSelection#type} is of a type that is not {@link * <p>If the returned {@link FallbackSelection#type fallback type} was not {@link
* FallbackOptions#isFallbackAvailable(int) advertised as available}, then the caller will disable * FallbackOptions#isFallbackAvailable(int) advertised as available}, then the loader will not
* exclusion as if null had been returned. * fall back.
* *
* @param fallbackOptions The available fallback options. * @param fallbackOptions The available fallback options.
* @param loadErrorInfo A {@link LoadErrorInfo} holding information about the load error. * @param loadErrorInfo A {@link LoadErrorInfo} holding information about the load error.
* @return The fallback selection indicating which exclusion type to apply and for how long the * @return The selected fallback, or {@code null} if the calling loader should not fall back.
* resource should be excluded. Returning null indicates to disable exclusion.
*/ */
@Nullable @Nullable
FallbackSelection getFallbackSelectionFor( FallbackSelection getFallbackSelectionFor(
FallbackOptions fallbackOptions, LoadErrorInfo loadErrorInfo); FallbackOptions fallbackOptions, LoadErrorInfo loadErrorInfo);
/** /**
* Returns the number of milliseconds to wait before attempting the load again, or {@link * Returns whether a loader can retry on encountering an error, and if so the duration to wait
* C#TIME_UNSET} if the error is fatal and should not be retried. * before retrying. A return value of {@link C#TIME_UNSET} indicates that the error is fatal and
* should not be retried.
* *
* <p>Loaders may ignore the retry delay returned by this method in order to wait for a specific * <p>For loads that can be retried, loaders may ignore the retry delay returned by this method in
* event before retrying. However, the load is retried if and only if this method does not return * order to wait for a specific event before retrying.
* {@link C#TIME_UNSET}.
* *
* @param loadErrorInfo A {@link LoadErrorInfo} holding information about the load error. * @param loadErrorInfo A {@link LoadErrorInfo} holding information about the load error.
* @return The number of milliseconds to wait before attempting the load again, or {@link * @return The duration to wait before retrying in milliseconds, or {@link C#TIME_UNSET} if the
* C#TIME_UNSET} if the error is fatal and should not be retried. * error is fatal and should not be retried.
*/ */
long getRetryDelayMsFor(LoadErrorInfo loadErrorInfo); long getRetryDelayMsFor(LoadErrorInfo loadErrorInfo);
@ -179,13 +182,13 @@ public interface LoadErrorHandlingPolicy {
default void onLoadTaskConcluded(long loadTaskId) {} default void onLoadTaskConcluded(long loadTaskId) {}
/** /**
* Returns the minimum number of times to retry a load in the case of a load error, before * Returns the minimum number of times to retry a load before a load error that can be retried may
* propagating the error. * be considered fatal.
* *
* @param dataType One of the {@link C C.DATA_TYPE_*} constants indicating the type of data to * @param dataType One of the {@link C C.DATA_TYPE_*} constants indicating the type of data being
* load. * loaded.
* @return The minimum number of times to retry a load in the case of a load error, before * @return The minimum number of times to retry a load before a load error that can be retried may
* propagating the error. * be considered fatal.
* @see Loader#startLoading(Loadable, Callback, int) * @see Loader#startLoading(Loadable, Callback, int)
*/ */
int getMinimumLoadableRetryCount(int dataType); int getMinimumLoadableRetryCount(int dataType);