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 aRemoteMediaClient
object and has the same lifecycle of the attachedRemoteMediaClient
.
This meansMediaQueue
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 attachedRemoteMediaClient
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) ofMediaQueueItem
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 onRemoteMediaClient
),
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.
GenerallyRemoteMediaClient
identifies queue items by their item ID, whileMediaQueue
keeps tracks the mapping between their item IDs and their indexes. Most of the interfaces
presented to the user ofMediaQueue
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
publicPendingResult<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
andprevCount
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 MediaQueueItemgetItemAtIndex(int index)
Returns theMediaQueueItem
at the given index.
If the index is out of bounds, returnsnull
.
If the item is not cached, returnsnull
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 MediaQueueItemgetItemAtIndex(int index, boolean fetchIfNeeded)
Returns theMediaQueueItem
at the given index.
If the index is out of bounds, returnsnull
.
If the item is not cached, returnsnull
.IffetchIfNeeded
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 theMediaQueueItem |
---|---|
fetchIfNeeded | whether to fetch theMediaQueueItem
if it is not cached |
Throws
IllegalStateException | if this method is not called on the main thread. |
---|
public intgetItemCount()
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 intindexOfItemWithId(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 intitemIdAtIndex(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 voidregisterCallback(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 voidsetCacheCapacity(int capacity)
Sets the capacity of the cache of the queue.
Throws
IllegalStateException | if this method is not called on the main thread. |
---|
public voidunregisterCallback(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. |
---|