com.notnoop.apns
Class ApnsServiceBuilder

java.lang.Object
  com.notnoop.apns.ApnsServiceBuilder

public class ApnsServiceBuilder
extends Object

The class is used to create instances of ApnsService. Note that this class is not synchronized. If multiple threads access a ApnsServiceBuilder instance concurrently, and at least on of the threads modifies one of the attributes structurally, it must be synchronized externally. Starting a new ApnsService is easy:

   ApnsService = APNS.newService()
    .withCert("/path/to/certificate.p12", "MyCertPassword")
    .withSandboxDestination()
    .build()
 

Constructor Summary

ApnsServiceBuilder()
Constructs a new instance of ApnsServiceBuilder

Method Summary

ApnsServiceBuilder	asBatched() Construct service which will process notification requests in batch.
ApnsServiceBuilder	asBatched(int waitTimeInSec, int maxWaitTimeInSec) Construct service which will process notification requests in batch.
ApnsServiceBuilder	asBatched(int waitTimeInSec, int maxWaitTimeInSec, ThreadFactory threadFactory) Construct service which will process notification requests in batch.
ApnsServiceBuilder	asPool(ExecutorService executor, int maxConnections) Constructs a pool of connections to the notification servers.
ApnsServiceBuilder	asPool(int maxConnections) Constructs a pool of connections to the notification servers.
ApnsServiceBuilder	asQueued() Constructs a new thread with a processing queue to process notification requests.
ApnsService	build() Returns a fully initialized instance of ApnsService, according to the requested settings.
ApnsServiceBuilder	withAppleDestination(boolean isProduction) Specify to use Apple servers as iPhone gateway and feedback servers.
ApnsServiceBuilder	withAutoAdjustCacheLength(boolean autoAdjustCacheLength) Specify if the notification cache should auto adjust.
ApnsServiceBuilder	withCacheLength(int cacheLength) Specity the number of notifications to cache for error purposes.
ApnsServiceBuilder	withCert(InputStream stream, String password) Specify the certificate used to connect to Apple APNS servers.
ApnsServiceBuilder	withCert(KeyStore keyStore, String password) Specify the certificate used to connect to Apple APNS servers.
ApnsServiceBuilder	withCert(String fileName, String password) Specify the certificate used to connect to Apple APNS servers.
ApnsServiceBuilder	withDelegate(ApnsDelegate delegate) Sets the delegate of the service, that gets notified of the status of message delivery.
ApnsServiceBuilder	withFeedbackDestination(String host, int port) Specify the Feedback for getting failed devices from Apple iPhone Push servers.
ApnsServiceBuilder	withGatewayDestination(String host, int port) Specify the gateway server for sending Apple iPhone notifications.
ApnsServiceBuilder	withNoErrorDetection() Disables the enhanced error detection, enabled by the enhanced push notification interface.
ApnsServiceBuilder	withProductionDestination() Specify to use the Apple Production servers as iPhone gateway and feedback servers.
ApnsServiceBuilder	withProxy(Proxy proxy) Specify the proxy to be used to establish the connections to Apple Servers Read the Java Networking and Proxies guide to understand the proxies complexity.
ApnsServiceBuilder	withProxySocket(Socket proxySocket) Deprecated. use withProxy(Proxy) instead
ApnsServiceBuilder	withReconnectPolicy(ReconnectPolicy.Provided rp) Specify the reconnection policy for the socket connection.
ApnsServiceBuilder	withReconnectPolicy(ReconnectPolicy rp) Specify the reconnection policy for the socket connection.
ApnsServiceBuilder	withSandboxDestination() Specify to use the Apple sandbox servers as iPhone gateway and feedback servers.
ApnsServiceBuilder	withSocksProxy(String host, int port) Specify the address of the SOCKS proxy the connection should use.
ApnsServiceBuilder	withSSLContext(SSLContext sslContext) Specify the SSLContext that should be used to initiate the connection to Apple Server.

Methods inherited from class java.lang.Object

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

Constructor Detail

ApnsServiceBuilder

public ApnsServiceBuilder()

Constructs a new instance of ApnsServiceBuilder

Method Detail

withCert

public ApnsServiceBuilder withCert(String fileName,
                                   String password)
                            throws RuntimeIOException,
                                   InvalidSSLConfig

