com.turo.pushy.apns

Class ApnsClientBuilder

java.lang.Object

com.turo.pushy.apns.ApnsClientBuilder

public class ApnsClientBuilder
extends Object

An ApnsClientBuilder constructs new ApnsClient instances. Callers must specify the APNs server to which clients connect and must provide either TLS credentials or a signing key (but not both) before building a client. Client builders may be reused to generate multiple clients, and their settings may be changed from one client to the next.

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 int	DEFAULT_PING_IDLE_TIME_MILLIS The default idle time in milliseconds after which the client will send a PING frame to the APNs server.
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
ApnsClientBuilder()

Method Summary

Modifier and Type	Method and Description
ApnsClient	build() Constructs a new ApnsClient with the previously-set configuration.
ApnsClientBuilder	setApnsServer(String hostname) Sets the hostname of the server to which the client under construction will connect.
ApnsClientBuilder	setApnsServer(String hostname, int port) Sets the hostname and port of the server to which the client under construction will connect.
ApnsClientBuilder	setClientCredentials(File p12File, String p12Password) Sets the TLS credentials for the client under construction using the contents of the given PKCS#12 file.
ApnsClientBuilder	setClientCredentials(InputStream p12InputStream, String p12Password) Sets the TLS credentials for the client under construction using the data from the given PKCS#12 input stream.
ApnsClientBuilder	setClientCredentials(X509Certificate clientCertificate, PrivateKey privateKey, String privateKeyPassword) Sets the TLS credentials for the client under construction.
ApnsClientBuilder	setConcurrentConnections(int concurrentConnections) Sets the maximum number of concurrent connections the client under construction may attempt to maintain to the APNs server.
ApnsClientBuilder	setConnectionTimeout(long connectionTimeout, TimeUnit timeoutUnit) Sets the maximum amount of time, in milliseconds, that the client under construction will wait to establish a connection with the APNs server before the connection attempt is considered a failure.
ApnsClientBuilder	setEventLoopGroup(EventLoopGroup eventLoopGroup) Sets the event loop group to be used by the client under construction.
ApnsClientBuilder	setFrameLogger(Http2FrameLogger frameLogger) Sets the HTTP/2 frame logger for the client under construction.
ApnsClientBuilder	setGracefulShutdownTimeout(long gracefulShutdownTimeout, TimeUnit timeoutUnit) Sets the amount of time clients should wait for in-progress requests to complete before closing a connection during a graceful shutdown.
ApnsClientBuilder	setIdlePingInterval(long pingInterval, TimeUnit pingIntervalUnit) Sets the amount of idle time (in milliseconds) after which the client under construction will send a PING frame to the APNs server.
ApnsClientBuilder	setMetricsListener(ApnsClientMetricsListener metricsListener) Sets the metrics listener for the client under construction.
ApnsClientBuilder	setProxyHandlerFactory(ProxyHandlerFactory proxyHandlerFactory) Sets the proxy handler factory to be used to construct proxy handlers when establishing a new connection to the APNs gateway.
ApnsClientBuilder	setSigningKey(ApnsSigningKey signingKey) Sets the signing key for the client under construction.
ApnsClientBuilder	setTrustedServerCertificateChain(File certificatePemFile) Sets the trusted certificate chain for the client under construction using the contents of the given PEM file.
ApnsClientBuilder	setTrustedServerCertificateChain(InputStream certificateInputStream) Sets the trusted certificate chain for the client under construction using the contents of the given PEM input stream.
ApnsClientBuilder	setTrustedServerCertificateChain(X509Certificate... certificates) Sets the trusted certificate chain for the client under construction.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_PING_IDLE_TIME_MILLIS

public static final int DEFAULT_PING_IDLE_TIME_MILLIS

The default idle time in milliseconds after which the client will send a PING frame to the APNs server.

Since:

0.11

See Also:

Constant Field Values

PRODUCTION_APNS_HOST

public static final String PRODUCTION_APNS_HOST

The hostname for the production APNs gateway.

Since:

0.5

See Also:

Constant Field Values

DEVELOPMENT_APNS_HOST

public static final String DEVELOPMENT_APNS_HOST

The hostname for the development APNs gateway.

Since:

0.5

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.

Since:

0.5

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.

Since:

0.5

See Also:

Communicating with APNs, Constant Field Values

Constructor Detail

ApnsClientBuilder

public ApnsClientBuilder()

Method Detail

setApnsServer

public ApnsClientBuilder setApnsServer(String hostname)

Sets the hostname of the server to which the client under construction will connect. Apple provides a production and development environment.

Parameters:

hostname - the hostname of the server to which the client under construction should connect

Returns:

a reference to this builder

Since:

0.11

See Also:

DEVELOPMENT_APNS_HOST, PRODUCTION_APNS_HOST, Communicating with APNs

