# MediaQueue

public class **MediaQueue** extends [Object](https://developer.android.com/reference/java/lang/Object.html)  
A data model representation of a media queue of arbitrary length. This class can be used
as the basis for an implementation of a ListView for driving a media queue UI.

`https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue`
is attached to a `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/RemoteMediaClient`
object and has the same lifecycle of the attached `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/RemoteMediaClient`.
This means `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue`
is only valid when a Cast session has started or resumed. When there's no Cast session,
clients should stop using this class.

It listens for queue change notifications from the attached `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/RemoteMediaClient`
and updates its internal data model accordingly. Likewise, it uses the attached
`https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/RemoteMediaClient` to fetch queue information on demand.

The model maintains a list of queue item IDs for the entire queue; it automatically
fetches this list whenever it attaches to a Cast session. It also maintains an LRU cache (of
configurable size) of `https://developers.google.com/android/reference/com/google/android/gms/cast/MediaQueueItem`s,
keyed by the queue item ID. The default cache size is 20. If the UI may display more than 20
items at the same time, it is possible that the items will compete with each other and they
keep getting evicted and refetched. To avoid this, increase the cache capacity by calling
`https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#setCacheCapacity(int)`.

The method `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#getItemAtIndex(int)` is used to fetch a queue item at a given index. If the
`https://developers.google.com/android/reference/com/google/android/gms/cast/MediaQueueItem`
is not currently in the cache, an asynchronous request is made to fetch that item from the
receiver, and the listener is eventually notified when the requested items are received.

If multiple calls to this method are made in a very short amount of time, the requested
item IDs are batched internally to reduce the number of network requests made. Because there
is an upper limit to how many queue items can be fetched from the receiver at a time,
`https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue`
keeps a rolling window of the last N item IDs to be fetched. Therefore if a very large number
of items is requested in a short amount of time, only the last N items will actually be
fetched. This behavior allows for the efficient management of a very long queue in the app's
UI which may be quickly and/or frequently scrolled through by a user.

`https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue`
does not provide any methods for directly modifying the queue, because any such change
involves an asynchronous network request to the receiver (via methods on `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/RemoteMediaClient`),
which can potentially fail with an error. `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue`
must ensure a consistent representation of the queue as it exists on the receiver, so making
local changes to the data model which are not yet committed on the receiver could result in
incorrect UI behavior.

Generally `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/RemoteMediaClient`
identifies queue items by their item ID, while `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue`
keeps tracks the mapping between their item IDs and their indexes. Most of the interfaces
presented to the user of `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue`
are by index, which is convenient for UI purposes.

### Nested Class Summary

|---|---|---|---|
| class | [MediaQueue.Callback](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback) || Callback interface for receiving updates from `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue`. |

### Public Method Summary

|---|---|
| [PendingResult](https://developers.google.com/android/reference/com/google/android/gms/common/api/PendingResult)\<[RemoteMediaClient.MediaChannelResult](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/RemoteMediaClient.MediaChannelResult)\> | [fetchMoreItemsRelativeToIndex](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#fetchMoreItemsRelativeToIndex(int,%20int,%20int))(int index, int nextCount, int prevCount) Requests a range of queue item IDs before or after the given index in the queue. |
| MediaQueueItem | [getItemAtIndex](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#getItemAtIndex(int))(int index) Returns the `https://developers.google.com/android/reference/com/google/android/gms/cast/MediaQueueItem` at the given index. |
| MediaQueueItem | [getItemAtIndex](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#getItemAtIndex(int,%20boolean))(int index, boolean fetchIfNeeded) Returns the `https://developers.google.com/android/reference/com/google/android/gms/cast/MediaQueueItem` at the given index. |
| int | [getItemCount](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#getItemCount())() Returns the number of items in the queue. |
| int\[\] | [getItemIds](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#getItemIds())() Returns the list of item IDs in the queue. |
| int | [indexOfItemWithId](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#indexOfItemWithId(int))(int itemId) Looks up the index of a queue item in the queue. |
| int | [itemIdAtIndex](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#itemIdAtIndex(int))(int index) Returns the item ID of the item at the given index in the queue. |
| void | [registerCallback](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#registerCallback(com.google.android.gms.cast.framework.media.MediaQueue.Callback))([MediaQueue.Callback](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback) callback) Registers a `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback` to receive media queue updates. |
| void | [setCacheCapacity](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#setCacheCapacity(int))(int capacity) Sets the capacity of the cache of the queue. |
| void | [unregisterCallback](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue#unregisterCallback(com.google.android.gms.cast.framework.media.MediaQueue.Callback))([MediaQueue.Callback](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback) callback) Unregisters a `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback` to stop receiving media queue updates. |

### Inherited Method Summary

From class java.lang.Object

|---|---|
| [Object](https://developer.android.com/reference/java/lang/Object.html) | clone() |
| boolean | equals([Object](https://developer.android.com/reference/java/lang/Object.html) arg0) |
| void | finalize() |
| final [Class](https://developer.android.com/reference/java/lang/Class.html)\<?\> | getClass() |
| int | hashCode() |
| final void | notify() |
| final void | notifyAll() |
| [String](https://developer.android.com/reference/java/lang/String.html) | toString() |
| final void | wait(long arg0, int arg1) |
| final void | wait(long arg0) |
| final void | wait() |

## Public Methods

#### public [PendingResult](https://developers.google.com/android/reference/com/google/android/gms/common/api/PendingResult)\<[RemoteMediaClient.MediaChannelResult](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/RemoteMediaClient.MediaChannelResult)\>
**fetchMoreItemsRelativeToIndex** (int index, int nextCount, int prevCount)

Requests a range of queue item IDs before or after the given index in the queue.

This method is intended to be used when the remote queue is partially full and the
sender wants the receiver to fetch more queue items (for example, from the cloud),
usually before the beginning of the queue or after the end of the queue. If new items
are fetched, the media queue notifies the clients through `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback#itemsInsertedInRange(int,%20int)`. Note that this method is
intended to be used when the UI scrolls to the top or bottom of the queue and the
client wants the receiver to fetch more items from the client. Exactly one of
`nextCount` and `prevCount` must be non-zero.

##### Parameters

| index | the index of the item relative to which more items should be fetched |
| nextCount | the maximum number of item IDs to fetch before the index. It can be 0 |
| prevCount | the maximum number of item IDs to fetch after the index. It can be 0 |
|---|---|

##### Returns

- the `https://developers.google.com/android/reference/com/google/android/gms/common/api/PendingResult` object for tracking this request

#### public MediaQueueItem **getItemAtIndex** (int index)

Returns the `https://developers.google.com/android/reference/com/google/android/gms/cast/MediaQueueItem`
at the given index.

If the index is out of bounds, returns `null`.

If the item is not cached, returns `null` and put the index into the list
of item IDs to fetch and arranges for the item to be fetched asynchronously. Calling
this method too frequently might make earlier fetches get abandoned.

When the item is fetched, `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback#itemsUpdatedAtIndexes(int[])` will be called.

##### Throws

| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException.html) | if this method is not called on the main thread. |
|---|---|

#### public MediaQueueItem **getItemAtIndex** (int index, boolean fetchIfNeeded)

Returns the `https://developers.google.com/android/reference/com/google/android/gms/cast/MediaQueueItem`
at the given index.

If the index is out of bounds, returns `null`.

If the item is not cached, returns `null`. If `fetchIfNeeded`
is true, put the index into the list of item IDs to fetch arranges for the item to be
fetched asynchronously. Calling this method too frequently might make earlier fetches
get abandoned.

When the item is fetched, `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback#itemsUpdatedAtIndexes(int[])` will be called.

##### Parameters

| index | the index of the `https://developers.google.com/android/reference/com/google/android/gms/cast/MediaQueueItem` |
| fetchIfNeeded | whether to fetch the `https://developers.google.com/android/reference/com/google/android/gms/cast/MediaQueueItem` if it is not cached |
|---|---|

##### Throws

| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException.html) | if this method is not called on the main thread. |
|---|---|

#### public int **getItemCount** ()

Returns the number of items in the queue.

##### Throws

| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException.html) | if this method is not called on the main thread. |
|---|---|

#### public int\[\] **getItemIds** ()

Returns the list of item IDs in the queue.

##### Throws

| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException.html) | if this method is not called on the main thread. |
|---|---|

#### public int **indexOfItemWithId** (int itemId)

Looks up the index of a queue item in the queue. Returns -1 if not found.

##### Parameters

| itemId | the queue item ID |
|---|---|

##### Throws

| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException.html) | if this method is not called on the main thread. |
|---|---|

#### public int **itemIdAtIndex** (int index)

Returns the item ID of the item at the given index in the queue. Returns
`https://developers.google.com/android/reference/com/google/android/gms/cast/MediaQueueItem#INVALID_ITEM_ID`
if the index out of bounds.

##### Throws

| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException.html) | if this method is not called on the main thread. |
|---|---|

#### public void **registerCallback** ([MediaQueue.Callback](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback) callback)

Registers a `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback` to receive media queue updates. Remember to unregister
the callback when it's not used to avoid memory leak.

##### Throws

| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException.html) | if this method is not called on the main thread. |
|---|---|

#### public void **setCacheCapacity** (int capacity)

Sets the capacity of the cache of the queue.

##### Throws

| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException.html) | if this method is not called on the main thread. |
|---|---|

#### public void **unregisterCallback** ([MediaQueue.Callback](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback) callback)

Unregisters a `https://developers.google.com/android/reference/com/google/android/gms/cast/framework/media/MediaQueue.Callback` to stop receiving media queue updates.

##### Throws

| [IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException.html) | if this method is not called on the main thread. |
|---|---|