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

static class

NotificationThread.MODE Working modes supported by Notification Threads.

Constructor Summary

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

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() Deprecated. Not thead-safe. use getPushedNotifications(true) instead.
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() Deprecated. Not thead-safe. use getPushedNotifications(true).getFailedNotifications() instead.
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(boolean clearList) Returns a list of all notifications pushed by this thread (successful or not).
long	getSleepBetweenNotifications()
PushedNotifications	getSuccessfulNotifications() Deprecated. Not thead-safe. use getPushedNotifications(true).getSuccessfulNotifications() instead.
int	getThreadNumber() Return the thread number assigned by the parent NotificationThreads object, if any.
boolean	isBusy() Determine if this thread is busy.
int	newMessageIdentifier() Return a new sequential message identifier.
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.
int	size() Get the number of devices that this thread pushes to.
NotificationThread	start() Start the transmission thread.
void	stopQueue() Invoke stopQueue on all threads working for the queue.

Methods inherited from class java.lang.Object

equals, 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

stopQueue

public void stopQueue()

Description copied from interface: PushQueue

Invoke stopQueue on all threads working for the queue.

Specified by:

stopQueue in interface PushQueue

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

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 -

getMaxNotificationsPerConnection

public int getMaxNotificationsPerConnection()

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 -

getSleepBetweenNotifications

public long getSleepBetweenNotifications()

getDevices

public List<Device> getDevices()

Get the list of devices associated with this thread.

Returns:

a list of devices

size

public int size()

Get the number of devices that this thread pushes to.

Returns:

the number of devices registered with this thread

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

getListener

public NotificationProgressListener getListener()

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

newMessageIdentifier

public int newMessageIdentifier()

Return a new sequential message identifier.

Returns:

a message identifier unique to all NotificationThread objects

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(boolean clearList)

Returns a list of all notifications pushed by this thread (successful or not). IMPORTANT: Invoking this method on a QUEUE causes a connection restart to get an opportunity to receive error-response packets (if any) which might affect the result of this method.

Specified by:

getPushedNotifications in interface PushQueue

Parameters:

clearList - indicate if the internal list of pushed notifications should be emptied (recommended)

Returns:

a list of pushed notifications

clearPushedNotifications

@Deprecated
public void clearPushedNotifications()

Deprecated. Not thead-safe. use getPushedNotifications(true) instead.

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

@Deprecated
public PushedNotifications getFailedNotifications()

Deprecated. Not thead-safe. use getPushedNotifications(true).getFailedNotifications() instead.

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

Returns:

a list of failed notifications

getSuccessfulNotifications

@Deprecated
public PushedNotifications getSuccessfulNotifications()

Deprecated. Not thead-safe. use getPushedNotifications(true).getSuccessfulNotifications() instead.

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. IMPORTANT: Invoking this method on a QUEUE causes a connection restart to get an opportunity to receive error-response packets (if any) which might affect the result of this method.

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