From 5a2ef5f6fa498e2364383ecdab876f69ae09d43a Mon Sep 17 00:00:00 2001 From: Jon Chambers Date: Sat, 9 May 2020 15:50:16 -0400 Subject: [PATCH] Update READMEs and doc links in preparation for 0.14.0. --- README.md | 20 ++++++++++---------- dropwizard-metrics-listener/README.md | 4 ++-- micrometer-metrics-listener/README.md | 4 ++-- micrometer-metrics-listener/pom.xml | 3 +-- 4 files changed, 15 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 7b5d3612b..d5f03b912 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Pushy is a Java library for sending [APNs](https://developer.apple.com/documentation/usernotifications) (iOS, macOS, and Safari) push notifications. -Pushy sends push notifications using Apple's HTTP/2-based APNs protocol and supports both TLS and token-based authentication. It distinguishes itself from other push notification libraries with a focus on [thorough documentation](https://pushy-apns.org/apidocs/0.13/index.html?overview-summary.html), asynchronous operation, and design for industrial-scale operation; with Pushy, it's easy and efficient to maintain multiple parallel connections to the APNs gateway to send large numbers of notifications to many different applications ("topics"). +Pushy sends push notifications using Apple's HTTP/2-based APNs protocol and supports both TLS and token-based authentication. It distinguishes itself from other push notification libraries with a focus on [thorough documentation](https://pushy-apns.org/apidocs/0.14/index.html?overview-summary.html), asynchronous operation, and design for industrial-scale operation; with Pushy, it's easy and efficient to maintain multiple parallel connections to the APNs gateway to send large numbers of notifications to many different applications ("topics"). We believe that Pushy is already the best tool for sending APNs push notifications from Java applications, and we hope you'll help us make it even better via bug reports and pull requests. If you have questions about using Pushy, please join us on [the Pushy mailing list](https://groups.google.com/d/forum/pushy-apns) or take a look at [the wiki](https://github.com/jchambers/pushy/wiki). Thanks! @@ -19,11 +19,11 @@ If you use [Maven](http://maven.apache.org/), you can add Pushy to your project com.eatthepath pushy - 0.13.11 + 0.14.0 ``` -If you don't use Maven (or something else that understands Maven dependencies, like Gradle), you can [download Pushy as a `.jar` file](https://github.com/jchambers/pushy/releases/download/pushy-0.13.11/pushy-0.13.11.jar) and add it to your project directly. You'll also need to make sure you have Pushy's runtime dependencies on your classpath. They are: +If you don't use Maven (or something else that understands Maven dependencies, like Gradle), you can [download Pushy as a `.jar` file](https://github.com/jchambers/pushy/releases/download/pushy-0.14.0/pushy-0.14.0.jar) and add it to your project directly. You'll also need to make sure you have Pushy's runtime dependencies on your classpath. They are: - [netty 4.1.48](http://netty.io/) - [gson 2.6](https://github.com/google/gson) @@ -51,7 +51,7 @@ Generally speaking, APNs clients must authenticate with the APNs server by some In TLS-based authentication, clients present a TLS certificate to the server when connecting, and may send notifications to any "topic" named in the certificate. Generally, this means that a single client can only send push notifications to a single receiving app. -Once you've registered your app and have the requisite certificates, the first thing you'll need to do to start sending push notifications with Pushy is to create an [`ApnsClient`](https://pushy-apns.org/apidocs/0.13/com/eatthepath/pushy/apns/ApnsClient.html). Clients using TLS authentication need a certificate and private key to authenticate with the APNs server. The most common way to store the certificate and key is in a password-protected PKCS#12 file (you'll wind up with a password-protected .p12 file if you follow Apple's instructions at the time of this writing). To create a client that will use TLS-based authentication: +Once you've registered your app and have the requisite certificates, the first thing you'll need to do to start sending push notifications with Pushy is to create an [`ApnsClient`](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/ApnsClient.html). Clients using TLS authentication need a certificate and private key to authenticate with the APNs server. The most common way to store the certificate and key is in a password-protected PKCS#12 file (you'll wind up with a password-protected .p12 file if you follow Apple's instructions at the time of this writing). To create a client that will use TLS-based authentication: ```java final ApnsClient apnsClient = new ApnsClientBuilder() @@ -76,7 +76,7 @@ final ApnsClient apnsClient = new ApnsClientBuilder() ## Sending push notifications -Pushy's APNs clients maintain an internal pool of connections to the APNs server and create new connections on demand. As a result, clients do not need to be started explicitly. Regardless of the authentication method you choose, once you've created a client, it's ready to start sending push notifications. At minimum, [push notifications](https://pushy-apns.org/apidocs/0.13/com/eatthepath/pushy/apns/ApnsPushNotification.html) need a device token (which identifies the notification's destination device and is a distinct idea from an authentication token), a topic, and a payload. +Pushy's APNs clients maintain an internal pool of connections to the APNs server and create new connections on demand. As a result, clients do not need to be started explicitly. Regardless of the authentication method you choose, once you've created a client, it's ready to start sending push notifications. At minimum, [push notifications](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/ApnsPushNotification.html) need a device token (which identifies the notification's destination device and is a distinct idea from an authentication token), a topic, and a payload. ```java final SimpleApnsPushNotification pushNotification; @@ -94,7 +94,7 @@ final SimpleApnsPushNotification pushNotification; Pushy includes a [`SimpleApnsPayloadBuilder`](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/util/SimpleApnsPayloadBuilder.html), and payload builders based on [Gson](https://github.com/jchambers/pushy/tree/master/gson-payload-builder) and [Jackson](https://github.com/jchambers/pushy/tree/master/jackson-payload-builder) are available as separate modules. [APNs payloads are just JSON strings](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification), and callers may produce payloads by the method of their choice; while Pushy's payload builders may be convenient, callers are _not_ obligated to use them. -The process of sending a push notification is asynchronous; although the process of sending a notification and getting a reply from the server may take some time, the client will return a [`CompletableFuture`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) right away. You can use that `CompletableFuture` to track the progress and eventual outcome of the sending operation. Note that sending a notification returns a [`PushNotificationFuture`](https://pushy-apns.org/apidocs/0.13/com/eatthepath/pushy/apns/util/concurrent/PushNotificationFuture.html), which is a subclass of `CompletableFuture` that always holds a reference to the notification that was sent. +The process of sending a push notification is asynchronous; although the process of sending a notification and getting a reply from the server may take some time, the client will return a [`CompletableFuture`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) right away. You can use that `CompletableFuture` to track the progress and eventual outcome of the sending operation. Note that sending a notification returns a [`PushNotificationFuture`](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/util/concurrent/PushNotificationFuture.html), which is a subclass of `CompletableFuture` that always holds a reference to the notification that was sent. ```java final PushNotificationFuture> @@ -185,7 +185,7 @@ Please note that the metric-handling methods in your listener implementation sho ## Using a proxy -If you need to use a proxy for outbound connections, you may specify a [`ProxyHandlerFactory`](https://pushy-apns.org/apidocs/0.13/com/eatthepath/pushy/apns/proxy/ProxyHandlerFactory.html) when building your `ApnsClient` instance. Concrete implementations of `ProxyHandlerFactory` are provided for HTTP, SOCKS4, and SOCKS5 proxies. +If you need to use a proxy for outbound connections, you may specify a [`ProxyHandlerFactory`](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/proxy/ProxyHandlerFactory.html) when building your `ApnsClient` instance. Concrete implementations of `ProxyHandlerFactory` are provided for HTTP, SOCKS4, and SOCKS5 proxies. An example: @@ -237,12 +237,12 @@ Pushy uses logging levels as follows: Pushy includes a mock APNs server that callers may use in integration tests and benchmarks. It is not necessary to use a mock server (or any related classes) in normal operation. -To build a mock server, callers should use a [`MockApnsServerBuilder`](https://pushy-apns.org/apidocs/0.13/com/eatthepath/pushy/apns/server/MockApnsServerBuilder.html). All servers require a [`PushNotificationHandler`](https://pushy-apns.org/apidocs/0.13/com/eatthepath/pushy/apns/server/PushNotificationHandler.html) (built by a [`PushNotificationHandlerFactory`](https://pushy-apns.org/apidocs/0.13/com/eatthepath/pushy/apns/server/PushNotificationHandlerFactory.html) provided to the builder) that decides whether the mock server will accept or reject each incoming push notification. Pushy includes an `AcceptAllPushNotificationHandlerFactory` that is helpful for benchmarking and a `ValidatingPushNotificationHandlerFactory` that may be helpful for integration testing. +To build a mock server, callers should use a [`MockApnsServerBuilder`](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/server/MockApnsServerBuilder.html). All servers require a [`PushNotificationHandler`](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/server/PushNotificationHandler.html) (built by a [`PushNotificationHandlerFactory`](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/server/PushNotificationHandlerFactory.html) provided to the builder) that decides whether the mock server will accept or reject each incoming push notification. Pushy includes an `AcceptAllPushNotificationHandlerFactory` that is helpful for benchmarking and a `ValidatingPushNotificationHandlerFactory` that may be helpful for integration testing. -Callers may also provide a [`MockApnsServerListener`](https://pushy-apns.org/apidocs/0.13/com/eatthepath/pushy/apns/server/MockApnsServerListener.html) when building a mock server; listeners are notified whenever the mock server accepts or rejects a notification from a client. +Callers may also provide a [`MockApnsServerListener`](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/server/MockApnsServerListener.html) when building a mock server; listeners are notified whenever the mock server accepts or rejects a notification from a client. ## License and status Pushy is available under the [MIT License](https://github.com/jchambers/pushy/blob/master/LICENSE.md). -The current version of Pushy is 0.13.11. It's fully functional and widely used in production environments, but the public API may change significantly before a 1.0 release. +The current version of Pushy is 0.14.0. It's fully functional and widely used in production environments, but the public API may change significantly before a 1.0 release. diff --git a/dropwizard-metrics-listener/README.md b/dropwizard-metrics-listener/README.md index a37ad922b..b5050a936 100644 --- a/dropwizard-metrics-listener/README.md +++ b/dropwizard-metrics-listener/README.md @@ -1,12 +1,12 @@ # Dropwizard Metrics listener for Pushy -This module is an implementation of Pushy's [`ApnsClientMetricsListener`](https://pushy-apns.org/apidocs/0.13/com/eatthepath/pushy/apns/ApnsClientMetricsListener.html) interface that uses the [Dropwizard Metrics library](http://metrics.dropwizard.io/) to gather and report metrics. If you use [Maven](http://maven.apache.org/), you can add the listener to your project by adding the following dependency declaration to your POM: +This module is an implementation of Pushy's [`ApnsClientMetricsListener`](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/ApnsClientMetricsListener.html) interface that uses the [Dropwizard Metrics library](http://metrics.dropwizard.io/) to gather and report metrics. If you use [Maven](http://maven.apache.org/), you can add the listener to your project by adding the following dependency declaration to your POM: ```xml com.eatthepath pushy-dropwizard-metrics-listener - 0.13.11 + 0.14.0 ``` diff --git a/micrometer-metrics-listener/README.md b/micrometer-metrics-listener/README.md index 90f316ab9..0818d6a99 100644 --- a/micrometer-metrics-listener/README.md +++ b/micrometer-metrics-listener/README.md @@ -1,12 +1,12 @@ # Micrometer Metrics listener for Pushy -This module is an implementation of Pushy's [`ApnsClientMetricsListener`](https://pushy-apns.org/apidocs/0.13/com/eatthepath/pushy/apns/ApnsClientMetricsListener.html) interface that uses the [Micrometer application monitoring library](http://micrometer.io/) to gather and report metrics. If you use [Maven](http://maven.apache.org/), you can add the listener to your project by adding the following dependency declaration to your POM: +This module is an implementation of Pushy's [`ApnsClientMetricsListener`](https://pushy-apns.org/apidocs/0.14/com/eatthepath/pushy/apns/ApnsClientMetricsListener.html) interface that uses the [Micrometer application monitoring library](http://micrometer.io/) to gather and report metrics. If you use [Maven](http://maven.apache.org/), you can add the listener to your project by adding the following dependency declaration to your POM: ```xml com.eatthepath pushy-micrometer-metrics-listener - 0.13.11 + 0.14.0 ``` diff --git a/micrometer-metrics-listener/pom.xml b/micrometer-metrics-listener/pom.xml index 4e7b36a8e..1096d50e3 100644 --- a/micrometer-metrics-listener/pom.xml +++ b/micrometer-metrics-listener/pom.xml @@ -61,7 +61,7 @@ ${basedir}/src/main/java/overview.html public - https://pushy-apns.org/apidocs/0.12/ + https://pushy-apns.org/apidocs/0.14/ @@ -74,7 +74,6 @@ 1.8 -