nl.meandi.apns.example:apns-example-notifier

JCA Connector for Apple Push Notification Service

License

License

GroupId

GroupId

nl.meandi.apns.example
ArtifactId

ArtifactId

apns-example-notifier
Last Version

Last Version

0.20
Release Date

Release Date

Type

Type

war
Description

Description

nl.meandi.apns.example:apns-example-notifier
JCA Connector for Apple Push Notification Service
Project URL

Project URL

https://github.com/marcelk/apns

Download apns-example-notifier

How to add to project

<!-- https://jarcasting.com/artifacts/nl.meandi.apns.example/apns-example-notifier/ -->
<dependency>
    <groupId>nl.meandi.apns.example</groupId>
    <artifactId>apns-example-notifier</artifactId>
    <version>0.20</version>
    <type>war</type>
</dependency>
// https://jarcasting.com/artifacts/nl.meandi.apns.example/apns-example-notifier/
implementation 'nl.meandi.apns.example:apns-example-notifier:0.20'
// https://jarcasting.com/artifacts/nl.meandi.apns.example/apns-example-notifier/
implementation ("nl.meandi.apns.example:apns-example-notifier:0.20")
'nl.meandi.apns.example:apns-example-notifier:war:0.20'
<dependency org="nl.meandi.apns.example" name="apns-example-notifier" rev="0.20">
  <artifact name="apns-example-notifier" type="war" />
</dependency>
@Grapes(
@Grab(group='nl.meandi.apns.example', module='apns-example-notifier', version='0.20')
)
libraryDependencies += "nl.meandi.apns.example" % "apns-example-notifier" % "0.20"
[nl.meandi.apns.example/apns-example-notifier "0.20"]

Dependencies

compile (1)

Group / Artifact Type Version
nl.meandi.apns : apns-adapter jar 0.20

provided (2)

Group / Artifact Type Version
org.jboss.ejb3 : jboss-ejb3-ext-api jar 2.1.0
javax : javaee-api jar 7.0

Project Modules

There are no modules declared in this project.

JCA Connector for the Apple Push Notification Service

This adapter can be plugged into a Java EE application server, so that applications can send push messages to iOS, Apple Watch and OS X devices. It has been written for Java EE 7 compliant application servers running on Java 8.

Usage

The adapter artifacts are available in Maven Central. Add this dependency to your project:

<dependency>
    <groupId>nl.meandi.apns.adapter</groupId>
    <artifactId>apns-adapter</artifactId>
    <version>0.18</version>
    <scope>provided</scope>
</dependency>

In order to send a push notification message to your app, inject the APNS resource in your Java EE component:

@Resource(lookup = "java:/eis/apns-connector")
private PushNotificationConnectionFactory connectionFactory;

Sending the message goes like this:

try (PushNotificationConnection conn = connectionFactory.getConnection()) {
    byte[] deviceTokenBytes = /* array with 32 bytes */;
    byte[] payload = /* payload in JSON format */;
    int notificationIdentifier = /* unique identification of this push notification */;
    Instant expirationDate = /* date/time indicating when the message expires */;
    NotificationPriority priority = /* TIME (deliver as soon as possible) or ENERGY (minimize power consumption) */;

    conn.sendNotification(deviceTokenBytes, payload, notificationIdentifier, expirationDate, priority);
} catch (Exception e) {
    throw new RuntimeException(e);
}

In addition, it is required to declare a message driven bean for processing feedback information from Apple:

@MessageDriven
public class MessageDrivenBean implements ApnsListener {
    ...
}

The feedback is about devices that failed to consume push notifications. The application should cease the notifications for those devices. The message driven bean should implement the handleDeviceRemoval method of the ApnsListener interface:

@Override
public void handleDeviceRemoval(Instant timestamp, byte[] deviceId) {
    /* Remove notification subscriptions for the device identified by deviceId. */;
}

Configuration and Deployment

The resource adapter rar file can be downloaded from Maven Central:

http://repo1.maven.org/maven2/nl/meandi/apns/apns-rar/0.18/apns-rar-0.18.rar

It depends on the Java EE server how this resource adapter needs to be deployed, configured, and how both application components (the notification sender and the feedback receiver) need to be bound to the adapter.

For the notification sender part, this connection factory needs to be bound to a JNDI name:

nl.meandi.apns.ManagedConnectionFactoryImpl

In addition, the connection factory needs to be configured with these two properties:

  • certificateFileName: the name of the file that contains the APNS certificate
  • certificateFilePassword: the password of the certificate file

For the feedback part, the message driven bean needs to be configured, by setting the activationConfig element of the @MessageDrivenBean annotation, and specifying the same two certificate properties that were just mentioned for the notification sender.

The adapter will automatically derive from the certificate whether it needs to connect to the sandbox environment of Apple, or to the production environment. It is possible to configure multiple pairs of connection factories and message driven beans, if you need to handle multiple iOS apps (that each require a certificate of their own).

Sample application

A sample application has been included in this project. It's a JSF application that runs inside a Wildfly 9 application server. In order to run it, you first need to clone this project and build the docker images, in a shell that has a Docker engine configured:

mvn install -Pdocker

After that, run this script to start the application:

etc/start-example.sh <certificate_file_name> <certificate_file_password>

The web application will be available at this URL:

<docker_host>:8080/apns-notifier

Then you can start sending push notifications to devices:

screenshot

Versions

Version
0.20
0.19
0.18
0.17