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.
MediaQueue
is attached to a RemoteMediaClient
object and has the same lifecycle of the attached RemoteMediaClient
.
This means 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 RemoteMediaClient
and updates its internal data model accordingly. Likewise, it uses the attached
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 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
setCacheCapacity(int)
.
The method
getItemAtIndex(int)
is used to fetch a queue item at a given index. If the
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,
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.
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 RemoteMediaClient
),
which can potentially fail with an error. 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 RemoteMediaClient
identifies queue items by their item ID, while MediaQueue
keeps tracks the mapping between their item IDs and their indexes. Most of the interfaces
presented to the user of MediaQueue
are by index, which is convenient for UI purposes.
Nested Class Summary
class | MediaQueue.Callback | Callback interface for receiving updates from
MediaQueue . |
Public Method Summary
PendingResult<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.
|
MediaQueueItem |
getItemAtIndex(int index)
Returns the
MediaQueueItem
at the given index.
|
MediaQueueItem |
getItemAtIndex(int index, boolean fetchIfNeeded)
Returns the
MediaQueueItem
at the given index.
|
int |
getItemCount()
Returns the number of items in the queue.
|
int[] |
getItemIds()
Returns the list of item IDs in the queue.
|
int |
indexOfItemWithId(int itemId)
Looks up the index of a queue item in the queue.
|
int |
itemIdAtIndex(int index)
Returns the item ID of the item at the given index in the queue.
|
void |
registerCallback(MediaQueue.Callback
callback)
Registers a
MediaQueue.Callback to receive media queue updates.
|
void |
setCacheCapacity(int capacity)
Sets the capacity of the cache of the queue.
|
void |
unregisterCallback(MediaQueue.Callback
callback)
Unregisters a
MediaQueue.Callback to stop receiving media queue updates.
|
Inherited Method Summary
Public Methods
public PendingResult<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
MediaQueue.Callback.itemsInsertedInRange(int, int)
. 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
PendingResult
object for tracking this request
public MediaQueueItem getItemAtIndex (int index)
Returns the 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,
MediaQueue.Callback.itemsUpdatedAtIndexes(int[])
will be called.
Throws
IllegalStateException | if this method is not called on the main thread. |
---|
public MediaQueueItem getItemAtIndex (int index, boolean fetchIfNeeded)
Returns the 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,
MediaQueue.Callback.itemsUpdatedAtIndexes(int[])
will be called.
Parameters
index | the index of the MediaQueueItem |
---|---|
fetchIfNeeded | whether to fetch the MediaQueueItem
if it is not cached |
Throws
IllegalStateException | if this method is not called on the main thread. |
---|
public int getItemCount ()
Returns the number of items in the queue.
Throws
IllegalStateException | if this method is not called on the main thread. |
---|
public int[] getItemIds ()
Returns the list of item IDs in the queue.
Throws
IllegalStateException | 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 | 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
MediaQueueItem.INVALID_ITEM_ID
if the index out of bounds.
Throws
IllegalStateException | if this method is not called on the main thread. |
---|
public void registerCallback (MediaQueue.Callback callback)
Registers a
MediaQueue.Callback
to receive media queue updates. Remember to unregister
the callback when it's not used to avoid memory leak.
Throws
IllegalStateException | 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 | if this method is not called on the main thread. |
---|
public void unregisterCallback (MediaQueue.Callback callback)
Unregisters a
MediaQueue.Callback
to stop receiving media queue updates.
Throws
IllegalStateException | if this method is not called on the main thread. |
---|