javapns.notification.transmission

Class NotificationThread

java.lang.Object

javapns.notification.transmission.NotificationThread

All Implemented Interfaces:

Runnable, PushQueue

public class NotificationThread
extends Object
implements Runnable, PushQueue

Pushes payloads asynchroneously using a dedicated thread.

A NotificationThread is created with one of two modes: LIST or QUEUE. In LIST mode, the thread is given a predefined list of devices and pushes all notifications as soon as it is started. Its work is complete and the thread ends as soon as all notifications have been sent. In QUEUE mode, the thread is started with no notification to send. It opens a connection and waits for messages to be added to its queue using the addMessageToQueue(..) method. This lifecyle is useful for creating connection pools.

No more than maxNotificationsPerConnection are pushed over a single connection. When that maximum is reached, the connection is restarted automatically and push continues. This is intended to avoid an undocumented notification-per-connection limit observed occasionnally with Apple servers.

Usage (LIST): once a NotificationThread is created using any LIST-mode constructor, invoke start() to push the payload to all devices in a separate thread.

Usage (QUEUE): once a NotificationThread is created using any QUEUE-mode constructor, invoke start() to open a connection and wait for notifications to be queued.

Author:

Sylvain Pedneault

See Also:

NotificationThread.MODE, NotificationThreads

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NotificationThread.MODE Working modes supported by Notification Threads.

Constructor Summary

Constructors

Constructor and Description
NotificationThread(AppleNotificationServer server) Create a standalone thread in QUEUE mode, awaiting messages to push.
NotificationThread(NotificationThreads threads, PushNotificationManager notificationManager, AppleNotificationServer server) Create a grouped thread in QUEUE mode, awaiting messages to push.
NotificationThread(NotificationThreads threads, PushNotificationManager notificationManager, AppleNotificationServer server, Object messages) Create a grouped thread in LIST mode for pushing individual payloads to a list of devices and coordinating with a parent NotificationThreads object.
NotificationThread(NotificationThreads threads, PushNotificationManager notificationManager, AppleNotificationServer server, Payload payload, Object devices) Create a grouped thread in LIST mode for pushing a single payload to a list of devices and coordinating with a parent NotificationThreads object.
NotificationThread(PushNotificationManager notificationManager, AppleNotificationServer server) Create a standalone thread in QUEUE mode, awaiting messages to push.
NotificationThread(PushNotificationManager notificationManager, AppleNotificationServer server, Object messages) Create a standalone thread in LIST mode for pushing individual payloads to a list of devices.
NotificationThread(PushNotificationManager notificationManager, AppleNotificationServer server, Payload payload, Object devices) Create a standalone thread in LIST mode for pushing a single payload to a list of devices.

Method Summary

Modifier and Type	Method and Description
PushQueue	add(Payload payload, Device device) Queue a message for delivery.
PushQueue	add(PayloadPerDevice message) Queue a message for delivery.
PushQueue	add(Payload payload, String token) Queue a message for delivery.
void	clearPushedNotifications() Clear the internal list of PushedNotification objects.
Exception	getCriticalException() If this thread experienced a critical exception (communication error, keystore issue, etc.), this method returns the exception.
List<Exception>	getCriticalExceptions() Wrap a critical exception (if any occurred) into a List to satisfy the NotificationQueue interface contract.
List<Device>	getDevices() Get the list of devices associated with this thread.
PushedNotifications	getFailedNotifications() Returns list of all notifications that this thread attempted to push but that failed.
int	getFirstMessageIdentifier() Returns the first message identifier generated by this thread.
int	getLastMessageIdentifier() Returns the last message identifier generated by this thread.
NotificationProgressListener	getListener()
int	getMaxNotificationsPerConnection()
List<PayloadPerDevice>	getMessages() Get the messages associated with this thread, if any.
PushedNotifications	getPushedNotifications() Returns list of all notifications pushed by this thread (successful or not).
long	getSleepBetweenNotifications()
PushedNotifications	getSuccessfulNotifications() Returns list of all notifications that this thread attempted to push and succeeded.
int	getThreadNumber() Return the thread number assigned by the parent NotificationThreads object, if any.
boolean	isBusy() Determine if this thread is busy.
void	run() Run method for the thread; do not call this method directly.
void	setListener(NotificationProgressListener listener) Provide an event listener which will be notified of this thread's progress.
void	setMaxNotificationsPerConnection(int maxNotificationsPerConnection) Set a maximum number of notifications that should be streamed over a continuous connection to an Apple server.
void	setSleepBetweenNotifications(long milliseconds) Set a delay the thread should sleep between each notification.
NotificationThread	start() Start the transmission thread.

