javapns.notification.transmission
Class NotificationThreads

java.lang.Object
  java.lang.ThreadGroup
      javapns.notification.transmission.NotificationThreads

All Implemented Interfaces:

Thread.UncaughtExceptionHandler, PushQueue

public class NotificationThreads
extends ThreadGroup
implements PushQueue

Pushes a payload to a large number of devices using multiple threads

The list of devices is spread evenly into multiple NotificationThreads.

Usage: once a NotificationThreads is created, invoke start() to start all NotificationThread threads.

You can provide a NotificationProgressListener to receive events about the work being done.

Author:

Sylvain Pedneault

See Also:

NotificationThread.MODE, NotificationThread

Constructor Summary

NotificationThreads(AppleNotificationServer server, int numberOfThreads)
Create a pool of notification threads in QUEUE mode.

NotificationThreads(AppleNotificationServer server, List<PayloadPerDevice> messages, int numberOfThreads)
Create the specified number of notification threads and spread the messages evenly between the threads.

NotificationThreads(AppleNotificationServer server, Payload payload, List<Device> devices, int numberOfThreads)
Create the specified number of notification threads and spread the devices evenly between the threads.

NotificationThreads(AppleNotificationServer server, Payload payload, List<Device> devices, List<NotificationThread> threads)
Spread the devices evenly between the provided threads.

NotificationThreads(AppleNotificationServer server, Payload payload, List<NotificationThread> threads)
Use the provided threads which should already each have their group of devices to work with.

NotificationThreads(Object keystore, String password, boolean production, Payload payload, List<Device> devices, int numberOfThreads)
Create the specified number of notification threads and spread the devices evenly between the threads.

NotificationThreads(Object keystore, String password, boolean production, Payload payload, List<Device> devices, List<NotificationThread> threads)
Spread the devices evenly between the provided threads.

NotificationThreads(Object keystore, String password, boolean production, Payload payload, List<NotificationThread> threads)
Use the provided threads which should already each have their group of devices to work with.

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.
List<Exception>	getCriticalExceptions() Get a list of critical exceptions that threads experienced.
long	getDelayBetweenThreads() Get the amount of time that the library will wait after starting a thread and before starting the next one.
PushedNotifications	getFailedNotifications() Deprecated. Not thead-safe. use getPushedNotifications(true).getFailedNotifications() instead.
NotificationProgressListener	getListener() Get the progress listener, if any is attached.
PushedNotifications	getPushedNotifications(boolean clearLists) Get a list of all notifications pushed by all threads.
PushedNotifications	getSuccessfulNotifications() Deprecated. Not thead-safe. use getPushedNotifications(true).getSuccessfulNotifications() instead.
List<NotificationThread>	getThreads() Get a list of threads created to push notifications.
void	setDelayBetweenThreads(long delayBetweenThreads) Set the amount of time that the library will wait after starting a thread and before starting the next one.
void	setListener(NotificationProgressListener listener) Attach an event listener to this object as well as all linked threads.
void	setMaxNotificationsPerConnection(int notifications) Configure in all threads the maximum number of notifications per connection.
void	setSleepBetweenNotifications(long milliseconds) Configure in all threads the number of milliseconds that threads should wait between each notification.
NotificationThreads	start() Start all notification threads.
void	stopQueue() Invoke stopQueue on all threads working for the queue.
void	waitForAllThreads() Wait for all threads to complete their work.
void	waitForAllThreads(boolean throwCriticalExceptions) Wait for all threads to complete their work, but throw any critical exception that occurs in a thread.

Methods inherited from class java.lang.ThreadGroup

activeCount, activeGroupCount, allowThreadSuspension, checkAccess, destroy, enumerate, enumerate, enumerate, enumerate, getMaxPriority, getName, getParent, interrupt, isDaemon, isDestroyed, list, parentOf, resume, setDaemon, setMaxPriority, stop, suspend, toString, uncaughtException

Methods inherited from class java.lang.Object

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

Constructor Detail

NotificationThreads

public NotificationThreads(AppleNotificationServer server,
                           Payload payload,
                           List<Device> devices,
                           int numberOfThreads)

Create the specified number of notification threads and spread the devices evenly between the threads.

Parameters:

server - the server to push to

payload - the payload to push

devices - a very large list of devices

numberOfThreads - the number of threads to create to share the work

NotificationThreads

public NotificationThreads(AppleNotificationServer server,
                           List<PayloadPerDevice> messages,
                           int numberOfThreads)

Create the specified number of notification threads and spread the messages evenly between the threads.

Parameters:

server - the server to push to

messages - a very large list of payload/device pairs

numberOfThreads - the number of threads to create to share the work

NotificationThreads

public NotificationThreads(Object keystore,
                           String password,
                           boolean production,
                           Payload payload,
                           List<Device> devices,
                           int numberOfThreads)
                    throws Exception

Create the specified number of notification threads and spread the devices evenly between the threads. Internally, this constructor uses a AppleNotificationServerBasicImpl to encapsulate the provided keystore, password and production parameters.

Parameters:

keystore - the keystore to use (can be a File, an InputStream, a String for a file path, or a byte[] array)

password - the keystore's password

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

payload - the payload to push

devices - a very large list of devices

numberOfThreads - the number of threads to create to share the work

Throws:

Exception

NotificationThreads

public NotificationThreads(AppleNotificationServer server,
                           Payload payload,
                           List<Device> devices,
                           List<NotificationThread> threads)

