fetch

Synchronously fetches a resource from this ResourceProvider using the provided url. The method returns when a successful response is available, or throws an exception on failure.

The returned response object includes metadata about the resource and methods for reading the resource body.

Relative URLs

If this ResourceProvider has a baseUrl, the implementation will use that baseUrl when resolving relative URLs. For example, If the ResourceProvider has the baseUrl "com.colibrio://xyz/", then the following URLs will target the same resource:

• "index.html"

• "com.colibrio://xyz/index.html"

If the ResourceProvider has no baseURL, then calling this method with a relative URL will cause InvalidUrlException to be thrown.

URL encoding

The passed url MAY contain URL encoded (percent-encoded) path segments using the UTF-8 character set. The implementation MUST normalize the path segment encoding so that it is insensitive to how it is encoded. For example, the following URLs MUST resolve to the same resource:

• 'cool movie.mp4'

• 'cool%20movie.mp4'

It is recommended that implementations use UriUtils.normalizePathnameEncoding to maximize compatibility with the framework.

Options

The options parameter configures how to fetch the resource. If an options parameter isn't defined, the implementation use the default values specified in ResourceRequestOptions.

Resources MAY support partial fetching by specifying options.range. Use fetchMetadata and check the ResourceMetadata.acceptsRanges property to check if the resource supports it. If you pass options.range and the ResourceProvider doesn't support partial fetching for the given resource, this method throws an RangeRequestNotSupportedException.

Thread safety

This method may be called by multiple threads in parallel. As the method blocks until a Response is available, it should not be called on the Main thread.

Error handling and retry handling

Some data transport mediums are prone to errors. For example, a HTTP Resource Provider implementation fetching resource from the Internet SHOULD internally retry requests if the user temporarily loses internet connection. Once the data is successfully retrieved, the implementation returns a Response.

For longer interruptions (decided by the implementation), the implementation SHOULD throw an ResourceUnavailableException to indicate to the framework that the resource could be fetched sometime in the future.

Parameters

Throws

If the resource is currently unavailable but might be retrievable later.
Like for example if the resource cannot be fetched due to the user temporarily loosing the internet connection.
The caller MAY try to recover by fetching this resource again later.

If `fetch()` was called with `options.range` set, but range requests is not supported for that resource.
The caller MAY recover by fetching the whole resource instead.

If `fetch()` fails for any other reason.