PushChannelListener Interface Reference

Listener interface for Push Channel state transitions and received Push Channel notifications (deprecated). More...

Description

Deprecated:

This class is deprecated and will be removed in a future release. Instead of setting a PushChannel listener, register for notifications as described in the PushChannel class reference.

State changes that occur when using PushChannel are handled by creating a class that implements this protocol. The callback for handling received Push Channel notifications is also part of this protocol.

Code Snippets

The following code snippets illustrate some common tasks.

Receive Push Channel Token

public void onChannelOpen(String token) {
    System.out.println("onChannelOpen token: " + token);
    myApp.pushIsOpen = true;
    myApp.pushToken = token;
    myApp.sendPushToken();
}

The above snippet shows a simple onChannelOpen handler. The following takes place when the Push Channel is opened:

• The token is logged to the system monitor
• The application's channel state is flagged as connected
• The token is stored in the application
• The application's sendPushToken method is called

The sendPushToken method, which would be written by the application developer, would send the token to the application server. This could use a socket, an HTTP request, or another means of communication. From the Push Channel point of view, this is an out-of-band communication.

The server will use the token to address Push Channel notification messages back to the application. These would be received by the application's onChannelMessage handler.

Receive Push Channel notification

public void onChannelMessage(String data) {
    System.out.println("onChannelMessage: " + data);
    myApp.processPush(data);
}

The above snippet shows a simple onChannelMessage handler.

The handler logs the received data to the system monitor, then calls the application processPush method. The "payload" of the notification is passed as a parameter to the processPush method.

The processPush method, which would be written by the application developer, could initiate any of the following actions:

• Alert the user that new data is available.
• Connect to the application server to retrieve the data. (Connection could use a socket, an HTTP request, or another means of communication. From the Push Channel point of view, this is an out-of-band communication.)

Handle Channel Closure

public void onChannelClose(String data) {
    System.out.println("onChannelClose: " + data);
    myApp.pushIsOpen = false;
    myApp.discardPushToken(data);
}

The above snippet shows a simple onChannelClose handler. The following takes place when the Push Channel is closed:

• The token is logged to the system monitor
• The application's channel state is flagged as not connected
• The application discardPushToken method is called. The token of the closed channel is passed as a parameter.

The discardPushToken method would delete the application's copy of the token, possibly after checking that it matches the whichWas parameter. The method could also initiate connection of a new Push Channel, which would have a new token. See connect .

Handle Channel Error

public void onChannelError(int error) {
    System.out.println("onChannelError: " + error);
    myApp.pushIsOpen = false;
    myApp.pushErr = error;
    myApp.discardPushToken();
}

The above snippet shows a simple onChannelError handler.

The handler logs the error code to the system monitor, flags the channel's state as not connected, records the error code in the application, then calls the application discardPushToken method.

The discardPushToken method could do any of the following:

• Delete the application's copy of the token.
• Set the error state in an ongoing status display.
• Depending on the error code, initiate connection of a new Push Channel, which would have a new token. See connect .

Handle Ping Failure

pubic void onChannelPingFail(int error) {
    System.out.println("onChannelPingFail: " + error);
    if ( error == 605 ) {
        myApp.resendPushToken();
    }
}

The above snippet shows a simple onChannelPingFail handler.

The handler logs the error code to the system monitor, then calls the application resendPushToken method if the token was lost.

The resendPushToken method, which would be written by the application developer, would send the application's stored token to the application server. This could use a socket, an HTTP request, or another means of communication. From the Push Channel point of view, this is an out-of-band communication.

The resendPushToken method should expect that the server is not immediately available, perhaps employing a retry policy.

Public Member Functions
void	onChannelOpen (String token)
	Channel opened callback. More...
void	onChannelMessage (String data)
	Push Channel notification callback. More...
void	onChannelClose (String token)
	Channel closed callback. More...
void	onChannelError (int error)
	Generic channel error callback. More...
void	onChannelPingFail (int error)
	Specific Ping Failure callback. More...

Member Function Documentation

onChannelOpen()

void onChannelOpen

(

String

token

)

