diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/Allocation.java b/library/src/main/java/com/google/android/exoplayer2/upstream/Allocation.java index 7968d35b78..08b42533cc 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/Allocation.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/Allocation.java @@ -24,7 +24,7 @@ package com.google.android.exoplayer2.upstream; public final class Allocation { /** - * The array containing the allocated space. The allocated space may not be at the start of the + * The array containing the allocated space. The allocated space might not be at the start of the * array, and so {@link #translateOffset(int)} method must be used when indexing into it. */ public final byte[] data; diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/Allocator.java b/library/src/main/java/com/google/android/exoplayer2/upstream/Allocator.java index f46e8d17b0..17b7dfd6e9 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/Allocator.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/Allocator.java @@ -31,22 +31,22 @@ public interface Allocator { Allocation allocate(); /** - * Return an {@link Allocation}. + * Releases an {@link Allocation} back to the allocator. * - * @param allocation The {@link Allocation} being returned. + * @param allocation The {@link Allocation} being released. */ void release(Allocation allocation); /** - * Return an array of {@link Allocation}s. + * Releases an array of {@link Allocation}s back to the allocator. * - * @param allocations The array of {@link Allocation}s being returned. + * @param allocations The array of {@link Allocation}s being released. */ void release(Allocation[] allocations); /** - * Hints to the {@link Allocator} that it should make a best effort to release any memory that it - * has allocated beyond the target buffer size. + * Hints to the allocator that it should make a best effort to release any excess + * {@link Allocation}s. */ void trim(); diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/AssetDataSource.java b/library/src/main/java/com/google/android/exoplayer2/upstream/AssetDataSource.java index e94d323bab..8487b7e6d2 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/AssetDataSource.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/AssetDataSource.java @@ -26,7 +26,7 @@ import java.io.IOException; import java.io.InputStream; /** - * A local asset {@link DataSource}. + * A {@link DataSource} for reading from a local asset. */ public final class AssetDataSource implements DataSource { @@ -50,16 +50,15 @@ public final class AssetDataSource implements DataSource { private boolean opened; /** - * Constructs a new {@link DataSource} that retrieves data from a local asset. + * @param context A context. */ public AssetDataSource(Context context) { this(context, null); } /** - * Constructs a new {@link DataSource} that retrieves data from a local asset. - * - * @param listener An optional listener. Specify {@code null} for no listener. + * @param context A context. + * @param listener An optional listener. */ public AssetDataSource(Context context, TransferListener listener) { this.assetManager = context.getAssets(); diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/BandwidthMeter.java b/library/src/main/java/com/google/android/exoplayer2/upstream/BandwidthMeter.java index 624dd7106b..973e291cb1 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/BandwidthMeter.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/BandwidthMeter.java @@ -21,20 +21,23 @@ package com.google.android.exoplayer2.upstream; public interface BandwidthMeter { /** - * Interface definition for a callback to be notified of {@link BandwidthMeter} events. + * A listener of {@link BandwidthMeter} events. */ interface EventListener { /** * Invoked periodically to indicate that bytes have been transferred. + *

+ * Note: The estimated bitrate is typically derived from more information than just + * {@code bytes} and {@code elapsedMs}. * * @param elapsedMs The time taken to transfer the bytes, in milliseconds. * @param bytes The number of bytes transferred. - * @param bitrate The estimated bitrate in bits/sec, or {@link #NO_ESTIMATE} if no estimate - * is available. Note that this estimate is typically derived from more information than - * {@code bytes} and {@code elapsedMs}. + * @param bitrate The estimated bitrate in bits/sec, or {@link #NO_ESTIMATE} if an estimate is + * not available. */ void onBandwidthSample(int elapsedMs, long bytes, long bitrate); + } /** @@ -43,9 +46,8 @@ public interface BandwidthMeter { long NO_ESTIMATE = -1; /** - * Gets the estimated bandwidth, in bits/sec. - * - * @return Estimated bandwidth in bits/sec, or {@link #NO_ESTIMATE} if no estimate is available. + * Returns the estimated bandwidth in bits/sec, or {@link #NO_ESTIMATE} if an estimate is not + * available. */ long getBitrateEstimate(); diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSink.java b/library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSink.java index ecb333f01f..69d5ed1cd3 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSink.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSink.java @@ -29,14 +29,13 @@ public final class ByteArrayDataSink implements DataSink { private ByteArrayOutputStream stream; @Override - public DataSink open(DataSpec dataSpec) throws IOException { + public void open(DataSpec dataSpec) throws IOException { if (dataSpec.length == C.LENGTH_UNBOUNDED) { stream = new ByteArrayOutputStream(); } else { Assertions.checkArgument(dataSpec.length <= Integer.MAX_VALUE); stream = new ByteArrayOutputStream((int) dataSpec.length); } - return this; } @Override @@ -50,9 +49,8 @@ public final class ByteArrayDataSink implements DataSink { } /** - * Returns the data written to the sink since the last call to {@link #open(DataSpec)}. - * - * @return The data, or null if {@link #open(DataSpec)} has never been called. + * Returns the data written to the sink since the last call to {@link #open(DataSpec)}, or null if + * {@link #open(DataSpec)} has never been called. */ public byte[] getData() { return stream == null ? null : stream.toByteArray(); diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSource.java b/library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSource.java index e3ed55663a..754815be03 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSource.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSource.java @@ -78,4 +78,3 @@ public final class ByteArrayDataSource implements DataSource { } } - diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/ContentDataSource.java b/library/src/main/java/com/google/android/exoplayer2/upstream/ContentDataSource.java index a21f63158f..44a5ac5a36 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/ContentDataSource.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/ContentDataSource.java @@ -28,7 +28,7 @@ import java.io.IOException; import java.io.InputStream; /** - * A content URI {@link DataSource}. + * A {@link DataSource} for reading from a content URI. */ public final class ContentDataSource implements DataSource { @@ -52,16 +52,15 @@ public final class ContentDataSource implements DataSource { private boolean opened; /** - * Constructs a new {@link DataSource} that retrieves data from a content provider. + * @param context A context. */ public ContentDataSource(Context context) { this(context, null); } /** - * Constructs a new {@link DataSource} that retrieves data from a content provider. - * - * @param listener An optional listener. Specify {@code null} for no listener. + * @param context A context. + * @param listener An optional listener. */ public ContentDataSource(Context context, TransferListener listener) { this.resolver = context.getContentResolver(); diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/DataSink.java b/library/src/main/java/com/google/android/exoplayer2/upstream/DataSink.java index 77e7454b4d..fe3334ab90 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/DataSink.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/DataSink.java @@ -18,25 +18,17 @@ package com.google.android.exoplayer2.upstream; import java.io.IOException; /** - * A component that consumes media data. + * A component to which streams of data can be written. */ public interface DataSink { /** - * Opens the {@link DataSink} to consume the specified data. + * Opens the sink to consume the specified data. * * @param dataSpec Defines the data to be consumed. - * @return This {@link DataSink}, for convenience. - * @throws IOException + * @throws IOException If an error occurs opening the sink. */ - DataSink open(DataSpec dataSpec) throws IOException; - - /** - * Closes the {@link DataSink}. - * - * @throws IOException - */ - void close() throws IOException; + void open(DataSpec dataSpec) throws IOException; /** * Consumes the provided data. @@ -44,8 +36,15 @@ public interface DataSink { * @param buffer The buffer from which data should be consumed. * @param offset The offset of the data to consume in {@code buffer}. * @param length The length of the data to consume, in bytes. - * @throws IOException + * @throws IOException If an error occurs writing to the sink. */ void write(byte[] buffer, int offset, int length) throws IOException; + /** + * Closes the sink. + * + * @throws IOException If an error occurs closing the sink. + */ + void close() throws IOException; + } diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/DataSource.java b/library/src/main/java/com/google/android/exoplayer2/upstream/DataSource.java index 44cb574115..4cc10edf88 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/DataSource.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/DataSource.java @@ -22,7 +22,7 @@ import android.net.Uri; import java.io.IOException; /** - * A component that provides media data. + * A component from which streams of data can be read. */ public interface DataSource { @@ -39,11 +39,10 @@ public interface DataSource { } /** - * Opens the {@link DataSource} to read the specified data. + * Opens the source to read the specified data. *

* Note: If an {@link IOException} is thrown, callers must still call {@link #close()} to ensure - * that any partial effects of the invocation are cleaned up. Implementations of this class can - * assume that callers will call {@link #close()} in this case. + * that any partial effects of the invocation are cleaned up. * * @param dataSpec Defines the data to be read. * @throws IOException If an error occurs opening the source. @@ -57,10 +56,8 @@ public interface DataSource { /** * Reads up to {@code length} bytes of data and stores them into {@code buffer}, starting at - * index {@code offset}. - *

- * This method blocks until at least one byte of data can be read, the end of the opened range is - * detected, or an exception is thrown. + * index {@code offset}. Blocks until at least one byte of data can be read, the end of the opened + * range is detected, or an exception is thrown. * * @param buffer The buffer into which the read data should be stored. * @param offset The start offset into {@code buffer} at which data should be written. @@ -72,20 +69,19 @@ public interface DataSource { int read(byte[] buffer, int offset, int readLength) throws IOException; /** - * When the source is open, returns the {@link Uri} from which data is being read. - *

- * The returned {@link Uri} will be identical to the one passed {@link #open(DataSpec)} in the - * {@link DataSpec} unless redirection has occurred. If redirection has occurred, the {@link Uri} - * after redirection is returned. + * When the source is open, returns the {@link Uri} from which data is being read. The returned + * {@link Uri} will be identical to the one passed {@link #open(DataSpec)} in the {@link DataSpec} + * unless redirection has occurred. If redirection has occurred, the {@link Uri} after redirection + * is returned. * - * @return When the source is open, the {@link Uri} from which data is being read. Null otherwise. + * @return The {@link Uri} from which data is being read, or null if the source is not open. */ Uri getUri(); /** - * Closes the {@link DataSource}. + * Closes the source. *

- * Note: This method will be called even if the corresponding call to {@link #open(DataSpec)} + * Note: This method must be called even if the corresponding call to {@link #open(DataSpec)} * threw an {@link IOException}. See {@link #open(DataSpec)} for more details. * * @throws IOException If an error occurs closing the source. diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/DataSourceInputStream.java b/library/src/main/java/com/google/android/exoplayer2/upstream/DataSourceInputStream.java index 72595aa20f..56cd33bba5 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/DataSourceInputStream.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/DataSourceInputStream.java @@ -23,7 +23,7 @@ import java.io.InputStream; /** * Allows data corresponding to a given {@link DataSpec} to be read from a {@link DataSource} and - * consumed as an {@link InputStream}. + * consumed through an {@link InputStream}. */ public final class DataSourceInputStream extends InputStream { diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java b/library/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java index 3d19e34957..6d711ff2dc 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java @@ -23,7 +23,7 @@ import android.net.Uri; import java.util.Arrays; /** - * Defines a region of media data. + * Defines a region of data. */ public final class DataSpec { @@ -41,7 +41,7 @@ public final class DataSpec { public static final int FLAG_ALLOW_GZIP = 1; /** - * Identifies the source from which data should be read. + * The source from which data should be read. */ public final Uri uri; /** diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultAllocator.java b/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultAllocator.java index c0ca193e18..ace9c61011 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultAllocator.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultAllocator.java @@ -37,20 +37,20 @@ public final class DefaultAllocator implements Allocator { private Allocation[] availableAllocations; /** - * Constructs an initially empty pool. + * Constructs an instance without creating any {@link Allocation}s up front. * - * @param individualAllocationSize The length of each individual allocation. + * @param individualAllocationSize The length of each individual {@link Allocation}. */ public DefaultAllocator(int individualAllocationSize) { this(individualAllocationSize, 0); } /** - * Constructs a pool with some {@link Allocation}s created up front. + * Constructs an instance with some {@link Allocation}s created up front. *

- * Note: Initial {@link Allocation}s will never be discarded by {@link #trim()}. + * Note: {@link Allocation}s created up front will never be discarded by {@link #trim()}. * - * @param individualAllocationSize The length of each individual allocation. + * @param individualAllocationSize The length of each individual {@link Allocation}. * @param initialAllocationCount The number of allocations to create up front. */ public DefaultAllocator(int individualAllocationSize, int initialAllocationCount) { diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultBandwidthMeter.java b/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultBandwidthMeter.java index 26060c2da5..86324638b8 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultBandwidthMeter.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultBandwidthMeter.java @@ -22,11 +22,14 @@ import android.os.Handler; import android.os.SystemClock; /** - * Counts transferred bytes while transfers are open and creates a bandwidth sample and updated - * bandwidth estimate each time a transfer ends. + * Estimates bandwidth by listening to data transfers. The bandwidth estimate is calculated using + * a {@link SlidingPercentile} and is updated each time a transfer ends. */ public final class DefaultBandwidthMeter implements BandwidthMeter, TransferListener { + /** + * The default maximum weight for the sliding window. + */ public static final int DEFAULT_MAX_WEIGHT = 2000; private static final int ELAPSED_MILLIS_FOR_ESTIMATE = 2000; diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSource.java b/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSource.java index a719a31325..fd87709d8e 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSource.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSource.java @@ -54,7 +54,7 @@ public final class DefaultDataSource implements DataSource { * Constructs a new instance, optionally configured to follow cross-protocol redirects. * * @param context A context. - * @param listener An optional {@link TransferListener}. + * @param listener An optional listener. * @param userAgent The User-Agent string that should be used when requesting remote data. * @param allowCrossProtocolRedirects Whether cross-protocol redirects (i.e. redirects from HTTP * to HTTPS and vice versa) are enabled when fetching remote data.. @@ -72,7 +72,7 @@ public final class DefaultDataSource implements DataSource { * than file, asset and content. * * @param context A context. - * @param listener An optional {@link TransferListener}. + * @param listener An optional listener. * @param baseDataSource A {@link DataSource} to use for URI schemes other than file, asset and * content. This {@link DataSource} should normally support at least http(s). */ diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSourceFactory.java b/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSourceFactory.java index 3a0d95bbec..4438860389 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSourceFactory.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSourceFactory.java @@ -27,29 +27,44 @@ public final class DefaultDataSourceFactory implements Factory { private final Context context; private final String userAgent; - private final TransferListener transferListener; + private final TransferListener listener; private final boolean allowCrossProtocolRedirects; + /** + * @param context A context. + * @param userAgent The User-Agent string that should be used. + */ public DefaultDataSourceFactory(Context context, String userAgent) { this(context, userAgent, null); } - public DefaultDataSourceFactory(Context context, String userAgent, - TransferListener transferListener) { - this(context, userAgent, transferListener, false); + /** + * @param context A context. + * @param userAgent The User-Agent string that should be used. + * @param listener An optional listener. + */ + public DefaultDataSourceFactory(Context context, String userAgent, TransferListener listener) { + this(context, userAgent, listener, false); } - public DefaultDataSourceFactory(Context context, String userAgent, - TransferListener transferListener, boolean allowCrossProtocolRedirects) { + /** + * @param context A context. + * @param userAgent The User-Agent string that should be used. + * @param listener An optional listener. + * @param allowCrossProtocolRedirects Whether cross-protocol redirects (i.e. redirects from HTTP + * to HTTPS and vice versa) are enabled. + */ + public DefaultDataSourceFactory(Context context, String userAgent, TransferListener listener, + boolean allowCrossProtocolRedirects) { this.context = context.getApplicationContext(); this.userAgent = userAgent; - this.transferListener = transferListener; + this.listener = listener; this.allowCrossProtocolRedirects = allowCrossProtocolRedirects; } @Override public DefaultDataSource createDataSource() { - return new DefaultDataSource(context, transferListener, userAgent, allowCrossProtocolRedirects); + return new DefaultDataSource(context, listener, userAgent, allowCrossProtocolRedirects); } } diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultHttpDataSource.java b/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultHttpDataSource.java index 93c403e0dc..65bc7078e2 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultHttpDataSource.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/DefaultHttpDataSource.java @@ -42,7 +42,7 @@ import java.util.regex.Matcher; import java.util.regex.Pattern; /** - * A {@link HttpDataSource} that uses Android's {@link HttpURLConnection}. + * An {@link HttpDataSource} that uses Android's {@link HttpURLConnection}. *

* By default this implementation will not follow cross-protocol redirects (i.e. redirects from * HTTP to HTTPS or vice versa). Cross-protocol redirects can be enabled by using the diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/FileDataSource.java b/library/src/main/java/com/google/android/exoplayer2/upstream/FileDataSource.java index 06e8050534..c66374614d 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/FileDataSource.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/FileDataSource.java @@ -24,7 +24,7 @@ import java.io.IOException; import java.io.RandomAccessFile; /** - * A local file {@link DataSource}. + * A {@link DataSource} for reading local files. */ public final class FileDataSource implements DataSource { @@ -46,17 +46,12 @@ public final class FileDataSource implements DataSource { private long bytesRemaining; private boolean opened; - /** - * Constructs a new {@link DataSource} that retrieves data from a file. - */ public FileDataSource() { this(null); } /** - * Constructs a new {@link DataSource} that retrieves data from a file. - * - * @param listener An optional listener. Specify {@code null} for no listener. + * @param listener An optional listener. */ public FileDataSource(TransferListener listener) { this.listener = listener; diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/HttpDataSource.java b/library/src/main/java/com/google/android/exoplayer2/upstream/HttpDataSource.java index 83ae41429a..423bc0d60c 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/HttpDataSource.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/HttpDataSource.java @@ -25,7 +25,7 @@ import java.util.List; import java.util.Map; /** - * An HTTP specific extension to {@link DataSource}. + * An HTTP {@link DataSource}. */ public interface HttpDataSource extends DataSource { @@ -166,9 +166,8 @@ public interface HttpDataSource extends DataSource { void clearAllRequestProperties(); /** - * Gets the headers provided in the response. - * - * @return The response headers, or {@code null} if response headers are unavailable. + * Returns the headers provided in the response, or {@code null} if response headers are + * unavailable. */ Map> getResponseHeaders(); diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/Loader.java b/library/src/main/java/com/google/android/exoplayer2/upstream/Loader.java index 949c982afd..5fd8cffd52 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/Loader.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/Loader.java @@ -56,14 +56,12 @@ public final class Loader { void cancelLoad(); /** - * Whether the load has been canceled. - * - * @return True if the load has been canceled. False otherwise. + * Returns whether the load has been canceled. */ boolean isLoadCanceled(); /** - * Performs the load, returning on completion or cancelation. + * Performs the load, returning on completion or cancellation. * * @throws IOException * @throws InterruptedException @@ -78,10 +76,10 @@ public final class Loader { public interface Callback { /** - * Invoked when a load has completed. + * Called when a load has completed. *

- * There is guaranteed to exist a memory barrier between {@link Loadable#load()} exiting and - * this callback being invoked. + * Note: There is guaranteed to be a memory barrier between {@link Loadable#load()} exiting and + * this callback being called. * * @param loadable The loadable whose load has completed. * @param elapsedRealtimeMs {@link SystemClock#elapsedRealtime} when the load ended. @@ -90,11 +88,11 @@ public final class Loader { void onLoadCompleted(T loadable, long elapsedRealtimeMs, long loadDurationMs); /** - * Invoked when a load has been canceled. + * Called when a load has been canceled. *

- * If the {@link Loader} has not been released then there is guaranteed to exist a memory - * barrier between {@link Loadable#load()} exiting and this callback being invoked. If the - * {@link Loader} has been released then this callback may be invoked before + * Note: If the {@link Loader} has not been released then there is guaranteed to be a memory + * barrier between {@link Loadable#load()} exiting and this callback being called. If the + * {@link Loader} has been released then this callback may be called before * {@link Loadable#load()} exits. * * @param loadable The loadable whose load has been canceled. @@ -106,10 +104,10 @@ public final class Loader { void onLoadCanceled(T loadable, long elapsedRealtimeMs, long loadDurationMs, boolean released); /** - * Invoked when a load encounters an error. + * Called when a load encounters an error. *

- * There is guaranteed to exist a memory barrier between {@link Loadable#load()} exiting and - * this callback being invoked. + * Note: There is guaranteed to be a memory barrier between {@link Loadable#load()} exiting and + * this callback being called. * * @param loadable The loadable whose load has encountered an error. * @param elapsedRealtimeMs {@link SystemClock#elapsedRealtime} when the error occurred. @@ -147,13 +145,13 @@ public final class Loader { } /** - * Start loading a {@link Loadable}. + * Starts loading a {@link Loadable}. *

* The calling thread must be a {@link Looper} thread, which is the thread on which the - * {@link Callback} will be invoked. + * {@link Callback} will be called. * * @param loadable The {@link Loadable} to load. - * @param callback A callback to invoke when the load ends. + * @param callback A callback to called when the load ends. * @param defaultMinRetryCount The minimum number of times the load must be retried before * {@link #maybeThrowError()} will propagate an error. * @throws IllegalStateException If the calling thread does not have an associated {@link Looper}. @@ -169,18 +167,16 @@ public final class Loader { } /** - * Whether the {@link Loader} is currently loading a {@link Loadable}. - * - * @return Whether the {@link Loader} is currently loading a {@link Loadable}. + * Returns whether the {@link Loader} is currently loading a {@link Loadable}. */ public boolean isLoading() { return currentTask != null; } /** - * If a fatal error has been encountered, or if the current {@link Loadable} has incurred a number - * of errors greater than its default minimum number of retries and if the load is currently - * backed off, then an error is thrown. Else does nothing. + * Throws an error if a fatal error has been encountered, or if the current {@link Loadable} has + * incurred a number of errors greater than its default minimum number of retries and if the load + * is currently backed off, then an error is thrown. Else does nothing. * * @throws IOException The error. */ @@ -189,9 +185,9 @@ public final class Loader { } /** - * If a fatal error has been encountered, or if the current {@link Loadable} has incurred a number - * of errors greater than the specified minimum number of retries and if the load is currently - * backed off, then an error is thrown. Else does nothing. + * Throws an error if a fatal error has been encountered, or if the current {@link Loadable} has + * incurred a number of errors greater than the specified minimum number of retries and if the + * load is currently backed off, then an error is thrown. * * @param minRetryCount A minimum retry count that must be exceeded. * @throws IOException The error. @@ -206,27 +202,23 @@ public final class Loader { } /** - * Cancels the current load. - *

- * This method should only be called when a load is in progress. + * Cancels the current load. This method should only be called when a load is in progress. */ public void cancelLoading() { currentTask.cancel(false); } /** - * Releases the {@link Loader}. - *

- * This method should be called when the {@link Loader} is no longer required. + * Releases the {@link Loader}. This method should be called when the {@link Loader} is no longer + * required. */ public void release() { release(null); } /** - * Releases the {@link Loader}, running {@code postLoadAction} on its thread. - *

- * This method should be called when the {@link Loader} is no longer required. + * Releases the {@link Loader}, running {@code postLoadAction} on its thread. This method should + * be called when the {@link Loader} is no longer required. * * @param postLoadAction A {@link Runnable} to run on the loader's thread when * {@link Loadable#load()} is no longer running. diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/ParsingLoadable.java b/library/src/main/java/com/google/android/exoplayer2/upstream/ParsingLoadable.java index 89cfafffe6..616fd6c9b7 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/ParsingLoadable.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/ParsingLoadable.java @@ -39,7 +39,7 @@ public final class ParsingLoadable implements Loadable { /** * Parses an object from a response. * - * @param uri The source of the response, after any redirection. + * @param uri The source {@link Uri} of the response, after any redirection. * @param inputStream An {@link InputStream} from which the response data can be read. * @return The parsed object. * @throws ParserException If an error occurs parsing the data. @@ -87,10 +87,8 @@ public final class ParsingLoadable implements Loadable { } /** - * Returns the number of bytes loaded. - *

- * In the case that the network response was compressed, the value returned is the size of the - * data after decompression. + * Returns the number of bytes loaded. In the case that the network response was compressed, the + * value returned is the size of the data after decompression. * * @return The number of bytes loaded. */ diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/TransferListener.java b/library/src/main/java/com/google/android/exoplayer2/upstream/TransferListener.java index 436b199a5a..9150af462b 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/TransferListener.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/TransferListener.java @@ -16,12 +16,12 @@ package com.google.android.exoplayer2.upstream; /** - * Interface definition for a callback to be notified of data transfer events. + * A listener of data transfer events. */ public interface TransferListener { /** - * Invoked when a transfer starts. + * Called when a transfer starts. */ void onTransferStart(); @@ -34,7 +34,7 @@ public interface TransferListener { void onBytesTransferred(int bytesTransferred); /** - * Invoked when a transfer ends. + * Called when a transfer ends. */ void onTransferEnd(); diff --git a/library/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSink.java b/library/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSink.java index 8066d304b4..5ea47fb30d 100644 --- a/library/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSink.java +++ b/library/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSink.java @@ -64,7 +64,7 @@ public final class CacheDataSink implements DataSink { } @Override - public DataSink open(DataSpec dataSpec) throws CacheDataSinkException { + public void open(DataSpec dataSpec) throws CacheDataSinkException { // TODO: Support caching for unbounded requests. See TODO in {@link CacheDataSource} for // more details. Assertions.checkState(dataSpec.length != C.LENGTH_UNBOUNDED); @@ -72,7 +72,6 @@ public final class CacheDataSink implements DataSink { this.dataSpec = dataSpec; dataSpecBytesWritten = 0; openNextOutputStream(); - return this; } catch (FileNotFoundException e) { throw new CacheDataSinkException(e); } diff --git a/library/src/main/java/com/google/android/exoplayer2/util/ColorParser.java b/library/src/main/java/com/google/android/exoplayer2/util/ColorParser.java index afe6e938e2..6188dad2f3 100644 --- a/library/src/main/java/com/google/android/exoplayer2/util/ColorParser.java +++ b/library/src/main/java/com/google/android/exoplayer2/util/ColorParser.java @@ -44,10 +44,22 @@ public final class ColorParser { private static final Map COLOR_MAP; + /** + * Parses a TTML color expression. + * + * @param colorExpression The color expression. + * @return The parsed ARGB color. + */ public static int parseTtmlColor(String colorExpression) { return parseColorInternal(colorExpression, false); } + /** + * Parses a CSS color expression. + * + * @param colorExpression The color expression. + * @return The parsed ARGB color. + */ public static int parseCssColor(String colorExpression) { return parseColorInternal(colorExpression, true); } diff --git a/library/src/main/java/com/google/android/exoplayer2/util/LongArray.java b/library/src/main/java/com/google/android/exoplayer2/util/LongArray.java index 5869e9c4b5..6d9725ad3d 100644 --- a/library/src/main/java/com/google/android/exoplayer2/util/LongArray.java +++ b/library/src/main/java/com/google/android/exoplayer2/util/LongArray.java @@ -51,7 +51,7 @@ public final class LongArray { } /** - * Gets a value. + * Returns the value at a specified index. * * @param index The index. * @return The corresponding value. @@ -66,9 +66,7 @@ public final class LongArray { } /** - * Gets the current size of the array. - * - * @return The current size of the array. + * Returns the current size of the array. */ public int size() { return size; diff --git a/library/src/main/java/com/google/android/exoplayer2/util/MediaClock.java b/library/src/main/java/com/google/android/exoplayer2/util/MediaClock.java index c6da3a50a6..5f42a40e04 100644 --- a/library/src/main/java/com/google/android/exoplayer2/util/MediaClock.java +++ b/library/src/main/java/com/google/android/exoplayer2/util/MediaClock.java @@ -21,7 +21,7 @@ package com.google.android.exoplayer2.util; public interface MediaClock { /** - * @return The current media position in microseconds. + * Returns the current media position in microseconds. */ long getPositionUs(); diff --git a/library/src/main/java/com/google/android/exoplayer2/util/NalUnitUtil.java b/library/src/main/java/com/google/android/exoplayer2/util/NalUnitUtil.java index c1e463ceb7..09894e3efb 100644 --- a/library/src/main/java/com/google/android/exoplayer2/util/NalUnitUtil.java +++ b/library/src/main/java/com/google/android/exoplayer2/util/NalUnitUtil.java @@ -209,7 +209,7 @@ public final class NalUnitUtil { } /** - * Gets the type of the NAL unit in {@code data} that starts at {@code offset}. + * Returns the type of the NAL unit in {@code data} that starts at {@code offset}. * * @param data The data to search. * @param offset The start offset of a NAL unit. Must lie between {@code -3} (inclusive) and @@ -221,7 +221,7 @@ public final class NalUnitUtil { } /** - * Gets the type of the H.265 NAL unit in {@code data} that starts at {@code offset}. + * Returns the type of the H.265 NAL unit in {@code data} that starts at {@code offset}. * * @param data The data to search. * @param offset The start offset of a NAL unit. Must lie between {@code -3} (inclusive) and diff --git a/library/src/main/java/com/google/android/exoplayer2/util/ParsableBitArray.java b/library/src/main/java/com/google/android/exoplayer2/util/ParsableBitArray.java index 87bc9c3b01..c8d9cd47d4 100644 --- a/library/src/main/java/com/google/android/exoplayer2/util/ParsableBitArray.java +++ b/library/src/main/java/com/google/android/exoplayer2/util/ParsableBitArray.java @@ -28,7 +28,9 @@ public final class ParsableBitArray { private int bitOffset; private int byteLimit; - /** Creates a new instance that initially has no backing data. */ + /** + * Creates a new instance that initially has no backing data. + */ public ParsableBitArray() {} /** @@ -81,9 +83,7 @@ public final class ParsableBitArray { } /** - * Gets the current bit offset. - * - * @return The current bit offset. + * Returns the current bit offset. */ public int getPosition() { return byteOffset * 8 + bitOffset; diff --git a/library/src/main/java/com/google/android/exoplayer2/util/ParsableByteArray.java b/library/src/main/java/com/google/android/exoplayer2/util/ParsableByteArray.java index 42f0c5a6d7..8f32e01642 100644 --- a/library/src/main/java/com/google/android/exoplayer2/util/ParsableByteArray.java +++ b/library/src/main/java/com/google/android/exoplayer2/util/ParsableByteArray.java @@ -29,16 +29,22 @@ public final class ParsableByteArray { private int position; private int limit; - /** Creates a new instance that initially has no backing data. */ + /** + * Creates a new instance that initially has no backing data. + */ public ParsableByteArray() {} - /** Creates a new instance with {@code length} bytes. */ + /** + * Creates a new instance with {@code length} bytes. + */ public ParsableByteArray(int length) { this.data = new byte[length]; limit = data.length; } - /** Creates a new instance wrapping {@code data}. */ + /** + * Creates a new instance wrapping {@code data}. + */ public ParsableByteArray(byte[] data) { this.data = data; limit = data.length; @@ -75,12 +81,16 @@ public final class ParsableByteArray { limit = 0; } - /** Returns the number of bytes yet to be read. */ + /** + * Returns the number of bytes yet to be read. + */ public int bytesLeft() { return limit - position; } - /** Returns the limit. */ + /** + * Returns the limit. + */ public int limit() { return limit; } @@ -95,12 +105,16 @@ public final class ParsableByteArray { this.limit = limit; } - /** Returns the current offset in the array, in bytes. */ + /** + * Returns the current offset in the array, in bytes. + */ public int getPosition() { return position; } - /** Returns the capacity of the array, which may be larger than the limit. */ + /** + * Returns the capacity of the array, which may be larger than the limit. + */ public int capacity() { return data == null ? 0 : data.length; } @@ -160,55 +174,73 @@ public final class ParsableByteArray { position += length; } - /** Reads the next byte as an unsigned value. */ + /** + * Reads the next byte as an unsigned value. + */ public int readUnsignedByte() { return (data[position++] & 0xFF); } - /** Reads the next two bytes as an unsigned value. */ + /** + * Reads the next two bytes as an unsigned value. + */ public int readUnsignedShort() { return (data[position++] & 0xFF) << 8 | (data[position++] & 0xFF); } - /** Reads the next two bytes as an unsigned value. */ + /** + * Reads the next two bytes as an unsigned value. + */ public int readLittleEndianUnsignedShort() { return (data[position++] & 0xFF) | (data[position++] & 0xFF) << 8; } - /** Reads the next two bytes as an signed value. */ + /** + * Reads the next two bytes as an signed value. + */ public short readShort() { return (short) ((data[position++] & 0xFF) << 8 | (data[position++] & 0xFF)); } - /** Reads the next two bytes as a signed value. */ + /** + * Reads the next two bytes as a signed value. + */ public short readLittleEndianShort() { return (short) ((data[position++] & 0xFF) | (data[position++] & 0xFF) << 8); } - /** Reads the next three bytes as an unsigned value. */ + /** + * Reads the next three bytes as an unsigned value. + */ public int readUnsignedInt24() { return (data[position++] & 0xFF) << 16 | (data[position++] & 0xFF) << 8 | (data[position++] & 0xFF); } - /** Reads the next three bytes as a signed value in little endian order. */ + /** + * Reads the next three bytes as a signed value in little endian order. + */ public int readLittleEndianInt24() { return (data[position++] & 0xFF) | (data[position++] & 0xFF) << 8 | (data[position++] & 0xFF) << 16; } - /** Reads the next three bytes as an unsigned value in little endian order. */ + /** + * Reads the next three bytes as an unsigned value in little endian order. + */ public int readLittleEndianUnsignedInt24() { return (data[position++] & 0xFF) | (data[position++] & 0xFF) << 8 | (data[position++] & 0xFF) << 16; } - /** Reads the next four bytes as an unsigned value. */ + /** + * Reads the next four bytes as an unsigned value. + */ public long readUnsignedInt() { return (data[position++] & 0xFFL) << 24 | (data[position++] & 0xFFL) << 16 @@ -216,7 +248,9 @@ public final class ParsableByteArray { | (data[position++] & 0xFFL); } - /** Reads the next four bytes as an unsigned value in little endian order. */ + /** + * Reads the next four bytes as an unsigned value in little endian order. + */ public long readLittleEndianUnsignedInt() { return (data[position++] & 0xFFL) | (data[position++] & 0xFFL) << 8 @@ -224,7 +258,9 @@ public final class ParsableByteArray { | (data[position++] & 0xFFL) << 24; } - /** Reads the next four bytes as a signed value. */ + /** + * Reads the next four bytes as a signed value + */ public int readInt() { return (data[position++] & 0xFF) << 24 | (data[position++] & 0xFF) << 16 @@ -232,7 +268,9 @@ public final class ParsableByteArray { | (data[position++] & 0xFF); } - /** Reads the next four bytes as an signed value in little endian order. */ + /** + * Reads the next four bytes as an signed value in little endian order. + */ public int readLittleEndianInt() { return (data[position++] & 0xFF) | (data[position++] & 0xFF) << 8 @@ -240,7 +278,9 @@ public final class ParsableByteArray { | (data[position++] & 0xFF) << 24; } - /** Reads the next eight bytes as a signed value. */ + /** + * Reads the next eight bytes as a signed value. + */ public long readLong() { return (data[position++] & 0xFFL) << 56 | (data[position++] & 0xFFL) << 48 @@ -252,7 +292,9 @@ public final class ParsableByteArray { | (data[position++] & 0xFFL); } - /** Reads the next eight bytes as a signed value in little endian order. */ + /** + * Reads the next eight bytes as a signed value in little endian order. + */ public long readLittleEndianLong() { return (data[position++] & 0xFFL) | (data[position++] & 0xFFL) << 8 @@ -264,7 +306,9 @@ public final class ParsableByteArray { | (data[position++] & 0xFFL) << 56; } - /** Reads the next four bytes, returning the integer portion of the fixed point 16.16 integer. */ + /** + * Reads the next four bytes, returning the integer portion of the fixed point 16.16 integer. + */ public int readUnsignedFixedPoint1616() { int result = (data[position++] & 0xFF) << 8 | (data[position++] & 0xFF); @@ -328,7 +372,9 @@ public final class ParsableByteArray { return result; } - /** Reads the next eight bytes as a 64-bit floating point value. */ + /** + * Reads the next eight bytes as a 64-bit floating point value. + */ public double readDouble() { return Double.longBitsToDouble(readLong()); } @@ -398,6 +444,7 @@ public final class ParsableByteArray { /** * Reads a long value encoded by UTF-8 encoding + * * @throws NumberFormatException if there is a problem with decoding * @return Decoded long value */ diff --git a/library/src/main/java/com/google/android/exoplayer2/util/PriorityTaskManager.java b/library/src/main/java/com/google/android/exoplayer2/util/PriorityTaskManager.java index d2619e6b98..cc6a17913b 100644 --- a/library/src/main/java/com/google/android/exoplayer2/util/PriorityTaskManager.java +++ b/library/src/main/java/com/google/android/exoplayer2/util/PriorityTaskManager.java @@ -52,9 +52,7 @@ public final class PriorityTaskManager { } /** - * Register a new task. - *

- * The task must call {@link #remove(int)} when done. + * Register a new task. The task must call {@link #remove(int)} when done. * * @param priority The priority of the task. */ diff --git a/library/src/main/java/com/google/android/exoplayer2/util/SlidingPercentile.java b/library/src/main/java/com/google/android/exoplayer2/util/SlidingPercentile.java index 32ef6c4c21..8b1af1f0c8 100644 --- a/library/src/main/java/com/google/android/exoplayer2/util/SlidingPercentile.java +++ b/library/src/main/java/com/google/android/exoplayer2/util/SlidingPercentile.java @@ -20,13 +20,14 @@ import java.util.Collections; import java.util.Comparator; /** - * Calculate any percentile over a sliding window of weighted values. A maximum total weight is - * configured. Once the maximum weight is reached, the oldest value is reduced in weight until it - * reaches zero and is removed. This maintains a constant total weight at steady state. + * Calculate any percentile over a sliding window of weighted values. A maximum weight is + * configured. Once the total weight of the values reaches the maximum weight, the oldest value is + * reduced in weight until it reaches zero and is removed. This maintains a constant total weight, + * equal to the maximum allowed, at the steady state. *

- * SlidingPercentile can be used for bandwidth estimation based on a sliding window of past - * download rate observations. This is an alternative to sliding mean and exponential averaging - * which suffer from susceptibility to outliers and slow adaptation to step functions. + * This class can be used for bandwidth estimation based on a sliding window of past transfer rate + * observations. This is an alternative to sliding mean and exponential averaging which suffer from + * susceptibility to outliers and slow adaptation to step functions. * * @see Wiki: Moving average * @see Wiki: Selection algorithm @@ -64,6 +65,9 @@ public final class SlidingPercentile { private int totalWeight; private int recycledSampleCount; + /** + * @param maxWeight The maximum weight. + */ public SlidingPercentile(int maxWeight) { this.maxWeight = maxWeight; recycledSamples = new Sample[MAX_RECYCLED_SAMPLES]; @@ -72,8 +76,7 @@ public final class SlidingPercentile { } /** - * Record a new observation. Respect the configured total weight by reducing in weight or - * removing the oldest observations as required. + * Adds a new weighted value. * * @param weight The weight of the new observation. * @param value The value of the new observation. @@ -106,10 +109,10 @@ public final class SlidingPercentile { } /** - * Compute the percentile by integration. + * Computes a percentile by integration. * * @param percentile The desired percentile, expressed as a fraction in the range (0,1]. - * @return The requested percentile value or Float.NaN. + * @return The requested percentile value or {@link Float#NaN} if no samples have been added. */ public float getPercentile(float percentile) { ensureSortedByValue(); @@ -127,7 +130,7 @@ public final class SlidingPercentile { } /** - * Sort the samples by index, if not already. + * Sorts the samples by index. */ private void ensureSortedByIndex() { if (currentSortOrder != SORT_ORDER_BY_INDEX) { @@ -137,7 +140,7 @@ public final class SlidingPercentile { } /** - * Sort the samples by value, if not already. + * Sorts the samples by value. */ private void ensureSortedByValue() { if (currentSortOrder != SORT_ORDER_BY_VALUE) { diff --git a/library/src/main/java/com/google/android/exoplayer2/util/XmlPullParserUtil.java b/library/src/main/java/com/google/android/exoplayer2/util/XmlPullParserUtil.java index e49f9d8038..93830b6755 100644 --- a/library/src/main/java/com/google/android/exoplayer2/util/XmlPullParserUtil.java +++ b/library/src/main/java/com/google/android/exoplayer2/util/XmlPullParserUtil.java @@ -25,23 +25,61 @@ public final class XmlPullParserUtil { private XmlPullParserUtil() {} + /** + * Returns whether the current event is an end tag with the specified name. + * + * @param xpp The {@link XmlPullParser} to query. + * @param name The specified name. + * @return True if the current event is an end tag with the specified name. False otherwise. + * @throws XmlPullParserException If an error occurs querying the parser. + */ public static boolean isEndTag(XmlPullParser xpp, String name) throws XmlPullParserException { return isEndTag(xpp) && xpp.getName().equals(name); } + /** + * Returns whether the current event is an end tag. + * + * @param xpp The {@link XmlPullParser} to query. + * @return True if the current event is an end tag. False otherwise. + * @throws XmlPullParserException If an error occurs querying the parser. + */ public static boolean isEndTag(XmlPullParser xpp) throws XmlPullParserException { return xpp.getEventType() == XmlPullParser.END_TAG; } + /** + * Returns whether the current event is a start tag with the specified name. + * + * @param xpp The {@link XmlPullParser} to query. + * @param name The specified name. + * @return True if the current event is a start tag with the specified name. False otherwise. + * @throws XmlPullParserException If an error occurs querying the parser. + */ public static boolean isStartTag(XmlPullParser xpp, String name) throws XmlPullParserException { return isStartTag(xpp) && xpp.getName().equals(name); } + /** + * Returns whether the current event is a start tag. + * + * @param xpp The {@link XmlPullParser} to query. + * @return True if the current event is a start tag. False otherwise. + * @throws XmlPullParserException If an error occurs querying the parser. + */ public static boolean isStartTag(XmlPullParser xpp) throws XmlPullParserException { return xpp.getEventType() == XmlPullParser.START_TAG; } + /** + * Returns the value of an attribute of the current start tag. + * + * @param xpp The {@link XmlPullParser} to query. + * @param attributeName The name of the attribute. + * @return The value of the attribute, or null if the current event is not a start tag or if no + * no such attribute was found. + */ public static String getAttributeValue(XmlPullParser xpp, String attributeName) { int attributeCount = xpp.getAttributeCount(); for (int i = 0; i < attributeCount; i++) {