1 /* 2 * Copyright (C) 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package com.google.android.exoplayer2.upstream; 17 18 import com.google.android.exoplayer2.C; 19 import com.google.android.exoplayer2.source.LoadEventInfo; 20 import com.google.android.exoplayer2.source.MediaLoadData; 21 import com.google.android.exoplayer2.upstream.Loader.Callback; 22 import com.google.android.exoplayer2.upstream.Loader.Loadable; 23 import java.io.IOException; 24 25 /** 26 * Defines how errors encountered by {@link Loader Loaders} are handled. 27 * 28 * <p>Loader clients may blacklist a resource when a load error occurs. Blacklisting works around 29 * load errors by loading an alternative resource. Clients do not try blacklisting when a resource 30 * does not have an alternative. When a resource does have valid alternatives, {@link 31 * #getBlacklistDurationMsFor(int, long, IOException, int)} defines whether the resource should be 32 * blacklisted. Blacklisting will succeed if any of the alternatives is not in the black list. 33 * 34 * <p>When blacklisting does not take place, {@link #getRetryDelayMsFor(int, long, IOException, 35 * int)} defines whether the load is retried. Errors whose load is not retried are propagated. Load 36 * errors whose load is retried are propagated according to {@link 37 * #getMinimumLoadableRetryCount(int)}. 38 * 39 * <p>Methods are invoked on the playback thread. 40 */ 41 public interface LoadErrorHandlingPolicy { 42 43 /** Holds information about a load task error. */ 44 final class LoadErrorInfo { 45 46 /** The {@link LoadEventInfo} associated with the load that encountered an error. */ 47 public final LoadEventInfo loadEventInfo; 48 /** {@link MediaLoadData} associated with the load that encountered an error. */ 49 public final MediaLoadData mediaLoadData; 50 /** The exception associated to the load error. */ 51 public final IOException exception; 52 /** The number of errors this load task has encountered, including this one. */ 53 public final int errorCount; 54 55 /** Creates an instance with the given values. */ LoadErrorInfo( LoadEventInfo loadEventInfo, MediaLoadData mediaLoadData, IOException exception, int errorCount)56 public LoadErrorInfo( 57 LoadEventInfo loadEventInfo, 58 MediaLoadData mediaLoadData, 59 IOException exception, 60 int errorCount) { 61 this.loadEventInfo = loadEventInfo; 62 this.mediaLoadData = mediaLoadData; 63 this.exception = exception; 64 this.errorCount = errorCount; 65 } 66 } 67 68 /** 69 * Returns the number of milliseconds for which a resource associated to a provided load error 70 * should be blacklisted, or {@link C#TIME_UNSET} if the resource should not be blacklisted. 71 * 72 * @param dataType One of the {@link C C.DATA_TYPE_*} constants indicating the type of data to 73 * load. 74 * @param loadDurationMs The duration in milliseconds of the load from the start of the first load 75 * attempt up to the point at which the error occurred. 76 * @param exception The load error. 77 * @param errorCount The number of errors this load has encountered, including this one. 78 * @return The blacklist duration in milliseconds, or {@link C#TIME_UNSET} if the resource should 79 * not be blacklisted. 80 */ getBlacklistDurationMsFor( int dataType, long loadDurationMs, IOException exception, int errorCount)81 long getBlacklistDurationMsFor( 82 int dataType, long loadDurationMs, IOException exception, int errorCount); 83 84 /** 85 * Returns the number of milliseconds for which a resource associated to a provided load error 86 * should be blacklisted, or {@link C#TIME_UNSET} if the resource should not be blacklisted. 87 * 88 * @param loadErrorInfo A {@link LoadErrorInfo} holding information about the load error. 89 * @return The blacklist duration in milliseconds, or {@link C#TIME_UNSET} if the resource should 90 * not be blacklisted. 91 */ getBlacklistDurationMsFor(LoadErrorInfo loadErrorInfo)92 default long getBlacklistDurationMsFor(LoadErrorInfo loadErrorInfo) { 93 return getBlacklistDurationMsFor( 94 loadErrorInfo.mediaLoadData.dataType, 95 loadErrorInfo.loadEventInfo.loadDurationMs, 96 loadErrorInfo.exception, 97 loadErrorInfo.errorCount); 98 } 99 100 /** 101 * Returns the number of milliseconds to wait before attempting the load again, or {@link 102 * C#TIME_UNSET} if the error is fatal and should not be retried. 103 * 104 * <p>{@link Loader} clients may ignore the retry delay returned by this method in order to wait 105 * for a specific event before retrying. However, the load is retried if and only if this method 106 * does not return {@link C#TIME_UNSET}. 107 * 108 * @param dataType One of the {@link C C.DATA_TYPE_*} constants indicating the type of data to 109 * load. 110 * @param loadDurationMs The duration in milliseconds of the load from the start of the first load 111 * attempt up to the point at which the error occurred. 112 * @param exception The load error. 113 * @param errorCount The number of errors this load has encountered, including this one. 114 * @return The number of milliseconds to wait before attempting the load again, or {@link 115 * C#TIME_UNSET} if the error is fatal and should not be retried. 116 */ getRetryDelayMsFor(int dataType, long loadDurationMs, IOException exception, int errorCount)117 long getRetryDelayMsFor(int dataType, long loadDurationMs, IOException exception, int errorCount); 118 119 /** 120 * Returns the number of milliseconds to wait before attempting the load again, or {@link 121 * C#TIME_UNSET} if the error is fatal and should not be retried. 122 * 123 * <p>{@link Loader} clients may ignore the retry delay returned by this method in order to wait 124 * for a specific event before retrying. However, the load is retried if and only if this method 125 * does not return {@link C#TIME_UNSET}. 126 * 127 * @param loadErrorInfo A {@link LoadErrorInfo} holding information about the load error. 128 * @return The number of milliseconds to wait before attempting the load again, or {@link 129 * C#TIME_UNSET} if the error is fatal and should not be retried. 130 */ getRetryDelayMsFor(LoadErrorInfo loadErrorInfo)131 default long getRetryDelayMsFor(LoadErrorInfo loadErrorInfo) { 132 return getRetryDelayMsFor( 133 loadErrorInfo.mediaLoadData.dataType, 134 loadErrorInfo.loadEventInfo.loadDurationMs, 135 loadErrorInfo.exception, 136 loadErrorInfo.errorCount); 137 } 138 139 /** 140 * Returns the minimum number of times to retry a load in the case of a load error, before 141 * propagating the error. 142 * 143 * @param dataType One of the {@link C C.DATA_TYPE_*} constants indicating the type of data to 144 * load. 145 * @return The minimum number of times to retry a load in the case of a load error, before 146 * propagating the error. 147 * @see Loader#startLoading(Loadable, Callback, int) 148 */ getMinimumLoadableRetryCount(int dataType)149 int getMinimumLoadableRetryCount(int dataType); 150 } 151