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.
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
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
- Jon Chambers
sendNotificationpublic <T extends ApnsPushNotification> PushNotificationFuture<T,
PushNotificationResponse<T>>sendNotification (T notification)
Sends a push notification to the APNs gateway.
This method returns a
Futurethat 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.
Futuremay 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
notification- the notification to send to the APNs gateway
Futurethat will complete when the notification has been either accepted or rejected by the APNs gateway
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
Futuresassociated with those notifications will fail.
Futurewill be marked as complete when all connections in this client's pool have closed completely and (if no
EventLoopGroupwas provided at construction time) the client's event loop group has shut down. If the client has already shut down, the returned
Futurewill be marked as complete immediately.
Clients may not be reused once they have been closed.
Futurethat will be marked as complete when the client has finished shutting down