Java/Kotlin SDK 13.0.0 migration guide

The v13.0.0 release of Java and Kotlin SDKs upgrades kotlinx-datetime to 0.7.1 and makes com.pubnub.api.utils.Instant a standalone SDK value type.

Earlier migration guides

If you are upgrading from an earlier version, read the Java/Kotlin SDK v10.0.0 migration guide and the Java/Kotlin SDK v9.0.0 migration guide first.

The most notable change in this release is that the Instant type is now a standalone SDK value type.

This guide summarizes differences and the steps to migrate to Java/Kotlin SDK v13.0.0.

What has changed

See the major differences between versions:

Feature	Java/Kotlin SDK 10.1.0+	Java/Kotlin SDK 13.0.0
Instant type	Type alias or implicit interop with kotlinx.datetime.Instant / kotlin.time.Instant (introduced in v10.1.0)	Standalone data class (com.pubnub.api.utils.Instant) with built-in conversion methods
kotlinx.datetime extensions	Worked directly on PubNub Instant	Use Instant.toLocalDateTime(TimeZone) instead
LocalDateTime to timetoken conversion	localDateTime.toInstant(zone) then TimetokenUtil.instantToTimetoken(instant)	TimetokenUtil.localDateTimeToInstant(localDateTime, zone) or TimetokenUtil.localDateTimeToTimetoken(localDateTime, zone)

Breaking changes

Instant type

com.pubnub.api.utils.Instant is now a standalone data class defined by the SDK. It isn't interchangeable with kotlin.time.Instant or kotlinx.datetime.Instant. This decouples the SDK's public API from experimental Kotlin time APIs and gives you a stable type across Kotlin versions.

The PubNub Instant class provides:

Property / Method	Description
epochSeconds: Long	Seconds since Unix epoch.
nanosecondsOfSecond: Int	Nanosecond adjustment (0..999,999,999).
toEpochMilliseconds(): Long	Returns the epoch time in milliseconds.
toLocalDateTime(timeZone: TimeZone): LocalDateTime	Converts to a kotlinx.datetime.LocalDateTime in the given time zone.
plus(duration: Duration): Instant	Returns a new Instant shifted forward by the duration.
minus(duration: Duration): Instant	Returns a new Instant shifted backward by the duration.
minus(other: Instant): Duration	Returns the duration between two instants.
Instant.fromEpochMilliseconds(epochMilliseconds: Long): Instant	Factory. Creates an Instant from epoch milliseconds.
Instant.fromEpochSeconds(epochSeconds: Long, nanosecondAdjustment: Int): Instant	Factory. Creates an Instant from epoch seconds and a nanosecond adjustment.

Using kotlinx.datetime extensions on PubNub Instant

In v12.x.x, PubNub Instant was interchangeable with kotlinx.datetime.Instant, so you could call kotlinx.datetime extension functions directly. In v13.0.0, use the built-in toLocalDateTime() method instead.

Before (v10.1.0+)

1import com.pubnub.api.utils.TimetokenUtil
2import kotlinx.datetime.TimeZone
3import kotlinx.datetime.toLocalDateTime
4

5val timetoken: Long = 17276954606232118
6val instant = TimetokenUtil.timetokenToInstant(timetoken)
7

8// kotlinx.datetime extension worked directly on PubNub Instant
9val localDateTime = instant.toLocalDateTime(TimeZone.UTC)

After (v13.0.0)

1import com.pubnub.api.utils.TimetokenUtil
2import kotlinx.datetime.TimeZone
3

4val timetoken: Long = 17276954606232118
5val instant = TimetokenUtil.timetokenToInstant(timetoken)
6

7// Use the built-in method on PubNub Instant
8val localDateTime = instant.toLocalDateTime(TimeZone.UTC)

Import change

In v13.0.0, you no longer need the import kotlinx.datetime.toLocalDateTime extension import. The toLocalDateTime() method is defined directly on com.pubnub.api.utils.Instant.

Converting LocalDateTime to a timetoken

In v12.x.x, you could convert a LocalDateTime to a timetoken by first creating a kotlinx.datetime.Instant with toInstant() and then passing it to TimetokenUtil.instantToTimetoken(). In v13.0.0, the TimetokenUtil class provides dedicated helpers that handle the conversion without exposing experimental time APIs.

Before (v10.1.0+)

1import com.pubnub.api.utils.TimetokenUtil
2import kotlinx.datetime.LocalDateTime
3import kotlinx.datetime.TimeZone
4import kotlinx.datetime.toInstant
5

6val localDateTime = LocalDateTime(
7    year = 2024, month = 9, day = 30,
8    hour = 12, minute = 12, second = 44,
9    nanosecond = 123456789
10)
11

12val zone = TimeZone.currentSystemDefault()
13

14// Convert through kotlinx.datetime.Instant
15val instant = localDateTime.toInstant(zone)
16val timetoken = TimetokenUtil.instantToTimetoken(instant)

show all 16 lines

After (v13.0.0)

1import com.pubnub.api.utils.TimetokenUtil
2import kotlinx.datetime.LocalDateTime
3import kotlinx.datetime.TimeZone
4

5val localDateTime = LocalDateTime(
6    year = 2024, month = 9, day = 30,
7    hour = 12, minute = 12, second = 44,
8    nanosecond = 123456789
9)
10

11val zone = TimeZone.currentSystemDefault()
12

13// Option 1: Get a PubNub Instant, then convert to timetoken
14val instant = TimetokenUtil.localDateTimeToInstant(localDateTime, zone)
15val timetoken = TimetokenUtil.instantToTimetoken(instant)
16

17// Option 2: Convert directly to a timetoken
18val timetokenDirect = TimetokenUtil.localDateTimeToTimetoken(localDateTime, zone)

show all 18 lines

Migration steps

To migrate from Java/Kotlin SDK v10.1.0+ to v13.0.0:

1. Update your dependency to v13.0.0.

2. Remove unused kotlinx.datetime extension imports:

   Action	Description
   Remove import kotlinx.datetime.toLocalDateTime	The toLocalDateTime() method is now defined on com.pubnub.api.utils.Instant. The extension import is no longer needed.

3. Replace LocalDateTime to Instant conversions:

   Action	Description
   Replace localDateTime.toInstant(zone) followed by TimetokenUtil.instantToTimetoken(instant)	Use TimetokenUtil.localDateTimeToInstant(localDateTime, zone) to get a PubNub Instant, or TimetokenUtil.localDateTimeToTimetoken(localDateTime, zone) to get a timetoken directly.

4. Verify that all references to Instant in your code resolve to com.pubnub.api.utils.Instant rather than kotlin.time.Instant or kotlinx.datetime.Instant.

5. Test your application. Pay special attention to any code that converts between timetokens, instants, and local date-times.

Additional resources

For API details, see the Kotlin SDK documentation and the TimetokenUtil reference. For questions or issues, contact PubNub support.