Specify the certificate used to connect to Apple APNS servers. This relies on the path (absolute or relative to working path) to the keystore (*.p12) containing the certificate, along with the given password. The keystore needs to be of PKCS12 and the keystore needs to be encrypted using the SunX509 algorithm. Both of these settings are the default. This library does not support password-less p12 certificates, due to a Oracle Java library Bug 6415637. There are three workarounds: use a password-protected certificate, use a different boot Java SDK implementation, or constract the `SSLContext` yourself! Needless to say, the password-protected certificate is most recommended option.

Parameters:

fileName - the path to the certificate

password - the password of the keystore

Returns:

this

Throws:

RuntimeIOException - if it fileName cannot be found or read

InvalidSSLConfig - if fileName is invalid Keystore or the password is invalid

withCert

public ApnsServiceBuilder withCert(InputStream stream,
                                   String password)
                            throws InvalidSSLConfig

Specify the certificate used to connect to Apple APNS servers. This relies on the stream of keystore (*.p12) containing the certificate, along with the given password. The keystore needs to be of PKCS12 and the keystore needs to be encrypted using the SunX509 algorithm. Both of these settings are the default. This library does not support password-less p12 certificates, due to a Oracle Java library Bug 6415637. There are three workarounds: use a password-protected certificate, use a different boot Java SDK implementation, or constract the `SSLContext` yourself! Needless to say, the password-protected certificate is most recommended option.

Parameters:

stream - the keystore represented as input stream

password - the password of the keystore

Returns:

this

Throws:

InvalidSSLConfig - if stream is invalid Keystore or the password is invalid

withCert

public ApnsServiceBuilder withCert(KeyStore keyStore,
                                   String password)
                            throws InvalidSSLConfig

Specify the certificate used to connect to Apple APNS servers. This relies on a keystore (*.p12) containing the certificate, along with the given password. This library does not support password-less p12 certificates, due to a Oracle Java library Bug 6415637. There are three workarounds: use a password-protected certificate, use a different boot Java SDK implementation, or constract the `SSLContext` yourself! Needless to say, the password-protected certificate is most recommended option.

Parameters:

stream - the keystore

password - the password of the keystore

Returns:

this

Throws:

InvalidSSLConfig - if stream is invalid Keystore or the password is invalid

withSSLContext

public ApnsServiceBuilder withSSLContext(SSLContext sslContext)

Specify the SSLContext that should be used to initiate the connection to Apple Server. Most clients would use withCert(InputStream, String) or withCert(String, String) instead. But some clients may need to represent the Keystore in a different format than supported.

Parameters:

sslContext - Context to be used to create secure connections

Returns:

this

withGatewayDestination

public ApnsServiceBuilder withGatewayDestination(String host,
                                                 int port)

Specify the gateway server for sending Apple iPhone notifications. Most clients should use withSandboxDestination() or withProductionDestination(). Clients may use this method to connect to mocking tests and such.

Parameters:

host - hostname the notification gateway of Apple

port - port of the notification gateway of Apple

Returns:

this

withFeedbackDestination

public ApnsServiceBuilder withFeedbackDestination(String host,
                                                  int port)

Specify the Feedback for getting failed devices from Apple iPhone Push servers. Most clients should use withSandboxDestination() or withProductionDestination(). Clients may use this method to connect to mocking tests and such.

Parameters:

host - hostname of the feedback server of Apple

port - port of the feedback server of Apple

Returns:

this

withAppleDestination

public ApnsServiceBuilder withAppleDestination(boolean isProduction)

Specify to use Apple servers as iPhone gateway and feedback servers. If the passed isProduction is true, then it connects to the production servers, otherwise, it connects to the sandbox servers

Parameters:

isProduction - determines which Apple servers should be used: production or sandbox

Returns:

this

withSandboxDestination

public ApnsServiceBuilder withSandboxDestination()

Specify to use the Apple sandbox servers as iPhone gateway and feedback servers. This is desired when in testing and pushing notifications with a development provision.

Returns:

this

withProductionDestination

public ApnsServiceBuilder withProductionDestination()

Specify to use the Apple Production servers as iPhone gateway and feedback servers. This is desired when sending notifications to devices with a production provision (whether through App Store or Ad hoc distribution).

Returns:

this

withReconnectPolicy

public ApnsServiceBuilder withReconnectPolicy(ReconnectPolicy rp)

Specify the reconnection policy for the socket connection. Note: This option has no effect when using non-blocking connections.

withAutoAdjustCacheLength

public ApnsServiceBuilder withAutoAdjustCacheLength(boolean autoAdjustCacheLength)

