ApnsClient (Pushy 0.6 API)

java.lang.Object
- com.relayrides.pushy.apns.ApnsClient<T>

Type Parameters:

T - the type of notification handled by the client
```
public class ApnsClient<T extends ApnsPushNotification>
extends Object
```
An APNs client sends push notifications to the APNs gateway. An APNs client connects to the APNs server and, as part of a TLS handshake, presents a certificate that identifies the client and the "topics" to which it can send push notifications. Please see Apple's Local and Remote Notification Programming Guide for detailed discussion of topics and certificate provisioning.

To construct a client, callers will need to provide the certificate provisioned by Apple and its accompanying private key. The certificate and key will be used to authenticate the client and identify the topics to which it can send notifications. 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.

Once a client has been constructed, it must connect to an APNs server before it can begin sending push notifications. Apple provides a production and development gateway; see PRODUCTION_APNS_HOST and DEVELOPMENT_APNS_HOST. See the APNs Provider API documentation for additional details.

Once a connection has been established, an APNs client will attempt to restore that connection automatically if the connection closes unexpectedly. APNs clients employ an exponential back-off strategy to manage the rate of reconnection attempts. Clients will stop trying to reconnect automatically if disconnected via the disconnect() method.

Notifications sent by a client to an APNs server are sent asynchronously. A io.netty.util.concurrent.Future 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. Please note that the Future returned is a io.netty.util.concurrent.Future, which is an extension of the java.util.concurrent.Future interface that allows callers to attach listeners that will be notified when the Future completes.

APNs clients are intended to be long-lived, persistent resources. Callers should shut them down 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

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`ALTERNATE_APNS_PORT` An alternative port for communication with the APNs gateway.
`static int`	`DEFAULT_APNS_PORT` The default (HTTPS) port for communication with the APNs gateway.
`static long`	`DEFAULT_WRITE_TIMEOUT_MILLIS` The default write timeout, in milliseconds.
`static String`	`DEVELOPMENT_APNS_HOST` The hostname for the development APNs gateway.
`static String`	`PRODUCTION_APNS_HOST` The hostname for the production APNs gateway.

Constructor Summary

Constructors
Constructor and Description
`ApnsClient(File p12File, String password)` Creates a new APNs client that will identify itself to the APNs gateway with the certificate and key from the given PKCS#12 file.
`ApnsClient(File p12File, String password, EventLoopGroup eventLoopGroup)` Creates a new APNs client that will identify itself to the APNs gateway with the certificate and key from the given PKCS#12 file.
`ApnsClient(InputStream p12InputStream, String password)` Creates a new APNs client that will identify itself to the APNs gateway with the certificate and key from the given PKCS#12 input stream.
`ApnsClient(InputStream p12InputStream, String password, EventLoopGroup eventLoopGroup)` Creates a new APNs client that will identify itself to the APNs gateway with the certificate and key from the given PKCS#12 input stream.
`ApnsClient(X509Certificate certificate, PrivateKey privateKey, String privateKeyPassword)` Creates a new APNs client that will identify itself to the APNs gateway with the given certificate and key.
`ApnsClient(X509Certificate certificate, PrivateKey privateKey, String privateKeyPassword, EventLoopGroup eventLoopGroup)` Creates a new APNs client that will identify itself to the APNs gateway with the given certificate and key.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Future<Void>`	`connect(String host)` Connects to the given APNs gateway on the default (HTTPS) port (443).
`Future<Void>`	`connect(String host, int port)` Connects to the given APNs gateway on the given port.
`Future<Void>`	`disconnect()` Gracefully disconnects from the APNs gateway.
`Future<Void>`	`getReconnectionFuture()` Returns a `Future` that will succeed when the client has re-established a connection to the APNs gateway.
`boolean`	`isConnected()` Indicates whether this client is connected to the APNs gateway and ready to send push notifications.
`Future<PushNotificationResponse<T>>`	`sendNotification(T notification)` Sends a push notification to the APNs gateway.
`void`	`setConnectionTimeout(int timeoutMillis)` Sets the maximum amount of time, in milliseconds, that a client will wait to establish a connection with the APNs server before the connection attempt is considered a failure.
`void`	`setGracefulShutdownTimeout(long timeoutMillis)` Sets the amount of time (in milliseconds) clients should wait for in-progress requests to complete before closing a connection during a graceful shutdown.
`void`	`setMetricsListener(ApnsClientMetricsListener metricsListener)` Sets the metrics listener for this client.
`void`	`setProxyHandlerFactory(ProxyHandlerFactory proxyHandlerFactory)` Sets the proxy handler factory to be used to construct proxy handlers when establishing a new connection to the APNs gateway.
`void`	`setWriteTimeout(long writeTimeoutMillis)` Sets the write timeout for this client.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_WRITE_TIMEOUT_MILLIS
```
public static final long DEFAULT_WRITE_TIMEOUT_MILLIS
```
    The default write timeout, in milliseconds.
    
    See Also:
    
    Constant Field Values
  - PRODUCTION_APNS_HOST
```
public static final String PRODUCTION_APNS_HOST
```
    The hostname for the production APNs gateway.
    
    See Also:
    
    Constant Field Values
  - DEVELOPMENT_APNS_HOST
```
public static final String DEVELOPMENT_APNS_HOST
```
    The hostname for the development APNs gateway.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_APNS_PORT
```
public static final int DEFAULT_APNS_PORT
```
    The default (HTTPS) port for communication with the APNs gateway.
    
    See Also:
    
    Constant Field Values
  - ALTERNATE_APNS_PORT
```
public static final int ALTERNATE_APNS_PORT
```
    An alternative port for communication with the APNs gateway. According to Apple's documentation:
    
    You can alternatively use port 2197 when communicating with APNs. You might do this, for example, to allow APNs traffic through your firewall but to block other HTTPS traffic.
    
    See Also:
    
    APNs Provider API, Connections, Constant Field Values
- Constructor Detail
  - ApnsClient
```
public ApnsClient(File p12File,
                  String password)
           throws SSLException,
                  FileNotFoundException,
                  IOException
