Utility Methods API for PubNub Java SDK
Breaking changes in v9.0.0
PubNub Java SDK version 9.0.0 unifies the codebases for Java and Kotlin SDKs, introduces a new way of instantiating the PubNub client, and changes asynchronous API callbacks and emitted status events. These changes can impact applications built with previous versions (< 9.0.0) of the Java SDK.
For more details about what has changed, refer to Java/Kotlin SDK migration guide.
The methods on this page are utility methods that don't fit into other categories.
Create Push Payload
This method creates the push payload for use in the appropriate endpoint calls.
Method(s)
PushPayloadHelper()
.setApnsPayload(PushPayloadHelper.APNSPayload)
.setFcmPayload(PushPayloadHelper.FCMPayload)
.setCommonPayload(Map<String, Object>)
.build()
| Parameter | Type | Required | Description |
|---|---|---|---|
setApnsPayload() | APNSPayload | Optional | Set APNs and APNs2 Payload. Associated devices will receive only the data supplied here within the pn_apns key. |
setFcmPayload() | FCMPayload | Optional | Set FCM Payload. Associated devices will receive only the data supplied here within the pn_gcm key. |
setCommonPayload() | Map<String, Object> | Optional | Set common Payload. Native PubNub subscribers will receive the data provided here, together with the pn_apns, and pn_gcm objects. |
build() | Map<String, Object> | Yes | Builds the payload from the values set using the parameters. |
Basic Usage
Create Push Payload
// Create an instance of PushPayloadHelper
PushPayloadHelper pushPayloadHelper = new PushPayloadHelper();
// Setup FCM parameters (FCMPayload)
PushPayloadHelper.FCMPayload fcmPayload = new PushPayloadHelper.FCMPayload();
// The FCMPayload includes a custom Notification object, which FCM itself uses
// to display the message automatically to end-user devices on behalf of the
// client app.
// Notification messages have a predefined set of user-visible keys
PushPayloadHelper.FCMPayload.Notification fcmNotification =
new PushPayloadHelper.FCMPayload.Notification()
.setTitle("Notification title")
.setBody("Notification body text")
.setImage("http://example.com/image.png");
fcmPayload.setNotification(fcmNotification);
Response
The PushPayloadHelper#build() operation returns a Map<String, Object> which can be passed directly as the message() parameter to the pubnub.publish() method.
Destroy
Destroy frees up the threads and allows for clean exit.
Method(s)
destroy()
Basic Usage
pubnub.destroy();
Returns
None
Encrypt
This function allows to encrypt the data.
Deprecated
The cipherKey parameter in this method is deprecated. We recommend that you configure a seprate instance of the crypto module and use it for partial encryption.
If you pass cipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.
Method(s)
To encrypt the data you can use the following method(s) in Java SDK.
pubnub.encrypt(data, customCipherKey)
| Parameter | Type | Required | Description |
|---|---|---|---|
data | String | Yes | The data to encrypt. |
customCipherKey | String | Optional | Cipher key to use for encryption. If provided, the legacy encryption with 128-bit cipher key entropy is used. If not provided, the cryptoModule from PubNub config will be used. For more information, refer to Crypto module configuration. |
Basic Usage
Encrypt part of message
CryptoModule aesCbcCryptoModule = CryptoModule.createAesCbcCryptoModule("myCipherKey01", true);
String stringToBeEncrypted = "string to be encrypted";
byte[] encryptedData = aesCbcCryptoModule.encrypt(stringToBeEncrypted.getBytes(StandardCharsets.UTF_8));
Encrypt File Input Stream
Encrypts input stream with a cipher key.
Deprecated
The cipherKey parameter in this method is deprecated. We recommend that you configure a seprate instance of the crypto module and use it for partial encryption.
If you pass cipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.
Method(s)
pubnub.encryptInputStream(inputStream, cipherKey)
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
inputStream | InputStream | Yes | Stream with content to encrypt. | |
cipherKey | String | Optional | PNConfiguration.getCipherKey() | If provided, the legacy encryption with 128-bit cipher key entropy is used. If not provided, the cryptoModule from PubNub config will be used. For more information, refer to Crypto module configuration |
Basic Usage
CryptoModule aesCbcCryptoModule = CryptoModule.createAesCbcCryptoModule("myCipherKey01", true);
InputStream inputStream = new ByteArrayInputStream(stringToBeEncrypted.getBytes(StandardCharsets.UTF_8));
InputStream encryptedStream = aesCbcCryptoModule.encryptStream(inputStream);
Returns
InputStream with encrypted data.
Decrypt
This function allows to decrypt the data.
Method(s)
To decrypt the data you can use the following method(s) in Java SDK.
Deprecated
The cipherKey parameter in this method is deprecated. We recommend that you configure a seprate instance of the crypto module and use it for partial encryption.
If you pass cipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.
pubnub.decrypt(data, customCipherKey)
| Parameter | Type | Required | Description |
|---|---|---|---|
data | String | Yes | The data to decrypt. |
customCipherKey | String | Optional | Cipher key to use for decryption. |
Basic Usage
CryptoModule aesCbcCryptoModule = CryptoModule.createAesCbcCryptoModule("myCipherKey01", true);
String stringToBeEncrypted = "string to be encrypted";
byte[] encryptedData = aesCbcCryptoModule.encrypt(stringToBeEncrypted.getBytes(StandardCharsets.UTF_8));
byte[] decryptedData = aesCbcCryptoModule.decrypt(encryptedData);
Decrypt File Input Stream
Decrypts input stream with a cipher key.
Deprecated
The cipherKey parameter in this method is deprecated. We recommend that you configure a seprate instance of the crypto module and use it for partial encryption.
If you pass cipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.
Method(s)
pubnub.decryptInputStream(inputStream, cipherKey)
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
inputStream | InputStream | Yes | Stream with content encrypted data. | |
cipherKey | String | Optional | PNConfiguration.getCipherKey() | Cipher key to use for encryption. If provided, the legacy encryption with 128-bit cipher key entropy is used. If not provided, the cryptoModule from PubNub config will be used. For more information, refer to Crypto module configuration. |
Basic Usage
CryptoModule aesCbcCryptoModule = CryptoModule.createAesCbcCryptoModule("myCipherKey01", true);
InputStream inputStream = new ByteArrayInputStream(stringToBeEncrypted.getBytes(StandardCharsets.UTF_8));
InputStream encryptedStream = aesCbcCryptoModule.encryptStream(inputStream);
InputStream decryptedStream = aesCbcCryptoModule.decryptStream(encryptedStream);
Returns
InputStream with decrypted data.
Get Subscribed Channel Groups
Returns all the subscribed channel groups in a List of type String.
Method(s)
To Get Subscribe Channel Groups you can use the following method(s) in the Java SDK:
public final List<String> getSubscribedChannelGroups()
Basic Usage
Get Subscribed Channel Groups
List<String> groups = pubnub.getSubscribedChannelGroups();
Response
List<String>
["channelGroup1", "channelGroup2"]
Get Subscribed Channels
Returns all the subscribed channels in a List of type String.
Method(s)
To Get Subscribed Channels you can use the following method(s) in the Java SDK:
public final List<String> getSubscribedChannels()
Basic Usage
Get Subscribed Channels
List<String> channels = pubnub.getSubscribedChannels();
Response
List<String>
["channel1", "channel2"]
Disconnect
Call the disconnect method to force the SDK to stop all requests to PubNub server when there are active subscribe channels.
Method(s)
To disconnect the data transmission you can use the following method(s) in Java SDK.
disconnect()
This method doesn't take any arguments.
Basic Usage
pubnub.disconnect();
Reconnect
Call the reconnect method to force the SDK to try and reach out PubNub.
Method(s)
To reconnect the data you can use the following method(s) in Java SDK.
reconnect()
This method doesn't take any arguments.
Basic Usage
pubnub.reconnect();
Timetoken to date
The timetokenToInstant() method of the TimetokenUtil class converts a PubNub timetoken (a unique identifier for each message sent and received in a PubNub channel that is a number of 100-nanosecond intervals since January 1, 1970) to an Instant object representing the corresponding date and time.
Use this method when you want to display the timetoken of each message or event in the message history in a human-readable format.
Method signature
Instant TimetokenUtil.timetokenToInstant(long timetoken)
Input
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
timetoken | long | Yes | n/a | Represents the PubNub timetoken to convert into a human-readable date format. |
Output
| Type | Description |
|---|---|
Instant | The human-readable date representation of the timetoken. |
Basic usage
Convert a timetoken value of 17276954606232118 to a human-readable date and time format.
long timetoken = 17276954606232118L;
Instant instant = TimetokenUtil.timetokenToInstant(timetoken);
LocalDateTime localDateTimeInUTC = LocalDateTime.ofInstant(instant, ZoneId.of("UTC"));
System.out.println("PubNub timetoken: " + timetoken);
System.out.println("Current date: " + localDateTimeInUTC.toLocalDate());
System.out.println("Current time: " + localDateTimeInUTC.toLocalTime());
The output of the method is as follows:
PubNub timetoken: 17276954606232118
Current date: 2024-09-30
Current time: 11:24:20.623211800
Date to timetoken
The instantToTimetoken() method of the TimetokenUtil class converts the Instant object representing the corresponding date and time into a PubNub timetoken (a unique identifier for each message sent and received in a PubNub channel that is a number of 100-nanosecond intervals since January 1, 1970).
Use this method to represent a specific date and time as a PubNub timetoken value, for example, to retrieve messages from a PubNub channel at a particular date and time.
Method signature
long TimetokenUtil.instantToTimetoken(Instant instant)
Input
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instant | Instant | Yes | n/a | Represents the date and time to convert into a PubNub timetoken. |
Output
| Type | Description |
|---|---|
long | Converted timetoken value. |
Basic usage
Convert a human-readable date and time, September 30, 2024 12:12:24 GMT, to a timetoken.
LocalDateTime localDateTime = LocalDateTime.of(2024, 9, 30, 12, 12, 44, 123456789); // Example date and time
Instant instant = localDateTime.atOffset(ZoneOffset.UTC).toInstant();
long timetoken = TimetokenUtil.instantToTimetoken(instant);
System.out.println("Current date: " + localDateTime.toLocalDate());
System.out.println("Current time: " + localDateTime.toLocalTime());
System.out.println("PubNub timetoken: " + timetoken);
Current date: 2024-09-30
Current time: 12:12:44.123456789
PubNub timetoken: 17276983641234567
Unix timestamp to timetoken
The unixToTimetoken() method of the TimetokenUtil class converts a Unix timestamp (a number of seconds since January 1, 1970) to a PubNub timetoken (a unique identifier for each message sent and received in a PubNub channel that is a number of 100-nanosecond intervals since January 1, 1970).
Use this method when you need a timetoken to retrieve historical messages with a specific timestamp range from Message Persistence.
Method signature
This method takes the following parameters:
long TimetokenUtil.unixToTimetoken(long unixTime)
Input
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
unixTime | long | Yes | n/a | Represents the Unix timestamp to convert into a PubNub timetoken. |
Output
| Type | Description |
|---|---|
long | Converted timetoken value. |
Basic usage
Convert a Unix timestamp value of 1727866935316 representing 2024-10-02 11:02:15.316 to PubNub timetoken:
long unixTime = 1727866935316L;
long timetoken = TimetokenUtil.unixToTimetoken(unixTime);
Instant instant = TimetokenUtil.timetokenToInstant(timetoken);
LocalDateTime localDateTimeInUTC = LocalDateTime.ofInstant(instant, ZoneId.of("UTC"));
System.out.println("PubNub timetoken: " + timetoken);
System.out.println("Current date: " + localDateTimeInUTC.toLocalDate());
System.out.println("Current time: " + localDateTimeInUTC.toLocalTime());
The output of the method is as follows:
PubNub timetoken: 17278669353160000
Current date: 2024-10-02
Current time: 11:02:15.316
Timetoken to Unix timestamp
The timetokenToUnix() method of the TimetokenUtil class converts a PubNub timetoken (a unique identifier for each message sent and received in a PubNub channel that is a number of 100-nanosecond intervals since January 1, 1970) to a Unix timestamp (a number of seconds since January 1, 1970).
Use this method to convert PubNub timetoken for use in another context or system that requires a Unix timestamp.
Method signature
long TimetokenUtil.timetokenToUnix(long timetoken)
Input
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
timetoken | long | Yes | n/a | Represents the PubNub timetoken to convert into a Unix timestamp. |
Output
| Type | Description |
|---|---|
long | Converted Unix timestamp value. |
Basic usage
Convert a PubNub timetoken 17276954606232118 representing 2024-09-30 11:24:20.623211800 to Unix time:
long timetoken = 17276954606232118L;
long unixTime = TimetokenUtil.timetokenToUnix(timetoken);
Instant instant = Instant.ofEpochMilli(unixTime);
LocalDateTime localDateTime = instant.atZone(ZoneOffset.UTC).toLocalDateTime();
System.out.println("Current date: " + localDateTime.toLocalDate());
System.out.println("Current time: " + localDateTime.toLocalTime());
System.out.println("PubNub timetoken: " + timetoken);
The output of the method is as follows:
Current date: 2024-09-30
Current time: 11:24:20.623
PubNub timetoken: 17276954606232118