com.relayrides.pushy.apns
Class ApnsConnection<T extends ApnsPushNotification>

java.lang.Object
  com.relayrides.pushy.apns.ApnsConnection<T>

public class ApnsConnection<T extends ApnsPushNotification>
extends Object

A connection to an APNs gateway. An ApnsConnection is responsible for sending push notifications to the APNs gateway, and reports lifecycle events via its ApnsConnectionListener.

Generally, connections should be managed by a parent PushManager and not manipulated directly (although connections are fully functional on their own). Connections are created in a disconnected state, and must be explicitly connected before they can be used to send push notifications.

Author:

Jon Chambers

See Also:

PushManager

Constructor Summary

ApnsConnection(ApnsEnvironment environment, SSLContext sslContext, NioEventLoopGroup eventLoopGroup, ApnsConnectionListener<T> listener)
Constructs a new APNs connection.

Method Summary

void	connect() Asynchronously connects to the APNs gateway in this connection's environment.
void	sendNotification(T notification) Asynchronously sends a push notification to the connected APNs gateway.
void	shutdownGracefully() Gracefully and asynchronously shuts down this connection.
void	shutdownImmediately() Immediately closes this connection (assuming it was ever open).
String	toString()
void	waitForPendingWritesToFinish() Waits for all pending write operations to finish.

Methods inherited from class java.lang.Object

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

Constructor Detail

ApnsConnection

public ApnsConnection(ApnsEnvironment environment,
                      SSLContext sslContext,
                      NioEventLoopGroup eventLoopGroup,
                      ApnsConnectionListener<T> listener)

Constructs a new APNs connection. The connection connects to the APNs gateway in the given environment with the credentials and key/trust managers in the given SSL context.

Parameters:

environment - the environment in which this connection will operate

sslContext - an SSL context with the keys/certificates and trust managers this connection should use when communicating with the APNs gateway

eventLoopGroup - the event loop group this connection should use for asynchronous network operations

listener - the listener to which this connection will report lifecycle events; must not be null

Method Detail

connect

public void connect()

Asynchronously connects to the APNs gateway in this connection's environment. The outcome of the connection attempt is reported via this connection's listener.

See Also:

ApnsConnectionListener.handleConnectionSuccess(ApnsConnection), ApnsConnectionListener.handleConnectionFailure(ApnsConnection, Throwable)

sendNotification

public void sendNotification(T notification)

Asynchronously sends a push notification to the connected APNs gateway. Successful notifications are not acknowledged by the APNs gateway; failed attempts to write push notifications to the outbound buffer and notification rejections are reported via this connection's listener.

Parameters:

notification - the notification to send

See Also:

ApnsConnectionListener.handleWriteFailure(ApnsConnection, ApnsPushNotification, Throwable), ApnsConnectionListener.handleRejectedNotification(ApnsConnection, ApnsPushNotification, RejectedNotificationReason)

waitForPendingWritesToFinish

public void waitForPendingWritesToFinish()
                                  throws InterruptedException

Waits for all pending write operations to finish. When this method exits normally (i.e. when it does not throw an InterruptedException), All pending writes will have either finished successfully or failed and passed to this connection's listener via the ApnsConnectionListener.handleWriteFailure(ApnsConnection, ApnsPushNotification, Throwable) method.

It is not guaranteed that all write operations will have finished by the time a connection has closed. Applications that need to know when all writes have finished should call this method after a connection closes, but must not do so in an IO thread (i.e. the thread that called the ApnsConnectionListener.handleConnectionClosure(ApnsConnection) method.

Throws:

InterruptedException - if interrupted while waiting for pending read/write operations to finish

shutdownGracefully

public void shutdownGracefully()

Gracefully and asynchronously shuts down this connection. Graceful disconnection is triggered by sending a known-bad notification to the APNs gateway; when the gateway rejects the notification, it is guaranteed that preceding notifications were processed successfully and that all following notifications were not processed at all. The gateway will close the connection after rejecting the notification, and this connection's listener will be notified when the connection is closed.

Note that if/when the known-bad notification is rejected by the APNs gateway, this connection's listener will not be notified of the rejection.

Calling this method before establishing a connection with the APNs gateway or while a graceful shutdown attempt is already in progress has no effect.

See Also:

ApnsConnectionListener.handleRejectedNotification(ApnsConnection, ApnsPushNotification, RejectedNotificationReason), ApnsConnectionListener.handleConnectionClosure(ApnsConnection)

shutdownImmediately

public void shutdownImmediately()

Immediately closes this connection (assuming it was ever open). No guarantees are made with regard to the state of sent notifications, and callers should generally prefer shutdownGracefully() to this method. If the connection was previously open, the connection's listener will be notified of the connection's closure. If a connection attempt was in progress, the listener will be notified of a connection failure. If the connection was never open, this method has no effect.

Calling this method while not connected has no effect.

See Also:

ApnsConnectionListener.handleConnectionClosure(ApnsConnection)

toString

public String toString()

Overrides:

toString in class Object