setApnsServer

public ApnsClientBuilder setApnsServer(String hostname,
                                       int port)

Sets the hostname and port of the server to which the client under construction will connect. Apple provides a production and development environment, both of which listen for traffic on the default HTTPS port (443) and an alternate port (2197), which callers may use to work around firewall or proxy restrictions.

Parameters:

hostname - the hostname of the server to which the client under construction should connect

port - the port to which the client under contruction should connect

Returns:

a reference to this builder

Since:

0.11

See Also:

DEVELOPMENT_APNS_HOST, PRODUCTION_APNS_HOST, DEFAULT_APNS_PORT, ALTERNATE_APNS_PORT, Communicating with APNs

setClientCredentials

public ApnsClientBuilder setClientCredentials(File p12File,
                                              String p12Password)
                                       throws SSLException,
                                              IOException

Sets the TLS credentials for the client under construction using the contents of the given PKCS#12 file. Clients constructed with TLS credentials will use TLS-based authentication when sending push notifications. The PKCS#12 file must contain a certificate/private key pair.

Clients may not have both TLS credentials and a signing key.

Parameters:

p12File - a PKCS#12-formatted file containing the certificate and private key to be used to identify the client to the APNs server

p12Password - the password to be used to decrypt the contents of the given PKCS#12 file; passwords may be blank (i.e. ""), but must not be null

Returns:

a reference to this builder

Throws:

SSLException - if the given PKCS#12 file could not be loaded or if any other SSL-related problem arises when constructing the context

IOException - if any IO problem occurred while attempting to read the given PKCS#12 file, or the PKCS#12 file could not be found

Since:

0.8

setClientCredentials

public ApnsClientBuilder setClientCredentials(InputStream p12InputStream,
                                              String p12Password)
                                       throws SSLException,
                                              IOException

Sets the TLS credentials for the client under construction using the data from the given PKCS#12 input stream. Clients constructed with TLS credentials will use TLS-based authentication when sending push notifications. The PKCS#12 data must contain a certificate/private key pair.

Clients may not have both TLS credentials and a signing key.

Parameters:

p12InputStream - an input stream to a PKCS#12-formatted file containing the certificate and private key to be used to identify the client to the APNs server

p12Password - the password to be used to decrypt the contents of the given PKCS#12 file; passwords may be blank (i.e. ""), but must not be null

Returns:

a reference to this builder

Throws:

SSLException - if the given PKCS#12 file could not be loaded or if any other SSL-related problem arises when constructing the context

IOException - if any IO problem occurred while attempting to read the given PKCS#12 input stream

Since:

0.8

setClientCredentials

public ApnsClientBuilder setClientCredentials(X509Certificate clientCertificate,
                                              PrivateKey privateKey,
                                              String privateKeyPassword)

Sets the TLS credentials for the client under construction. Clients constructed with TLS credentials will use TLS-based authentication when sending push notifications.

Clients may not have both TLS credentials and a signing key.

Parameters:

clientCertificate - 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

Returns:

a reference to this builder

Since:

0.8

setSigningKey

public ApnsClientBuilder setSigningKey(ApnsSigningKey signingKey)

Sets the signing key for the client under construction. Clients constructed with a signing key will use token-based authentication when sending push notifications.

Clients may not have both a signing key and TLS credentials.

Parameters:

signingKey - the signing key to be used by the client under construction

Returns:

a reference to this builder

Since:

0.10

See Also:

ApnsSigningKey.loadFromPkcs8File(File, String, String), ApnsSigningKey.loadFromInputStream(InputStream, String, String)

setTrustedServerCertificateChain

public ApnsClientBuilder setTrustedServerCertificateChain(File certificatePemFile)

Sets the trusted certificate chain for the client under construction using the contents of the given PEM file. If not set (or null), the client will use the JVM's default trust manager.

Callers will generally not need to set a trusted server certificate chain in normal operation, but may wish to do so for certificate pinning or connecting to a mock server for integration testing or benchmarking.

Parameters:

certificatePemFile - a PEM file containing one or more trusted certificates

Returns:

a reference to this builder

Since:

0.8

setTrustedServerCertificateChain

public ApnsClientBuilder setTrustedServerCertificateChain(InputStream certificateInputStream)

Sets the trusted certificate chain for the client under construction using the contents of the given PEM input stream. If not set (or null), the client will use the JVM's default trust manager.

Callers will generally not need to set a trusted server certificate chain in normal operation, but may wish to do so for certificate pinning or connecting to a mock server for integration testing or benchmarking.

Parameters:

certificateInputStream - an input stream to PEM-formatted data containing one or more trusted certificates

Returns:

a reference to this builder

Since:

0.8

setTrustedServerCertificateChain

public ApnsClientBuilder setTrustedServerCertificateChain(X509Certificate... certificates)

