Skip to content

Handling Media Resources

You can download media resource (also known as media streams) during store open and download. Set the automaticallyRetrieveStream parameter to true when constructing the OfflineODataDefiningQuery. There are three types of OfflineODataDefiningQuery:

  • Type 1: A defining query that identifies one or more entities where the automaticallyRetrievesStreams parameter is set to false. In this case, even if the defining query identifies media entities, the media streams will not be downloaded.

  • Type 2: A defining query that identifies one or more entities, some of which may be media entities, and where the automaticallyRetrievesStreams parameter is set to true. In this case, the media streams will be downloaded as well for media entities.

  • Type 3: A defining query that identifies a single media entity and the automaticallyRetrievesStreams parameter is set to true. The URL specified in this case MUST be the read link of the media entity, not the read link of the media stream. For example, if the media entity's read link is Documents(101) and the media stream's read link is Documents(101)/$value, the expected URL of the defining query is Documents(101).

You can add defining queries of type 1 and 2 before or after the offline store is opened. Essentially, they can be added at any time. However, you can only remove defining queries of these types before the store is initially opened. After first open, removal is not allowed.

You can add defining queries of type 3 before or after the offline store has been opened. Defining queries of type 3 can be removed after the offline store has been opened to stop future download of the media streams.

// Type 1 defining query with media entity set Photos.
// Set automaticallyRetrieveStream to false to skip downloading media
// streams for photos when opening the offline store.
// This can be done before or after initial open of the offline store
offlineODataProvider.addDefiningQuery(new OfflineODataDefiningQuery("Photos", "/Photos", false));

// Open the offline store

// Type 3 defining query to download media streams of specific photos
offlineODataDefiningQuery photo1dq = new OfflineODataDefiningQuery("Photo1", "/Photos(1)", true));
offlineODataDefiningQuery photo2dq = new OfflineODataDefiningQuery("Photo2", "/Photos(2)", true));

Then, you can perform download to get the media resources.

// Perform download using the subset feature to only download the newly
// added media resource defining queries
List<OfflineODataDefiningQuery> mediaQueries = new ArrayList<OfflineODataDefiningQuery>();
                 ()-> {
                     // Download completed successfully. Notify application for appropriate action
                 (error) -> {
                     // Handle the error

When a media resource is no longer needed, you can remove it by removing the defining query:

// No longer need photo with id = 1

The application can create new media streams, and then update them even if automaticallyRetrieveStream is false. You can also delete a media stream (by deleting the media entity) if automaticallyRetrieveStream is false. However, you cannot update the media stream of a media entity that was downloaded from the back end when the defining query has automaticallyRetrieveStream set to false since the media stream is not available in the offline store. In this case, you'd need to perform an online request to update the media stream itself.


Defining queries added without opening offline store aren't persisted. If the application terminates, they will be lost.

Offline OData does not support the stream property. Stream-related methods such as uploadStream(), deleteStream(), and downloadStream() operate only on a media entity’s media stream. The method deleteStream() does the same as the deleteEntity() method.

Last update: November 24, 2020