```
    Creates a new APNs client that will identify itself to the APNs gateway with the certificate and key from the given PKCS#12 file. The PKCS#12 file must contain a single certificate/private key pair.
    
    Clients created using this method will use a default, internally-managed event loop group. Once the client has been disconnected via the disconnect() method, its event loop will be shut down and the client cannot be reconnected.
    
    Parameters:
    
    p12File - a PKCS#12-formatted file containing the certificate and private key to be used to identify the client to the APNs server
    
    password - the password to be used to decrypt the contents of the given PKCS#12 file
    
    Throws:
    
    SSLException - if the given PKCS#12 file could not be loaded or if any other SSL-related problem arises when constructing the context
    
    FileNotFoundException - if the given PKCS#12 file could not be found
    
    IOException - if any IO problem occurs while attempting to read the given PKCS#12 file
    
    Since:
    
    0.5
  - ApnsClient
```
public ApnsClient(File p12File,
                  String password,
                  EventLoopGroup eventLoopGroup)
           throws SSLException,
                  FileNotFoundException,
                  IOException
```
    Creates a new APNs client that will identify itself to the APNs gateway with the certificate and key from the given PKCS#12 file. The PKCS#12 file must contain a single certificate/private key pair.
    
    Clients created using this method will use the provided event loop group, which may be useful in cases where multiple clients are running in parallel. If a client is created using this method, it is the responsibility of the caller to shut down the event loop group. Clients created with an externally-provided event loop group may be reconnected after being shut down via the disconnect() method.
    
    Parameters:
    
    p12File - a PKCS#12-formatted file containing the certificate and private key to be used to identify the client to the APNs server
    
    password - the password to be used to decrypt the contents of the given PKCS#12 file
    
    eventLoopGroup - the event loop group to be used to handle I/O events for this client
    
    Throws:
    
    SSLException - if the given PKCS#12 file could not be loaded or if any other SSL-related problem arises when constructing the context
    
    FileNotFoundException - if the given PKCS#12 file could not be found
    
    IOException - if any IO problem occurs while attempting to read the given PKCS#12 file
    
    Since:
    
    0.5
  - ApnsClient
```
public ApnsClient(InputStream p12InputStream,
                  String password)
           throws SSLException
```
    Creates a new APNs client that will identify itself to the APNs gateway with the certificate and key from the given PKCS#12 input stream. The PKCS#12 input stream must contain a single certificate/private key pair.
    
    Clients created using this method will use a default, internally-managed event loop group. Once the client has been disconnected via the disconnect() method, its event loop will be shut down and the client cannot be reconnected.
    
    Parameters:
    
    p12InputStream - an input stream for PKCS#12-formatted data containing the certificate and private key to be used to identify the client to the APNs server
    
    password - the password to be used to decrypt the contents of the given PKCS#12 data
    
    Throws:
    
    SSLException - if the given PKCS#12 data could not be loaded or if any other SSL-related problem arises when constructing the context
    
    Since:
    
    0.5.2
  - ApnsClient
```
public ApnsClient(InputStream p12InputStream,
                  String password,
                  EventLoopGroup eventLoopGroup)
           throws SSLException
