Package com.eatthepath.pushy.apns

Class ApnsClient

java.lang.Object
com.eatthepath.pushy.apns.ApnsClient
public class ApnsClient extends Object

An APNs client sends push notifications to the APNs gateway. Clients authenticate themselves to APNs servers in one of two ways: they may either present a TLS certificate to the server at connection time, or they may present authentication tokens for each notification they send. Clients that opt to use TLS-based authentication may send notifications to any topic named in the client certificate. Clients that opt to use token-based authentication may send notifications to any topic associated with the team to which the client's signing key belongs. Please see the UserNotifications Framework documentation for a detailed discussion of the APNs protocol, topics, and certificate/key provisioning.

Clients are constructed using an ApnsClientBuilder. Callers may optionally specify an EventLoopGroup when constructing a new client. If no event loop group is specified, clients will create and manage their own single-thread event loop group. If many clients are operating in parallel, specifying a shared event loop group serves as a mechanism to keep the total number of threads in check. Callers may also want to provide a specific event loop group to take advantage of platform-specific features (i.e. epoll or KQueue).

Callers must either provide an SSL context with the client's certificate or a signing key at client construction time. If a signing key is provided, the client will use token authentication when sending notifications; otherwise, it will use TLS-based authentication. It is an error to provide both a client certificate and a signing key.

Clients maintain their own internal connection pools and open connections to the APNs server on demand. As a result, clients do not need to be "started" explicitly, and are ready to begin sending notifications as soon as they're constructed.

Notifications sent by a client to an APNs server are sent asynchronously. A CompletableFuture is returned immediately when a notification is sent, but will not complete until the attempt to send the notification has failed, the notification has been accepted by the APNs server, or the notification has been rejected by the APNs server.

APNs clients are intended to be long-lived, persistent resources. They are also inherently thread-safe and can be shared across many threads in a complex application. Callers must shut them down via the close() method when they are no longer needed (i.e. when shutting down the entire application). If an event loop group was specified at construction time, callers should shut down that event loop group when all clients using that group have been disconnected.

Since:
0.5
Author:
Jon Chambers

  • Method Details

    • sendNotification

      public <T extends ApnsPushNotification> PushNotificationFuture<T,PushNotificationResponse<T>> sendNotification(T notification)

      Sends a push notification to the APNs gateway.

      This method returns a Future that indicates whether the notification was accepted or rejected by the gateway. If the notification was accepted, it may be delivered to its destination device at some time in the future, but final delivery is not guaranteed. Rejections should be considered permanent failures, and callers should not attempt to re-send the notification.

      The returned Future may fail with an exception if the notification could not be sent. Failures to send a notification to the gateway—i.e. those that fail with exceptions—should generally be considered non-permanent, and callers should attempt to re-send the notification when the underlying problem has been resolved.

      Type Parameters:
      T - the type of notification to be sent
      Parameters:
      notification - the notification to send to the APNs gateway
      Returns:
      a Future that will complete when the notification has been either accepted or rejected by the APNs gateway
      Since:
      0.8

    • close

      public CompletableFuture<Void> close()

      Gracefully shuts down the client, closing all connections and releasing all persistent resources. The disconnection process will wait until notifications that have been sent to the APNs server have been either accepted or rejected. Note that some notifications passed to sendNotification(ApnsPushNotification) may still be enqueued and not yet sent by the time the shutdown process begins; the Futures associated with those notifications will fail.

      The returned Future will be marked as complete when all connections in this client's pool have closed completely and (if no EventLoopGroup was provided at construction time) the client's event loop group has shut down. If the client has already shut down, the returned Future will be marked as complete immediately.

      Clients may not be reused once they have been closed.

      Returns:
      a Future that will be marked as complete when the client has finished shutting down
      Since:
      0.11