XEP-0163: Personal Eventing Protocol

XEP-0163: Personal Eventing Protocol (PEP) defines semantics for using the XMPP publish-subscribe protocol to broadcast state change events associated with an instant messaging and presence account.

For every instant messaging account a PubSub service is automatically created, which is then referred to as Personal Eventing Service. By default your contacts are automatically added as subscribers to every node you publish.

Therefore it can be used, if you want to publish your location, tune, mood, activity or your avatar, so that your contacts will receive notifications for these kind of information, e.g. you publish your geo location and your contacts receive it.

Creating the Personal Eventing Service

First you have to create the personal eventing service. Since it’s just a subset of PubSub, you have to use the PubSubManager and the personal eventing service is just a PubSubService.

PubSubManager pubSubManager = xmppClient.getManager(PubSubManager.class);
PubSubService personalEventingService = pubSubManager.createPersonalEventingService();

Publishing User Data

If you want to publish data to a node in your personal service, you create a local PubSubNode instance so that you can work with it, then publish data to that node.

Here’s an example to publish your geo location. As per XEP-0080: User Location you want to publish it to the node “http://jabber.org/protocol/geoloc” which is GeoLocation.NAMESPACE.

PubSubNode pubSubNode = personalEventingService.node(GeoLocation.NAMESPACE);
pubSubNode.publish(GeoLocation.builder()
    .latitude(45.44)
    .longitude(12.33)
    .build());

By default (i.e. if not otherwise configured) all your contacts now receive an event notification about your new geo location.

Listening for PEP Events

Now that you have published your geo location all your contacts will receive notifications about it. This is just a message with a “PubSub event” extension.

xmppClient.addInboundMessageListener(e -> {
    Message message = e.getMessage();
    Event event = message.getExtension(Event.class);
    if (event != null) {
        if (GeoLocation.NAMESPACE.equals(event.getNode())) {
            for (Item item : event.getItems()) {
                if (item.getPayload() instanceof GeoLocation) {
                    GeoLocation geoLocation = (GeoLocation) item.getPayload();
                    Double latitude = geoLocation.getLatitude();   // 45.44
                    Double longitude = geoLocation.getLongitude(); // 12.33
                    // ...
                }
            }
        }
    }
});