Spread the devices evenly between the provided threads.

Parameters:

server - the server to push to

payload - the payload to push

devices - a very large list of devices

threads - a list of pre-built threads

NotificationThreads

public NotificationThreads(Object keystore,
                           String password,
                           boolean production,
                           Payload payload,
                           List<Device> devices,
                           List<NotificationThread> threads)
                    throws Exception

Spread the devices evenly between the provided threads. Internally, this constructor uses a AppleNotificationServerBasicImpl to encapsulate the provided keystore, password and production parameters.

Parameters:

keystore - the keystore to use (can be a File, an InputStream, a String for a file path, or a byte[] array)

password - the keystore's password

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

payload - the payload to push

devices - a very large list of devices

threads - a list of pre-built threads

Throws:

Exception

NotificationThreads

public NotificationThreads(AppleNotificationServer server,
                           Payload payload,
                           List<NotificationThread> threads)

Use the provided threads which should already each have their group of devices to work with.

Parameters:

server - the server to push to

payload - the payload to push

threads - a list of pre-built threads

NotificationThreads

public NotificationThreads(Object keystore,
                           String password,
                           boolean production,
                           Payload payload,
                           List<NotificationThread> threads)
                    throws Exception

Use the provided threads which should already each have their group of devices to work with. Internally, this constructor uses a AppleNotificationServerBasicImpl to encapsulate the provided keystore, password and production parameters.

Parameters:

keystore - the keystore to use (can be a File, an InputStream, a String for a file path, or a byte[] array)

password - the keystore's password

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

payload - the payload to push

threads - a list of pre-built threads

Throws:

Exception

NotificationThreads

public NotificationThreads(AppleNotificationServer server,
                           int numberOfThreads)

Create a pool of notification threads in QUEUE mode.

Parameters:

server - the server to push to

numberOfThreads - the number of threads to create in the pool

Method Detail

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

start

public NotificationThreads start()

Start all notification threads. This method returns immediately, as all threads start working on their own. To wait until all threads are finished, use the waitForAllThreads() method.

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

setMaxNotificationsPerConnection

public void setMaxNotificationsPerConnection(int notifications)

Configure in all threads the maximum number of notifications per connection. As soon as a thread reaches that maximum, it will automatically close the connection, initialize a new connection and continue pushing more notifications.

Parameters:

notifications - the maximum number of notifications that threads will push in a single connection (default is 200)

setSleepBetweenNotifications

public void setSleepBetweenNotifications(long milliseconds)

Configure in all threads the number of milliseconds that threads should wait between each notification. This feature is intended to alleviate intense resource usage that can occur when sending large quantities of notifications very quickly.

Parameters:

milliseconds - the number of milliseconds threads should sleep between individual notifications (default is 0)

stopQueue

public void stopQueue()

Description copied from interface: PushQueue

Invoke stopQueue on all threads working for the queue.

Specified by:

stopQueue in interface PushQueue

getThreads

public List<NotificationThread> getThreads()

Get a list of threads created to push notifications.

Returns:

a list of threads

getListener

public NotificationProgressListener getListener()

Get the progress listener, if any is attached.

Returns:

a progress listener

setListener

public void setListener(NotificationProgressListener listener)

Attach an event listener to this object as well as all linked threads.

Parameters:

listener -

waitForAllThreads

public void waitForAllThreads()
                       throws InterruptedException

Wait for all threads to complete their work. This method blocks and returns only when all threads are done. When using this method, you need to check critical exceptions manually to make sure that all threads were able to do their work. This method should not be used in QUEUE mode, as threads stay idle and never end.

Throws:

InterruptedException

waitForAllThreads

public void waitForAllThreads(boolean throwCriticalExceptions)
                       throws Exception

Wait for all threads to complete their work, but throw any critical exception that occurs in a thread. This method blocks and returns only when all threads are done. This method should not be used in QUEUE mode, as threads stay idle and never end.

Parameters:

throwCriticalExceptions - If true, this method will throw the first critical exception that occured in a thread (if any). If false, critical exceptions will not be checked.

Throws:

Exception - if throwCriticalExceptions is true and a critical exception did occur in a thread

getPushedNotifications

public PushedNotifications getPushedNotifications(boolean clearLists)

Get a list of all notifications pushed by all threads.

Specified by:

getPushedNotifications in interface PushQueue

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 maintained in each thread. 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.

Get a list of all notifications that all threads 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.

Get a list of all notifications that all threads attempted to push and succeeded.

Returns:

a list of successful notifications

getCriticalExceptions

public List<Exception> getCriticalExceptions()

Get a list of critical exceptions that threads experienced. Critical exceptions include CommunicationException and KeystoreException. Exceptions related to tokens, payloads and such are *not* included here, as they are noted in individual PushedNotification objects.

Specified by:

getCriticalExceptions in interface PushQueue

Returns:

a list of critical exceptions

setDelayBetweenThreads

public void setDelayBetweenThreads(long delayBetweenThreads)

Set the amount of time that the library will wait after starting a thread and before starting the next one. The default delay is 200 milliseconds. This means that starting 10 threads will take 2 seconds to fully start. As discussed in issue report #102, adding a delay improves reliability.

Parameters:

delayBetweenThreads - a number of milliseconds

getDelayBetweenThreads

public long getDelayBetweenThreads()

Get the amount of time that the library will wait after starting a thread and before starting the next one.

Returns:

the number of milliseconds currently configured