PubNub Java SDK

The status(PubNub pubnub, PNStatus status) callback is used to monitor the connection state.

For PNSubscribeOperation and PNUnsubscribeOperation, check the status.getCategory() to determine the specific state:

• PNConnectedCategory: Successfully connected.
• PNReconnectedCategory: Temporary failure followed by reconnection.
• PNDisconnectedCategory: Successfully unsubscribed.
• PNUnexpectedDisconnectCategory: Error (e.g., internet connection issue).
• PNAccessDeniedCategory: Error (e.g., PAM permission issue).

For PNHeartbeatOperation, use status.isError() to check if the heartbeat failed.

The Java SDK includes integration tests that run against a live PubNub application. To run them, you must first create a dedicated application in the PubNub Admin Portal.

Setup

1. Create a dedicated PubNub application.
2. Configure the subKey (Subscribe Key) in a test.properties file located in the project's root directory. You can use test.properties.example as a template.
3. Alternatively, you can override properties by setting environment variables.

Execution

Use the Gradle integrationTest task to launch the tests. Note that these tests are not part of the standard CI pipeline and must be triggered manually.

# Option 1: Using test.properties
./gradlew integrationTest

# Option 2: Overriding via environment variables
export subKey=<SUBSCRIBE_KEY>
./gradlew build integrationTest

To manually add the PubNub libraries to your project in an IDE (such as IntelliJ IDEA), follow these steps:

1. Navigate to File -> Project Structure -> Modules.
2. Select the Main/Test module.
3. Go to the Dependencies tab.
4. Click the "+" (add) button.
5. Select Library -> Java.
6. Select and add all required libraries from the list.
7. Click Apply to save changes.

Use the following Gradle command to clean the previous build artifacts and compile the source code:

gradle clean compile

To create a shadowJar (a Fat Jar containing all dependencies), you can use either of the following sequences of commands:

Option 1 (Single command):

gradle clean build shadowJar

Option 2 (Step-by-step):

gradle clean
gradle clean test
gradle build shadowJar

Integrate the PubNub Java SDK into your project using Maven or Gradle. Note that this repository is no longer being updated; development has moved to the PubNub Kotlin SDK.

### For Maven
```xml
<dependency>
  <groupId>com.pubnub</groupId>
  <artifactId>pubnub-gson</artifactId>
  <version>6.4.5</version>
</dependency>

For Gradle

implementation 'com.pubnub:pubnub-gson:6.4.5'

To initialize a PubNub instance, create a PNConfiguration object. You must provide a UserId and set your SubscribeKey and PublishKey, which can be obtained from the PubNub Admin Portal.

PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUserId"));
pnConfiguration.setSubscribeKey("mySubscribeKey");
pnConfiguration.setPublishKey("myPublishKey");

PubNub pubnub = new PubNub(pnConfiguration);

When performing an asynchronous file upload, the PNCallback<Void> returns a PNStatus object. You should inspect this object to determine if the upload succeeded or failed.

Status Mapping for Failures:

• Access Denied: PNStatusCategory.PNAccessDeniedCategory (HTTP 401 or 403).
• Bad Request: PNStatusCategory.PNBadRequestCategory (HTTP 400 or general failure).
• Timeout: PNStatusCategory.PNTimeoutCategory (Socket timeout).
• Connection Issues: PNStatusCategory.PNUnexpectedDisconnectCategory (Unknown host, Socket exception, or SSL exception).
• Cancelled: PNStatusCategory.PNCancelledCategory (If the call was explicitly cancelled).

If status.error() is true, inspect status.errorData() for the PNErrorData containing the error message and cause.

Use the publish() method to send data to a specific channel. The operation is asynchronous and provides a callback to handle success or failure. If a failure occurs, check the publishStatus category to diagnose the issue.

pubnub.publish().channel(channelName)
  .message(messageJsonObject)
  .async((result, publishStatus) -> {
    if (!publishStatus.isError()) {
        // Message successfully published to specified channel.
    } else {
        // Handle message publish error
    }
});

When attempting to generate an upload URL, the following errors may occur during validation or response processing:

• PNERROBJ_SUBSCRIBE_KEY_MISSING: The PubNub configuration is missing a subscribeKey.
• PNERROBJ_CHANNEL_MISSING: The channel parameter provided is null or empty.
• PNERROBJ_INTERNAL_ERROR:
  • Occurs if the server response is empty or null.
  • Occurs if the response does not contain the required key form parameter in the formFields list.