ApnsClientBuilder (Pushy 0.9 API)

java.lang.Object
- com.relayrides.pushy.apns.ApnsClientBuilder

```
public class ApnsClientBuilder
extends Object
```
An ApnsClientBuilder constructs new ApnsClient instances. All settings are optional. Callers must provide a certificate and private key via one of the setClientCredentials methods in order to use TLS-based client authentication; if client credentials are not specified, the constructed client will use token-based authentication, and callers will need to register signing keys directly with the client after construction.

Client builders may be reused to generate multiple clients, and their settings may be changed from one client to the next.

Author:

Jon Chambers

Constructor Summary

Constructors
Constructor and Description

ApnsClientBuilder()

Constructors
Constructor and Description
`ApnsClientBuilder()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ApnsClient`	`build()` Constructs a new `ApnsClient` with the previously-set configuration.
`ApnsClientBuilder`	`setChannelWriteBufferWatermark(WriteBufferWaterMark writeBufferWatermark)` Sets the buffer usage watermark range for the client to build.
`ApnsClientBuilder`	`setClientCredentials(File p12File, String p12Password)` Sets the credentials for the client under construction using the contents of the given PKCS#12 file.
`ApnsClientBuilder`	`setClientCredentials(InputStream p12InputStream, String p12Password)` Sets the 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 credentials for the client under construction.
`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`	`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`	`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`	`setSslProvider(SslProvider sslProvider)` Sets the SSL provider to be used by 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.
`ApnsClientBuilder`	`setWriteTimeout(long writeTimeout, TimeUnit timeoutUnit)` Sets the write timeout for the client to build.

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

- Constructor Detail
  - ApnsClientBuilder
```
public ApnsClientBuilder()
```
- Method Detail
  - setClientCredentials
```
public ApnsClientBuilder setClientCredentials(File p12File,
                                              String p12Password)
                                       throws SSLException,
                                              IOException
```
    Sets the credentials for the client under construction using the contents of the given PKCS#12 file. The PKCS#12 file must contain a certificate/private key pair.
    
    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 credentials for the client under construction using the data from the given PKCS#12 input stream. The PKCS#12 data must contain a certificate/private key pair.
    
    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 credentials for the client under construction.
    
    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
  - 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
  - setSslProvider
```
public ApnsClientBuilder setSslProvider(SslProvider sslProvider)
```
    Sets the SSL provider to be used by the client under construction. By default, the client will use a native SSL provider if available and fall back to the JDK provider otherwise.
    
    Parameters:
    
    sslProvider - the SSL provider to be used by the client under construction, or null to choose a provider automatically
    
    Returns:
    
    a reference to this builder
    
    Since:
    
    0.9
  - 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 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
  - 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
  - setWriteTimeout
```
public ApnsClientBuilder setWriteTimeout(long writeTimeout,
                                         TimeUnit timeoutUnit)
```
    Sets the write timeout for the client to build. 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.
    
    By default, clients have a write timeout of 20000L milliseconds.
    
    Parameters:
    
    writeTimeout - the write timeout for the client under construction
    
    timeoutUnit - the time unit for the given timeout
    
    Returns:
    
    a reference to this builder
    
    Since:
    
    0.8
  - 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.disconnect()
  - setChannelWriteBufferWatermark
```
public ApnsClientBuilder setChannelWriteBufferWatermark(WriteBufferWaterMark writeBufferWatermark)
```
    Sets the buffer usage watermark range for the client to build. When a the amount of buffered and not-yet-flushed data in a client's network channel exceeds the given "high-water" mark, the channel will begin rejecting new data until enough data has been flushed to cross the given "low-water" mark. Notifications sent when the client's network channel is "flooded" will fail with a ClientBusyException.
    
    By default, the high-water mark is 64kB, and the low-water mark is 32kB.
    
    Parameters:
    
    writeBufferWatermark - the buffer usage watermark range for the client's network channel
    
    Returns:
    
    a reference to this builder
    
    Since:
    
    0.8.2
  - 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
    
    Since:
    
    0.8

Class ApnsClientBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ApnsClientBuilder

Method Detail

setClientCredentials

setClientCredentials

setClientCredentials

setTrustedServerCertificateChain

setTrustedServerCertificateChain

setTrustedServerCertificateChain

setSslProvider

setEventLoopGroup

setMetricsListener

setProxyHandlerFactory

setConnectionTimeout

setWriteTimeout

setGracefulShutdownTimeout

setChannelWriteBufferWatermark

build