3.0.0-alpha.1

[mickael-menu]

Take a look at the migration guide

Changelog

Changed

• The R2Shared, R2Streamer and R2Navigator packages are now called ReadiumShared, ReadiumStreamer and ReadiumNavigator.
• Many APIs now expect one of the new URL types (RelativeURL, AbsoluteURL, HTTPURL and FileURL). This is helpful because:
  • It validates at compile time that we provide a URL that is supported.
  • The API's capabilities are better documented, e.g. a download API could look like this : download(url: HTTPURL) -> FileURL.

Shared

• Link and Locator's href are normalized as valid URLs to improve interoperability with the Readium Web toolkits.
  • You MUST migrate your database if you were persisting HREFs and Locators. Take a look at the migration guide for guidance.
• Links are not resolved to the self URL of a manifest anymore. However, you can still normalize the HREFs yourselves by calling Manifest.normalizeHREFsToSelf().
• Publication.localizedTitle is now optional, as we cannot guarantee a publication will always have a title.

What's Changed

• Refactor HREF normalization and models by @mickael-menu in Refactor HREF normalization and models #358
• Validate Link's href when creating a URL by @mickael-menu in Validate Link's href when creating a URL #379
• Fix audiobook regression by @mickael-menu in Fix audiobook regression #380
• Prevent crash when reporting the currently spoken word by @mickael-menu in Prevent crash when reporting the currently spoken word #381
• Validate Link HREFs only when they are not templated by @mickael-menu in Validate Link HREFs only when they are not templated #387
• Fix audiobook regression by @mickael-menu in Fix audiobook regression #393
• Drop R2 prefix by @mickael-menu in Drop R2 prefix #412
• Don't require a self link to enable HTTP requests in a RWPM by @mickael-menu in Don't require a self link to enable HTTP requests in a RWPM #415
• Documentation by @mickael-menu in Documentation #384
• 3.0.0-alpha.1 by @mickael-menu in 3.0.0-alpha.1 #420

Full Changelog: 2.7.1...3.0.0-alpha.1

---

This discussion was created from the release 3.0.0-alpha.1.

[LaurentiuUngur]

Hi. With the new mobile SDKs 3.x changes related to HREFs and Locators, do you have any migration guide in case those are being stored on the server side ? Having them stored only on local DB seems pretty straight forward by using AnyURL(legacyHREF:) and Locator(legacyJSONString:) . Another approach that I’m thinking of is to leave server DB as it is right now, but to use in mobile code Locator(legacyJSONString:) which will work, but thinking long term when a new breaking change may take place again (maybe in 4.x), things can get pretty complicated. I would be very grateful having your opinion on how the migration should look like in case of storing them on server side, not locally. Thanks a lot !

[mickael-menu]

As a reminder:

To improve the interoperability with other Readium toolkits (in particular the Readium Web Toolkits, which only work in a streaming context) Readium v3 now generates and expects valid URLs for Locator and Link's href.

• https://domain.com/isbn/dir/my%20chapter.html is left unchanged, as it was already a valid URL.
• /dir/my chapter.html becomes the relative URL path dir/my%20chapter.html
  • We dropped the / prefix to avoid issues when resolving to a base URL.
  • Special characters are percent-encoded.

So to migrate a legacy HREF server-side, you can use this algorithm:

1. Attempt to parse the HREF as a valid percent-encoded URL, and check the presence of an URL scheme (http, https, etc.).
   • If it is a valid absolute URL, leave the HREF unchanged.
2. Fall back on converting a relative legacy HREF into a relative URL:
   1. Remove the / prefix from the HREF, if there's any.
   2. Percent-encode the HREF.
   • For example /dir/my chapter.html becomes dir/my%20chapter.html.

Here's the Swift implementation as a reference:

/// Creates an `AnyURL` from a legacy HREF.
///
/// For example, if it is a relative path such as `/dir/my chapter.html`,
/// it will be / converted to the valid relative URL `dir/my%20chapter.html`.
///
/// Only use this API when you are upgrading to Readium 3.x and migrating
/// the HREFs stored in / your database. See the 3.0 migration guide for
/// more information.
public init?(legacyHREF href: String) {
    if let url = URL(string: href), url.scheme != nil {
        self.init(url: url)
    } else if let url = RelativeURL(path: href.removingPrefix("/")) {
        self = .relative(url)
    } else {
        return nil
    }
}

and the Kotlin one:

/**
 * Creates an [Url] from a legacy HREF.
 *
 * For example, if it is a relative path such as `/dir/my chapter.html`, it will be
 * converted to the valid relative URL `dir/my%20chapter.html`.
 *
 * Only use this API when you are upgrading to Readium 3.x and migrating the HREFs stored in
 * your database. See the 3.0 migration guide for more information.
 */
@DelicateReadiumApi
public fun Url.Companion.fromLegacyHref(href: String): Url? =
    AbsoluteUrl(href) ?: RelativeUrl(href.removePrefix("/").percentEncodedPath())