This callback will be invoked when the associated Push Channel is opened in the BlackBerry Dynamics proxy infrastructure. See connect . At this point, a Push Channel token will have been issued by the BlackBerry Dynamics proxy infrastructure Network Operation Center (NOC).

The method that is invoked must initiate sending of the token to the application server, out of band. The application server will then be able to use the token to address Push Channel notifications back to the application on the device, via the NOC.

See also

Push Channel Back-End API

Invocation of this callback also notifies the application on the device that any of the following callbacks could now be invoked: onChannelMessage, onChannelPingFail, onChannelClose.

Parameters

token

String containing the Push Channel token issued by the NOC.

onChannelMessage()

void onChannelMessage

(

String

data

)

This callback will be invoked when a Push Channel notification is received on the associated Push Channel. The message will have been sent by the application server, using the Push Channel notify service, which is hosted by the BlackBerry Dynamics Network Operation Center (NOC).

The service supports a "payload" of data to be included in the notification. The data could be in any format chosen by the application developer. The payload could also be empty.

Note that Push Channel notifications can be received at any time when the channel is open. This includes the interval between the request for disconnection (disconnect called) and channel disconnection being finalized (onChannelClose received).

The method that is invoked could initiate the following actions:

• Alert the user that new data is available.
• Connect to the application server to retrieve the data.

Parameters

data	String containing the data payload included by the application server, encoded in UTF-8.

Note

Because of this callback, the application code does not need to maintain a constant connection with the server. This is an important benefit of using the BlackBerry Dynamics Push Channel framework.

See also

Push Channel Back-End API

onChannelClose()

void onChannelClose

(

String

token

)

This callback will be invoked when the associated Push Channel is closed. This means closed by the remote end, or by the application having called disconnect .

Invocation of this callback notifies the application on the device that:

• The associated Push Channel token cannot be used any more
• No more Push Channel notifications will be received on this channel

If the onChannelClose was not expected, the method that is invoked could alert the user that Push Channel notifications will not be received, or cause this to be displayed as an ongoing state. The method could also initiate release of the Push Channel object. Alternatively, reconnection could be initiated, see connect .

Parameters

token

Token for the Push Channel that was closed.

Note that this callback is only invoked for permanent Push Channel closure. This callback is not invoked for transient losses of channel communication. For example, this callback is not invoked when the mobile device loses packet data coverage or otherwise cannot connect to the BlackBerry Dynamics proxy infrastructure. The status of the connection to the infrastructure can be monitored by using the GDNetworkInfo programming interface.

onChannelError()

void onChannelError

(

int

error

)

This callback is invoked when a permanent error condition is encountered on the associated Push Channel.

Invocation of this callback notifies the application that the Push Channel token cannot be used any more, or that the channel could not be connected in the first place. Furthermore, no (more) Push Channel notifications will be received on this channel.

The method that is invoked could alert the user that Push Channel notifications will not be received, or cause this to be displayed as an ongoing state. The method that is invoked should initiate reconnection, see connect , after checking that the Push Channel service is available, see GDNetworkInfo.isPushChannelAvailable.

Parameters

error

Reason code for the condition encountered, as follows.

error	Channel Error reason
0	Push is not currently connected.
200-499	Internal error.
500-599	Internal server error.

onChannelPingFail()

void onChannelPingFail

(

int

error

)

This callback is invoked when Ping Failure is encountered on the associated Push Channel.

The method that is invoked should initiate resending of the Push Channel token to the application server, if the token has been lost. This is similar to the processing when the channel is initially opened. If the application server is able to accept the token, then Push Channel notification can resume.

See also

Push Channel Back-End API

Note that Ping Fail notifications can be received at any time when the channel is open. This includes the interval between the request for disconnection (disconnect called) and channel disconnection being finalized (onChannelClose received).

Parameters

error

Reason code for the condition encountered, as follows.

error	Ping Failure reason
600	Application server address could not be resolved via DNS
601	Could not connect to application server address
602	Application server TLS/SSL certificate invalid
603	Timed out waiting for application server HTTP response
604	Application server returned an invalid response
605	Application server indicated that token is unknown

Note that only error 605 means that the token has been lost and must be resent.