Methods inherited from class java.lang.Object

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

Constructor Detail

NotificationThread

public NotificationThread(NotificationThreads threads,
                          PushNotificationManager notificationManager,
                          AppleNotificationServer server,
                          Payload payload,
                          Object devices)

Create a grouped thread in LIST mode for pushing a single payload to a list of devices and coordinating with a parent NotificationThreads object.

Parameters:

threads - the parent NotificationThreads object that is coordinating multiple threads

notificationManager - the notification manager to use

server - the server to communicate with

payload - a payload to push

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

NotificationThread

public NotificationThread(NotificationThreads threads,
                          PushNotificationManager notificationManager,
                          AppleNotificationServer server,
                          Object messages)

Create a grouped thread in LIST mode for pushing individual payloads to a list of devices and coordinating with a parent NotificationThreads object.

Parameters:

threads - the parent NotificationThreads object that is coordinating multiple threads

notificationManager - the notification manager to use

server - the server to communicate with

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

NotificationThread

public NotificationThread(PushNotificationManager notificationManager,
                          AppleNotificationServer server,
                          Payload payload,
                          Object devices)

Create a standalone thread in LIST mode for pushing a single payload to a list of devices.

Parameters:

notificationManager - the notification manager to use

server - the server to communicate with

payload - a payload to push

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

NotificationThread

public NotificationThread(PushNotificationManager notificationManager,
                          AppleNotificationServer server,
                          Object messages)

Create a standalone thread in LIST mode for pushing individual payloads to a list of devices.

Parameters:

notificationManager - the notification manager to use

server - the server to communicate with

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

NotificationThread

public NotificationThread(NotificationThreads threads,
                          PushNotificationManager notificationManager,
                          AppleNotificationServer server)

Create a grouped thread in QUEUE mode, awaiting messages to push.

Parameters:

threads - the parent NotificationThreads object that is coordinating multiple threads

notificationManager - the notification manager to use

server - the server to communicate with

NotificationThread

public NotificationThread(PushNotificationManager notificationManager,
                          AppleNotificationServer server)

Create a standalone thread in QUEUE mode, awaiting messages to push.

Parameters:

notificationManager - the notification manager to use

server - the server to communicate with

NotificationThread

public NotificationThread(AppleNotificationServer server)

Create a standalone thread in QUEUE mode, awaiting messages to push.

Parameters:

server - the server to communicate with

Method Detail

start

public NotificationThread start()

Start the transmission thread.

This method returns immediately, as the thread starts working on its own.

Specified by:

start in interface PushQueue

Returns:

the queue itself, as a handy shortcut to create and start a queue in a single line of code

run

public void run()

Run method for the thread; do not call this method directly.

Specified by:

run in interface Runnable

add

public PushQueue add(Payload payload,
                     String token)
              throws InvalidDeviceTokenFormatException

Description copied from interface: PushQueue

Queue a message for delivery. A thread will pick it up and push it asynchroneously. This method has no effect if the underlying notification thread is not in QUEUE mode.

Specified by:

add in interface PushQueue

Parameters:

payload - a payload

token - a device token

Returns:

the actual queue to which the message was added, which could be a different one if the request was delegated to a sub-queue

Throws:

InvalidDeviceTokenFormatException

add

public PushQueue add(Payload payload,
                     Device device)