```
    Creates a new APNs client that will identify itself to the APNs gateway with the certificate and key from the given PKCS#12 input stream. The PKCS#12 input stream must contain a single certificate/private key pair.
    
    Clients created using this method will use the provided event loop group, which may be useful in cases where multiple clients are running in parallel. If a client is created using this method, it is the responsibility of the caller to shut down the event loop group. Clients created with an externally-provided event loop group may be reconnected after being shut down via the disconnect() method.
    
    Parameters:
    
    p12InputStream - an input stream for PKCS#12-formatted data containing the certificate and private key to be used to identify the client to the APNs server
    
    password - the password to be used to decrypt the contents of the given PKCS#12 data
    
    eventLoopGroup - the event loop group to be used to handle I/O events for this client
    
    Throws:
    
    SSLException - if the given PKCS#12 data could not be loaded or if any other SSL-related problem arises when constructing the context
    
    Since:
    
    0.5.2
  - ApnsClient
```
public ApnsClient(X509Certificate certificate,
                  PrivateKey privateKey,
                  String privateKeyPassword)
           throws SSLException
```
    Creates a new APNs client that will identify itself to the APNs gateway with the given certificate and key.
    
    Clients created using this method will use a default, internally-managed event loop group. Once the client has been disconnected via the disconnect() method, its event loop will be shut down and the client cannot be reconnected.
    
    Parameters:
    
    certificate - the certificate to be used to identify the client to the APNs server
    
    privateKey - the private key for the client certificate
    
    privateKeyPassword - the password to be used to decrypt the private key; may be null if the private key does not require a password
    
    Throws:
    
    SSLException - if the given key or certificate could not be loaded or if any other SSL-related problem arises when constructing the context
    
    Since:
    
    0.5
  - ApnsClient
```
public ApnsClient(X509Certificate certificate,
                  PrivateKey privateKey,
                  String privateKeyPassword,
                  EventLoopGroup eventLoopGroup)
           throws SSLException
```
    Creates a new APNs client that will identify itself to the APNs gateway with the given certificate and key.
    
    Clients created using this method will use the provided event loop group, which may be useful in cases where multiple clients are running in parallel. If a client is created using this method, it is the responsibility of the caller to shut down the event loop group. Clients created with an externally-provided event loop group may be reconnected after being shut down via the disconnect() method.
    
    Parameters:
    
    certificate - the certificate to be used to identify the client to the APNs server
    
    privateKey - the private key for the client certificate
    
    privateKeyPassword - the password to be used to decrypt the private key; may be null if the private key does not require a password
    
    eventLoopGroup - the event loop group to be used to handle I/O events for this client
    
    Throws:
    
    SSLException - if the given key or certificate could not be loaded or if any other SSL-related problem arises when constructing the context
    
    Since:
    
    0.5
- Method Detail
  - setConnectionTimeout
```
public void setConnectionTimeout(int timeoutMillis)
```
    Sets the maximum amount of time, in milliseconds, that a client will wait to establish a connection with the APNs server before the connection attempt is considered a failure.
    
    Parameters:
    
    timeoutMillis - the maximum amount of time in milliseconds to wait for a connection attempt to complete
    
    Since:
    
    0.5
  - setMetricsListener
```
public void setMetricsListener(ApnsClientMetricsListener metricsListener)
```
    Sets the metrics listener for this client.
    
    Parameters:
    
    metricsListener - the metrics listener for this client, or null if this client should not report metrics to a listener
    
    Since:
    
    0.6
  - setWriteTimeout
```
public void setWriteTimeout(long writeTimeoutMillis)
```
    Sets the write timeout for this client. If an attempt to send a notification to the APNs server takes longer than the given timeout, the connection will be closed (and automatically reconnected later). Note that write timeouts refer to the amount of time taken to send a notification to the server, and not the time taken by the server to process and respond to a notification.
    
    Write timeouts should generally be set before starting a connection attempt. Changes to a client's write timeout will take effect after the next connection attempt; changes made to an already-connected client will have no immediate effect.
    
    By default, clients have a write timeout of milliseconds.
    
    Parameters:
    
    writeTimeoutMillis - the write timeout for this client in milliseconds; if zero, write attempts will never time out
    
    Since:
    
    0.6
  - setProxyHandlerFactory
```
public void setProxyHandlerFactory(ProxyHandlerFactory proxyHandlerFactory)
```
    Sets the proxy handler factory to be used to construct proxy handlers when establishing a new connection to the APNs gateway. Proxy handlers are added to the beginning of the client's pipeline. A client's proxy handler factory may be null, in which case the client will connect to the gateway directly and will not use a proxy. By default, clients will not use a proxy.
    
    Parameters:
    
    proxyHandlerFactory - the proxy handler factory to be used to construct proxy handlers, or null if this client should not use a proxy
    
    Since:
    
    0.6
  - connect
```
public Future<Void> connect(String host)
```
    Connects to the given APNs gateway on the default (HTTPS) port (443).
    
    Once an initial connection has been established and until the client has been explicitly disconnected via the disconnect() method, the client will attempt to reconnect automatically if the connection closes unexpectedly. If the connection closes unexpectedly, callers may monitor the status of the reconnection attempt with the Future returned by the getReconnectionFuture() method.
    
    Parameters:
    
    host - the APNs gateway to which to connect
    
    Returns:
    
    a Future that will succeed when the client has connected to the gateway and is ready to send push notifications
    
    Since:
    
    0.5
    
    See Also:
    
    PRODUCTION_APNS_HOST, DEVELOPMENT_APNS_HOST
  - connect
```
public Future<Void> connect(String host,
                            int port)
