sjs/media
1
0
Fork 0
mirror of https://github.com/samsonjs/media.git synced 2026-03-27 09:45:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Consistent Javadoc for upstream package

Browse source 
-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=128159118
This commit is contained in:
olly 2016-07-22 03:39:12 -07:00 committed by Oliver Woodman
parent 692d756ee6
commit f0b73e5d5b
31 changed files with 274 additions and 185 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
library/src/main/java/com/google/android/exoplayer2/upstream/Allocation.java
View file

@ -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;

12
library/src/main/java/com/google/android/exoplayer2/upstream/Allocator.java
View file

@ -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();

9
library/src/main/java/com/google/android/exoplayer2/upstream/AssetDataSource.java
View file

@ -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();

16
library/src/main/java/com/google/android/exoplayer2/upstream/BandwidthMeter.java
View file

@ -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.
* <p>
* 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();

8
library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSink.java
View file

@ -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();

1
library/src/main/java/com/google/android/exoplayer2/upstream/ByteArrayDataSource.java
View file

@ -78,4 +78,3 @@ public final class ByteArrayDataSource implements DataSource {
}
}

9
library/src/main/java/com/google/android/exoplayer2/upstream/ContentDataSource.java
View file

@ -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();

25
library/src/main/java/com/google/android/exoplayer2/upstream/DataSink.java
View file

@ -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;
}

28
library/src/main/java/com/google/android/exoplayer2/upstream/DataSource.java
View file

@ -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.
* <p>
* 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}.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.

2
library/src/main/java/com/google/android/exoplayer2/upstream/DataSourceInputStream.java
View file

@ -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 {

4
library/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java
View file

@ -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;
/**

10
library/src/main/java/com/google/android/exoplayer2/upstream/DefaultAllocator.java
View file

@ -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.
* <p>
* 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) {

7
library/src/main/java/com/google/android/exoplayer2/upstream/DefaultBandwidthMeter.java
View file

@ -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;

4
library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSource.java
View file

@ -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).
*/

31
library/src/main/java/com/google/android/exoplayer2/upstream/DefaultDataSourceFactory.java
View file

@ -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);
}
}

2
library/src/main/java/com/google/android/exoplayer2/upstream/DefaultHttpDataSource.java
View file

@ -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}.
* <p>
* 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

9
library/src/main/java/com/google/android/exoplayer2/upstream/FileDataSource.java
View file

@ -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;

7
library/src/main/java/com/google/android/exoplayer2/upstream/HttpDataSource.java
View file

@ -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<String, List<String>> getResponseHeaders();

62
library/src/main/java/com/google/android/exoplayer2/upstream/Loader.java
View file

@ -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<T extends Loadable> {
/**
* Invoked when a load has completed.
* Called when a load has completed.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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}.
* <p>
* 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.
* <p>
* 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}.
* <p>
* 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.
* <p>
* 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.

8
library/src/main/java/com/google/android/exoplayer2/upstream/ParsingLoadable.java
View file

@ -39,7 +39,7 @@ public final class ParsingLoadable<T> 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<T> implements Loadable {
}
/**
* Returns the number of bytes loaded.
* <p>
* In the case that the network response was compressed, the value returned is the size of the
* data <em>after</em> 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 <em>after</em> decompression.
*
* @return The number of bytes loaded.
*/

6
library/src/main/java/com/google/android/exoplayer2/upstream/TransferListener.java
View file

@ -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();

3
library/src/main/java/com/google/android/exoplayer2/upstream/cache/CacheDataSink.java vendored
View file

@ -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);
}

12
library/src/main/java/com/google/android/exoplayer2/util/ColorParser.java
View file

@ -44,10 +44,22 @@ public final class ColorParser {
private static final Map<String, Integer> 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);
}

6
library/src/main/java/com/google/android/exoplayer2/util/LongArray.java
View file

@ -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;

2
library/src/main/java/com/google/android/exoplayer2/util/MediaClock.java
View file

@ -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();

4
library/src/main/java/com/google/android/exoplayer2/util/NalUnitUtil.java
View file

@ -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

8
library/src/main/java/com/google/android/exoplayer2/util/ParsableBitArray.java
View file

@ -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;

93
library/src/main/java/com/google/android/exoplayer2/util/ParsableByteArray.java
View file

@ -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
*/

4
library/src/main/java/com/google/android/exoplayer2/util/PriorityTaskManager.java
View file

@ -52,9 +52,7 @@ public final class PriorityTaskManager {
}
/**
* Register a new task.
* <p>
* 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.
*/

27
library/src/main/java/com/google/android/exoplayer2/util/SlidingPercentile.java
View file

@ -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.
* <p>
* 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 <a href="http://en.wikipedia.org/wiki/Moving_average">Wiki: Moving average</a>
* @see <a href="http://en.wikipedia.org/wiki/Selection_algorithm">Wiki: Selection algorithm</a>
@ -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) {

38
library/src/main/java/com/google/android/exoplayer2/util/XmlPullParserUtil.java
View file

@ -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++) {