javapns
Class Push

java.lang.Object
  javapns.Push

public class Push
extends Object

Main class for easily interacting with the Apple Push Notification System

This is the best starting point for pushing simple or custom notifications, or for contacting the Feedback Service to cleanup your list of devices.

The JavaPNS library also includes more advanced options such as multithreaded transmission, special payloads, and more. See the library's documentation at http://code.google.com/p/javapns/ for more information.

Author:

Sylvain Pedneault

See Also:

NotificationThreads

Method Summary

static PushedNotifications	alert(String message, Object keystore, String password, boolean production, Object devices) Push a simple alert to one or more devices.
static PushedNotifications	badge(int badge, Object keystore, String password, boolean production, Object devices) Push a simple badge number to one or more devices.
static PushedNotifications	combined(String message, int badge, String sound, Object keystore, String password, boolean production, Object devices) Push a notification combining an alert, a badge and a sound.
static PushedNotifications	contentAvailable(Object keystore, String password, boolean production, Object devices) Push a content-available notification for Newsstand.
static List<Device>	feedback(Object keystore, String password, boolean production) Retrieve a list of devices that should be removed from future notification lists.
static PushedNotifications	payload(Payload payload, Object keystore, String password, boolean production, int numberOfThreads, Object devices) Push a preformatted payload to a list of devices using multiple simulatenous threads (and connections).
static PushedNotifications	payload(Payload payload, Object keystore, String password, boolean production, Object devices) Push a preformatted payload to a list of devices.
static PushedNotifications	payloads(Object keystore, String password, boolean production, int numberOfThreads, Object payloadDevicePairs) Push a different preformatted payload for each device using multiple simulatenous threads (and connections).
static PushedNotifications	payloads(Object keystore, String password, boolean production, Object payloadDevicePairs) Push a different preformatted payload for each device.
static PushQueue	queue(Object keystore, String password, boolean production, int numberOfThreads) Build and start an asynchronous queue for sending notifications later without opening and closing connections.
static PushedNotifications	sound(String sound, Object keystore, String password, boolean production, Object devices) Push a simple sound name to one or more devices.
static PushedNotifications	test(Object keystore, String password, boolean production, Object devices) Push a special test notification with an alert message containing useful debugging information.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

alert

public static PushedNotifications alert(String message,
                                        Object keystore,
                                        String password,
                                        boolean production,
                                        Object devices)
                                 throws CommunicationException,
                                        KeystoreException

Push a simple alert to one or more devices.

Parameters:

message - the alert message to push.

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

devices - a list or an array of tokens or devices: String[], List<String>, Device[], List<Device>, String or Device

Returns:

a list of pushed notifications, each with details on transmission results and error (if any)

Throws:

KeystoreException - thrown if an error occurs when loading the keystore

CommunicationException - thrown if an unrecoverable error occurs while trying to communicate with Apple servers

badge

public static PushedNotifications badge(int badge,
                                        Object keystore,
                                        String password,
                                        boolean production,
                                        Object devices)
                                 throws CommunicationException,
                                        KeystoreException

Push a simple badge number to one or more devices.

Parameters:

badge - the badge number to push.

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

devices - a list or an array of tokens or devices: String[], List<String>, Device[], List<Device>, String or Device

Returns:

a list of pushed notifications, each with details on transmission results and error (if any)

Throws:

KeystoreException - thrown if an error occurs when loading the keystore

CommunicationException - thrown if an unrecoverable error occurs while trying to communicate with Apple servers

sound

public static PushedNotifications sound(String sound,
                                        Object keystore,
                                        String password,
                                        boolean production,
                                        Object devices)
                                 throws CommunicationException,
                                        KeystoreException

Push a simple sound name to one or more devices.

Parameters:

sound - the sound name (stored in the client app) to push.

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

devices - a list or an array of tokens or devices: String[], List<String>, Device[], List<Device>, String or Device

Returns:

a list of pushed notifications, each with details on transmission results and error (if any)

Throws:

KeystoreException - thrown if an error occurs when loading the keystore

CommunicationException - thrown if an unrecoverable error occurs while trying to communicate with Apple servers

combined

public static PushedNotifications combined(String message,
                                           int badge,
                                           String sound,
                                           Object keystore,
                                           String password,
                                           boolean production,
                                           Object devices)
                                    throws CommunicationException,
                                           KeystoreException

Push a notification combining an alert, a badge and a sound.

Parameters:

message - the alert message to push (set to null to skip).

badge - the badge number to push (set to -1 to skip).

sound - the sound name to push (set to null to skip).

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

devices - a list or an array of tokens or devices: String[], List<String>, Device[], List<Device>, String or Device

Returns:

a list of pushed notifications, each with details on transmission results and error (if any)

Throws:

KeystoreException - thrown if an error occurs when loading the keystore

CommunicationException - thrown if an unrecoverable error occurs while trying to communicate with Apple servers

contentAvailable

public static PushedNotifications contentAvailable(Object keystore,
                                                   String password,
                                                   boolean production,
                                                   Object devices)
                                            throws CommunicationException,
                                                   KeystoreException

Push a content-available notification for Newsstand.

Parameters:

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

devices - a list or an array of tokens or devices: String[], List<String>, Device[], List<Device>, String or Device

Returns:

a list of pushed notifications, each with details on transmission results and error (if any)

Throws:

KeystoreException - thrown if an error occurs when loading the keystore

CommunicationException - thrown if an unrecoverable error occurs while trying to communicate with Apple servers

test

public static PushedNotifications test(Object keystore,
                                       String password,
                                       boolean production,
                                       Object devices)
                                throws CommunicationException,
                                       KeystoreException

Push a special test notification with an alert message containing useful debugging information.

Parameters:

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

devices - a list or an array of tokens or devices: String[], List<String>, Device[], List<Device>, String or Device

Returns:

a list of pushed notifications, each with details on transmission results and error (if any)

Throws:

KeystoreException - thrown if an error occurs when loading the keystore

CommunicationException - thrown if an unrecoverable error occurs while trying to communicate with Apple servers

payload

public static PushedNotifications payload(Payload payload,
                                          Object keystore,
                                          String password,
                                          boolean production,
                                          Object devices)
                                   throws CommunicationException,
                                          KeystoreException

Push a preformatted payload to a list of devices.

Parameters:

payload - a simple or complex payload to push.

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

devices - a list or an array of tokens or devices: String[], List<String>, Device[], List<Device>, String or Device

Returns:

a list of pushed notifications, each with details on transmission results and error (if any)

Throws:

KeystoreException - thrown if an error occurs when loading the keystore

CommunicationException - thrown if an unrecoverable error occurs while trying to communicate with Apple servers

payload

public static PushedNotifications payload(Payload payload,
                                          Object keystore,
                                          String password,
                                          boolean production,
                                          int numberOfThreads,
                                          Object devices)
                                   throws Exception

Push a preformatted payload to a list of devices using multiple simulatenous threads (and connections).

Parameters:

payload - a simple or complex payload to push.

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

numberOfThreads - the number of parallel threads to use to push the notifications

devices - a list or an array of tokens or devices: String[], List<String>, Device[], List<Device>, String or Device

Returns:

a list of pushed notifications, each with details on transmission results and error (if any)

Throws:

Exception - thrown if any critical exception occurs

queue

public static PushQueue queue(Object keystore,
                              String password,
                              boolean production,
                              int numberOfThreads)
                       throws KeystoreException

Build and start an asynchronous queue for sending notifications later without opening and closing connections. The returned queue is not started, meaning that underlying threads and connections are not initialized. The queue will start if you invoke its start() method or one of the add() methods. Once the queue is started, its underlying thread(s) and connection(s) will remain active until the program ends.

Parameters:

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

numberOfThreads - the number of parallel threads to use to push the notifications

Returns:

a live queue to which you can add notifications to be sent asynchronously

Throws:

KeystoreException - thrown if an error occurs when loading the keystore

payloads

public static PushedNotifications payloads(Object keystore,
                                           String password,
                                           boolean production,
                                           Object payloadDevicePairs)
                                    throws CommunicationException,
                                           KeystoreException

Push a different preformatted payload for each device.

Parameters:

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

payloadDevicePairs - a list or an array of PayloadPerDevice: List<PayloadPerDevice>, PayloadPerDevice[] or PayloadPerDevice

Returns:

a list of pushed notifications, each with details on transmission results and error (if any)

Throws:

KeystoreException - thrown if an error occurs when loading the keystore

CommunicationException - thrown if an unrecoverable error occurs while trying to communicate with Apple servers

payloads

public static PushedNotifications payloads(Object keystore,
                                           String password,
                                           boolean production,
                                           int numberOfThreads,
                                           Object payloadDevicePairs)
                                    throws Exception

Push a different preformatted payload for each device using multiple simulatenous threads (and connections).

Parameters:

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

numberOfThreads - the number of parallel threads to use to push the notifications

payloadDevicePairs - a list or an array of PayloadPerDevice: List<PayloadPerDevice>, PayloadPerDevice[] or PayloadPerDevice

Returns:

a list of pushed notifications, each with details on transmission results and error (if any)

Throws:

Exception - thrown if any critical exception occurs

feedback

public static List<Device> feedback(Object keystore,
                                    String password,
                                    boolean production)
                             throws CommunicationException,
                                    KeystoreException

Retrieve a list of devices that should be removed from future notification lists.

Devices in this list are ones that you previously tried to push a notification to, but to which Apple could not actually deliver because the device user has either opted out of notifications, has uninstalled your application, or some other conditions.

Important: Apple's Feedback Service always resets its list of inactive devices after each time you contact it. Calling this method twice will not return the same list of devices!

Please be aware that Apple does not specify precisely when a device will be listed by the Feedback Service. More specifically, it is unlikely that the device will be listed immediately if you uninstall the application during testing. It might get listed after some number of notifications couldn't reach it, or some amount of time has elapsed, or a combination of both.

Further more, if you are using Apple's sandbox servers, the Feedback Service will probably not list your device if you uninstalled your app and it was the last one on your device that was configured to receive notifications from the sandbox. See the library's wiki for more information.

Parameters:

keystore - a keystore containing your private key and the certificate signed by Apple (File, InputStream, byte[], KeyStore or String for a file path)

password - the keystore's password.

production - true to use Apple's production servers, false to use the sandbox servers.

Returns:

a list of devices that are inactive.

Throws:

KeystoreException - thrown if an error occurs when loading the keystore

CommunicationException - thrown if an unrecoverable error occurs while trying to communicate with Apple servers