Sets the trusted certificate chain for the client under construction. If not set (or null), the client will use the JVM's default trust manager.

Callers will generally not need to set a trusted server certificate chain in normal operation, but may wish to do so for certificate pinning or connecting to a mock server for integration testing or benchmarking.

Parameters:

certificates - one or more trusted certificates

Returns:

a reference to this builder

Since:

0.8

setEventLoopGroup

public ApnsClientBuilder setEventLoopGroup(EventLoopGroup eventLoopGroup)

Sets the event loop group to be used by the client under construction. If not set (or if null), the client will create and manage its own event loop group.

Generally speaking, callers don't need to set event loop groups for clients, but it may be useful to specify an event loop group under certain circumstances. In particular, specifying an event loop group that is shared among multiple ApnsClient instances can keep thread counts manageable. Regardless of the number of concurrent ApnsClient instances, callers may also wish to specify an event loop group to take advantage of certain platform-specific optimizations (e.g. epoll or KQueue event loop groups).

Parameters:

eventLoopGroup - the event loop group to use for this client, or null to let the client manage its own event loop group

Returns:

a reference to this builder

Since:

0.8

setConcurrentConnections

public ApnsClientBuilder setConcurrentConnections(int concurrentConnections)

Sets the maximum number of concurrent connections the client under construction may attempt to maintain to the APNs server. By default, clients will attempt to maintain a single connection to the APNs server.

Parameters:

concurrentConnections - the maximum number of concurrent connections the client under construction may attempt to maintain

Returns:

a reference to this builder

Since:

0.11

setMetricsListener

public ApnsClientBuilder setMetricsListener(ApnsClientMetricsListener metricsListener)

Sets the metrics listener for the client under construction. Metrics listeners gather information that describes the performance and behavior of a client, and are completely optional.

Parameters:

metricsListener - the metrics listener for the client under construction, or null if this client should not report metrics to a listener

Returns:

a reference to this builder

Since:

0.8

setProxyHandlerFactory

public ApnsClientBuilder setProxyHandlerFactory(ProxyHandlerFactory proxyHandlerFactory)

Sets the proxy handler factory to be used to construct proxy handlers when establishing a new connection to the APNs gateway. 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

Returns:

a reference to this builder

Since:

0.8

setConnectionTimeout

public ApnsClientBuilder setConnectionTimeout(long connectionTimeout,
                                              TimeUnit timeoutUnit)

Sets the maximum amount of time, in milliseconds, that the client under construction will wait to establish a connection with the APNs server before the connection attempt is considered a failure.

Parameters:

connectionTimeout - the maximum amount of time to wait for a connection attempt to complete

timeoutUnit - the time unit for the given timeout

Returns:

a reference to this builder

Since:

0.8

setIdlePingInterval

public ApnsClientBuilder setIdlePingInterval(long pingInterval,
                                             TimeUnit pingIntervalUnit)

Sets the amount of idle time (in milliseconds) after which the client under construction will send a PING frame to the APNs server. By default, clients will send a PING frame after 60000 milliseconds of inactivity.

Parameters:

pingInterval - the amount of idle time after which the client will send a PING frame

pingIntervalUnit - the time unit for the given idle time

Returns:

a reference to this builder

Since:

0.10

setGracefulShutdownTimeout

public ApnsClientBuilder setGracefulShutdownTimeout(long gracefulShutdownTimeout,
                                                    TimeUnit timeoutUnit)

Sets the amount of time clients should wait for in-progress requests to complete before closing a connection during a graceful shutdown.

Parameters:

gracefulShutdownTimeout - the amount of time to wait for in-progress requests to complete before closing a connection

timeoutUnit - the time unit for the given timeout

Returns:

a reference to this builder

Since:

0.8

See Also:

ApnsClient.close()

setFrameLogger

public ApnsClientBuilder setFrameLogger(Http2FrameLogger frameLogger)

Sets the HTTP/2 frame logger for the client under construction. HTTP/2 frame loggers log all HTTP/2 frames sent to or from the client to the logging system of your choice via SLF4J. Frame logging is extremely verbose and is recommended only for debugging purposes.

Parameters:

frameLogger - the frame logger to be used by the client under construction or null if the client should not log individual HTTP/2 frames

Returns:

a reference to this builder

Since:

0.12

See Also:

SLF4J

build

public ApnsClient build()
                 throws SSLException

Constructs a new ApnsClient with the previously-set configuration.

Returns:

a new ApnsClient instance with the previously-set configuration

Throws:

SSLException - if an SSL context could not be created for the new client for any reason

IllegalStateException - if this method is called without specifying an APNs server address, if this method is called without providing TLS credentials or a signing key, or if this method is called with both TLS credentials and a signing key

Since:

0.8