Specify if the notification cache should auto adjust. Default is true

Parameters:

autoAdjustCacheLength -

Returns:

this

withReconnectPolicy

public ApnsServiceBuilder withReconnectPolicy(ReconnectPolicy.Provided rp)

Specify the reconnection policy for the socket connection. Note: This option has no effect when using non-blocking connections.

withSocksProxy

public ApnsServiceBuilder withSocksProxy(String host,
                                         int port)

Specify the address of the SOCKS proxy the connection should use.

Read the Java Networking and Proxies guide to understand the proxies complexity.

Be aware that this method only handles SOCKS proxies, not HTTPS proxies. Use withProxy(Proxy) instead.

Parameters:

host - the hostname of the SOCKS proxy

port - the port of the SOCKS proxy server

Returns:

this

withProxy

public ApnsServiceBuilder withProxy(Proxy proxy)

Specify the proxy to be used to establish the connections to Apple Servers

Read the Java Networking and Proxies guide to understand the proxies complexity.

Parameters:

proxy - the proxy object to be used to create connections

Returns:

this

withCacheLength

public ApnsServiceBuilder withCacheLength(int cacheLength)

Specity the number of notifications to cache for error purposes. Default is 100

Parameters:

cacheLength - Number of notifications to cache for error purposes

Returns:

this

withProxySocket

@Deprecated
public ApnsServiceBuilder withProxySocket(Socket proxySocket)

Deprecated. use withProxy(Proxy) instead

Specify the socket to be used as underlying socket to connect to the APN service. This assumes that the socket connects to a SOCKS proxy.

Parameters:

proxySocket - the underlying socket for connections

Returns:

this

asPool

public ApnsServiceBuilder asPool(int maxConnections)

Constructs a pool of connections to the notification servers. Apple servers recommend using a pooled connection up to 15 concurrent persistent connections to the gateways. Note: This option has no effect when using non-blocking connections.

asPool

public ApnsServiceBuilder asPool(ExecutorService executor,
                                 int maxConnections)

Constructs a pool of connections to the notification servers. Apple servers recommend using a pooled connection up to 15 concurrent persistent connections to the gateways. Note: This option has no effect when using non-blocking connections. Note: The maxConnections here is used as a hint to how many connections get created.

asQueued

public ApnsServiceBuilder asQueued()

Constructs a new thread with a processing queue to process notification requests.

Returns:

this

asBatched

public ApnsServiceBuilder asBatched()

Construct service which will process notification requests in batch. After each request batch will wait waitTimeInSec (set as 5sec) for more request to come before executing but not more than maxWaitTimeInSec (set as 10sec) Note: It is not recommended to use pooled connection

asBatched

public ApnsServiceBuilder asBatched(int waitTimeInSec,
                                    int maxWaitTimeInSec)

Construct service which will process notification requests in batch. After each request batch will wait waitTimeInSec for more request to come before executing but not more than maxWaitTimeInSec Note: It is not recommended to use pooled connection

Parameters:

waitTimeInSec - time to wait for more notification request before executing batch

maxWaitTimeInSec - maximum wait time for batch before executing

asBatched

public ApnsServiceBuilder asBatched(int waitTimeInSec,
                                    int maxWaitTimeInSec,
                                    ThreadFactory threadFactory)

Construct service which will process notification requests in batch. After each request batch will wait waitTimeInSec for more request to come before executing but not more than maxWaitTimeInSec> Each batch creates new connection and close it after finished. In case reconnect policy is specified it will be applied by batch processing. E.g.: ReconnectPolicy.Provided.EVERY_HALF_HOUR will reconnect the connection in case batch is running for more than half an hour Note: It is not recommended to use pooled connection

Parameters:

waitTimeInSec - time to wait for more notification request before executing batch

maxWaitTimeInSec - maximum wait time for batch before executing

threadFactory - thread factory to use for batch processing

withDelegate

public ApnsServiceBuilder withDelegate(ApnsDelegate delegate)

Sets the delegate of the service, that gets notified of the status of message delivery. Note: This option has no effect when using non-blocking connections.

withNoErrorDetection

public ApnsServiceBuilder withNoErrorDetection()

Disables the enhanced error detection, enabled by the enhanced push notification interface. Error detection is enabled by default. This setting is desired when the application shouldn't spawn new threads.

Returns:

this

build

public ApnsService build()

Returns a fully initialized instance of ApnsService, according to the requested settings.

Returns:

a new instance of ApnsService