Description copied from interface: PushQueue

Queue a message for delivery. A thread will pick it up and push it asynchroneously. This method has no effect if the underlying notification thread is not in QUEUE mode.

Specified by:

add in interface PushQueue

Parameters:

payload - a payload

device - a device

Returns:

the actual queue to which the message was added, which could be a different one if the request was delegated to a sub-queue

add

public PushQueue add(PayloadPerDevice message)

Description copied from interface: PushQueue

Queue a message for delivery. A thread will pick it up and push it asynchroneously. This method has no effect if the underlying notification thread is not in QUEUE mode.

Specified by:

add in interface PushQueue

Parameters:

message - a payload/device pair

Returns:

the actual queue to which the message was added, which could be a different one if the request was delegated to a sub-queue

getMaxNotificationsPerConnection

public int getMaxNotificationsPerConnection()

setMaxNotificationsPerConnection

public void setMaxNotificationsPerConnection(int maxNotificationsPerConnection)

Set a maximum number of notifications that should be streamed over a continuous connection to an Apple server. When that maximum is reached, the thread automatically closes and reopens a fresh new connection to the server and continues streaming notifications.

Default is 200 (recommended).

Parameters:

maxNotificationsPerConnection -

getSleepBetweenNotifications

public long getSleepBetweenNotifications()

setSleepBetweenNotifications

public void setSleepBetweenNotifications(long milliseconds)

Set a delay the thread should sleep between each notification. This is sometimes useful when communication with Apple servers is unreliable and notifications are streaming too fast.

Default is 0.

Parameters:

milliseconds -

getDevices

public List<Device> getDevices()

Get the list of devices associated with this thread.

Returns:

a list of devices

getListener

public NotificationProgressListener getListener()

setListener

public void setListener(NotificationProgressListener listener)

Provide an event listener which will be notified of this thread's progress.

Parameters:

listener - any object implementing the NotificationProgressListener interface

getThreadNumber

public int getThreadNumber()

Return the thread number assigned by the parent NotificationThreads object, if any.

Returns:

the unique number assigned to this thread by the parent group

getFirstMessageIdentifier

public int getFirstMessageIdentifier()

Returns the first message identifier generated by this thread.

Returns:

a message identifier unique to all NotificationThread objects

getLastMessageIdentifier

public int getLastMessageIdentifier()

Returns the last message identifier generated by this thread.

Returns:

a message identifier unique to all NotificationThread objects

getPushedNotifications

public PushedNotifications getPushedNotifications()

Returns list of all notifications pushed by this thread (successful or not).

Specified by:

getPushedNotifications in interface PushQueue

Returns:

a list of pushed notifications

clearPushedNotifications

public void clearPushedNotifications()

Clear the internal list of PushedNotification objects. You should invoke this method once you no longer need the list of PushedNotification objects so that memory can be reclaimed.

Specified by:

clearPushedNotifications in interface PushQueue

getFailedNotifications

public PushedNotifications getFailedNotifications()

Returns list of all notifications that this thread attempted to push but that failed.

Returns:

a list of failed notifications

getSuccessfulNotifications

public PushedNotifications getSuccessfulNotifications()

Returns list of all notifications that this thread attempted to push and succeeded.

Returns:

a list of failed notifications

getMessages

public List<PayloadPerDevice> getMessages()

Get the messages associated with this thread, if any.

Returns:

messages

isBusy

public boolean isBusy()

Determine if this thread is busy.

Returns:

if the thread is busy or not

getCriticalException

public Exception getCriticalException()

If this thread experienced a critical exception (communication error, keystore issue, etc.), this method returns the exception.

Returns:

a critical exception, if one occurred in this thread

getCriticalExceptions

public List<Exception> getCriticalExceptions()

Wrap a critical exception (if any occurred) into a List to satisfy the NotificationQueue interface contract.

Specified by:

getCriticalExceptions in interface PushQueue

Returns:

a list containing a critical exception, if any occurred