• BlackBerry Dynamics
  • Runtime library for Android applications
  • 10.0.0.93
PushConnection Class Reference

Manage Push Channel connection (deprecated). More...

Description

Deprecated:
This class is deprecated and will be removed in a future release.
  • Instead of isConnected, use com.good.gd.net.GDNetworkInfo.isPushChannelAvailable.
  • Instead of setting a PushConnection listener, register for notifications as described in the GDNetworkInfo class reference.
  • The connect and disconnect methods are no longer required. They were added to enable management of power consumption by the application code. This is no longer required because of advances in the built-in power management of mobile operating systems and devices. .

This API is part of the BlackBerry Dynamics Push Channel feature. For an overall description of how to use the feature, see under PushChannel .

The Push Connection is the container and conduit for the device's Push Channels. An application may open multiple Push Channels; all will be managed within a single Push Connection.

The Push Connection is automatically established during BlackBerry Dynamics authorization processing, and then maintained by the BlackBerry Dynamics Runtime under application control. The application can instruct the runtime to switch the Push Connection off and on.

When instructed to switch off, the BlackBerry Dynamics Runtime will terminate the Push Connection, and suspend its maintenance. When instructed to switch back on, the BlackBerry Dynamics Runtime will re-establish the Push Connection, and resume maintenance.

Switching off the Push Connection might be an option that the application offers to the end user, for example, allowing them to reduce power consumption on the device.

Push Connection methods cannot be called until BlackBerry Dynamics authorization processing is complete.

See also
PushChannel
GDAndroid, for BlackBerry Dynamics authorization

Push Channel Network

The Push Connection is a link between the mobile application and the BlackBerry Dynamics proxy infrastructure Network Operation Center (NOC). The Push Channel is a link between the mobile application and its application server (App Server). There can be more than one Push Channel; the mobile application can receive push communications from more than one App Server. Push Channels are mediated by the NOC, and sometimes other proxy infrastructure elements.

This is shown in the following diagram.

API Overview

The BlackBerry Dynamics Push Connection API consists of a small number of methods that must be used in a particular order. Whilst some other APIs are general-purpose toolkits, the Push Connection API has only a single purpose: to enable the Push Channel API.

The normal sequence of operations is as follows.

  1. Application started.
  2. BlackBerry Dynamics initialization and authorization, see under GDAndroid.
  3. When the application needs a Push Channel...
  4. Call getInstance to access the Push Connection object,
  5. Call isConnected to check the connection state,
  6. If the state is not connected:
    1. Set a PushConnectionListener to handle connection state changes
    2. Call connect to ensure that connection is being attempted,
    3. When the onStatus callback in the handler is invoked, go back and check the connection state again.
  7. If the state is connected, proceed to setting up a Push Channel.

For details of Push Channel set-up, see under PushChannel .

Code Snippets

The following code snippets illustrate some common tasks.

Terminate Push Connection

PushConnection.getInstance().disconnect;

After the disconnect, the connection can be re-opened later.

Re-open Push Connection

if ( ! PushConnection.getInstance().isConnected() ) {
PushConnection.getInstance().setListener(this);
PushConnection.getInstance().connect();
}

The above snippet shows a check for whether the Push Channel service is already available. If it is not, then a connection is initiated. The connection attempt is asynchronous. The onStatus callback would be invoked, with isConnected returning true, when the attempt succeeds (not shown). See PushConnectionListener .

Public Member Functions

boolean isConnected ()
 Get state of the connection to the Push Channel service (deprecated). More...
 
void setListener (PushConnectionListener listener)
 Event-handling for the connection to the overall Push Channel service (deprecated). More...
 
void connect ()
 Initiate connection to the overall Push Channel service (deprecated). More...
 
void disconnect ()
 Terminate the connection to the Push Channel service (deprecated). More...
 

Static Public Member Functions

static synchronized PushConnection getInstance ()
 Get a reference to the Push Connection object (deprecated). More...
 

Member Function Documentation

◆ isConnected()

boolean isConnected ( )
Deprecated:
This method is in a deprecated class and will be removed in a future release.

This method returns the current status of the Push Channel connection.

Returns
true if the Push Channel connection is open and operating, and the Push Channel service is available.
false otherwise.
Exceptions
com.good.gd.error.GDNotAuthorizedErrorif BlackBerry Dynamics authorization processing has not yet completed.

◆ setListener()

void setListener ( PushConnectionListener  listener)
Deprecated:
This method is in a deprecated class and will be removed in a future release.

Call this method to set the listener for the Push Connection object.

The Push Connection object works asynchronously. When its state changes, an event is generated by the BlackBerry Dynamics runtime, and passed to a callback in the application. The specified listener must contain the code for the callback, i.e. the listener must be an instance of a class that conforms to the PushConnectionListener interface.

Parameters
listenerInstance to set as the listener.
Exceptions
com.good.gd.error.GDNotAuthorizedErrorif BlackBerry Dynamics authorization processing has not yet completed.

◆ connect()

void connect ( )
Deprecated:
This method is deprecated and will be removed in a future release.
This method enabled management of power consumption by the application code. This is no longer required because of advances in the built-in power management of mobile operating systems and devices.

Call this method to establish, or re-establish, the Push Channel connection with the BlackBerry Dynamics proxy infrastructure Network Operation Center (NOC).

Establishing the connection involves a number of messages being exchanged with the NOC. The onStatus callback in the listener will be invoked as this progresses.

If mobile data coverage is lost after this method has been called, the Push Channel connection will stop operating. The BlackBerry Dynamics Runtime will automatically attempt to re-establish the Push Channel connection when coverage is regained. The BlackBerry Dynamics Runtime uses the native Connectivity Manager to be notified of coverage status.

Exceptions
com.good.gd.error.GDNotAuthorizedErrorif BlackBerry Dynamics authorization processing has not yet completed.

◆ disconnect()

void disconnect ( )
Deprecated:
This method is deprecated and will be removed in a future release.
This method enabled management of power consumption by the application code. This is no longer required because of advances in the built-in power management of mobile operating systems and devices.

Call this method to terminate the Push Channel connection with the BlackBerry Dynamics proxy infrastructure Network Operation Center (NOC).

If the connection was open and operating, termination will result in the onStatus callback in the listener being invoked.

Exceptions
com.good.gd.error.GDNotAuthorizedErrorif BlackBerry Dynamics authorization processing has not yet completed.

◆ getInstance()

static synchronized PushConnection getInstance ( )
static
Deprecated:
This method is in a deprecated class and will be removed in a future release.

This method returns a reference to the Push Connection object.

The Push Connection object is a "singleton class".

Returns
Reference that can be used to call, for example, the isConnected method.