```
    Connects to the given APNs gateway on the given port.
    
    Once an initial connection has been established and until the client has been explicitly disconnected via the disconnect() method, the client will attempt to reconnect automatically if the connection closes unexpectedly. If the connection closes unexpectedly, callers may monitor the status of the reconnection attempt with the Future returned by the getReconnectionFuture() method.
    
    Parameters:
    
    host - the APNs gateway to which to connect
    
    port - the port on which to connect to the APNs gateway
    
    Returns:
    
    a Future that will succeed when the client has connected to the gateway and is ready to send push notifications
    
    Since:
    
    0.5
    
    See Also:
    
    PRODUCTION_APNS_HOST, DEVELOPMENT_APNS_HOST, DEFAULT_APNS_PORT, ALTERNATE_APNS_PORT
  - isConnected
```
public boolean isConnected()
```
    Indicates whether this client is connected to the APNs gateway and ready to send push notifications.
    
    Returns:
    
    true if this client is connected and ready to send notifications or false otherwise
    
    Since:
    
    0.5
  - getReconnectionFuture
```
public Future<Void> getReconnectionFuture()
```
    Returns a Future that will succeed when the client has re-established a connection to the APNs gateway. Callers may use this method to determine when it is safe to resume sending notifications after a send attempt fails with a ClientNotConnectedException.
    
    If the client is already connected, the Future returned by this method will succeed immediately. If the client was not previously connected (either because it has never been connected or because it was explicitly disconnected via the disconnect() method), the Future returned by this method will fail immediately with an IllegalStateException.
    
    Returns:
    
    a Future that will succeed when the client has established a connection to the APNs gateway
    
    Since:
    
    0.5
  - sendNotification
```
public Future<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.
    
    In particular, attempts to send a notification when the client is not connected will fail with a ClientNotConnectedException. If the client was previously connected and has not been explicitly disconnected (via the disconnect() method), the client will attempt to reconnect automatically. Callers may wait for a reconnection attempt to complete by waiting for the Future returned by the getReconnectionFuture() method.
    
    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.5
  - setGracefulShutdownTimeout
```
public void setGracefulShutdownTimeout(long timeoutMillis)
```
    Sets the amount of time (in milliseconds) clients should wait for in-progress requests to complete before closing a connection during a graceful shutdown.
    
    Parameters:
    
    timeoutMillis - the number of milliseconds to wait for in-progress requests to complete before closing a connection
    
    Since:
    
    0.5
    
    See Also:
    
    disconnect()
  - disconnect
```
public Future<Void> disconnect()
```
    Gracefully disconnects from the APNs gateway. The disconnection process will wait until notifications in flight have been either accepted or rejected by the gateway. The returned Future will be marked as complete when the connection has closed completely. If the connection is already closed when this method is called, the returned Future will be marked as complete immediately.
    
    If a non-null EventLoopGroup was provided at construction time, clients may be reconnected and reused after they have been disconnected. If no event loop group was provided at construction time, clients may not be restarted after they have been disconnected via this method.
    
    Returns:
    
    a Future that will be marked as complete when the connection has been closed
    
    Since:
    
    0.5

Class ApnsClient<T extends ApnsPushNotification>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_WRITE_TIMEOUT_MILLIS

PRODUCTION_APNS_HOST

DEVELOPMENT_APNS_HOST

DEFAULT_APNS_PORT

ALTERNATE_APNS_PORT

Constructor Detail

ApnsClient

ApnsClient

ApnsClient

ApnsClient

ApnsClient

ApnsClient

Method Detail

setConnectionTimeout

setMetricsListener

setWriteTimeout

setProxyHandlerFactory

connect

connect

isConnected

getReconnectionFuture

sendNotification

setGracefulShutdownTimeout

disconnect