UDP Push

Introduction

This document defines the Open-Xchange UDP Push protocol which is used to send events to registered clients and servers.

Low level Documentation

A package is a number of tokens. The tokens are strings, numbers or boolean values and every token is seperated with a '\1'.

Protocol

Client Register Package

This package is sent by the client to tell the OX server he wants to receive push packages. The client sends this package to the server on port 44335.

Client Register Package
Name Type Descrption
Magic int Number Static value: 1337
Package Length Number The length of informations in this package
Action Number For a client register package the action value is always '1'
User ID Number The user id
Context ID Number The context id of the user

Java Example

public static final int MAGIC = 1337;

public static final int REGISTER_ACTION = 1;

protected int userId = 1234; // read userId from config
protected int context = 5678 // read context from config

StringBuffer packageData = new StringBuffer();
packageData.append(REGISTER_ACTION);
packageData.append('\1');
packageData.append(userId);
packageData.append('\1');
packageData.append(contextId);
packageData.append('\1');
        
StringBuffer stringPackage = new StringBuffer();
stringPackage.append(MAGIC);
stringPackage.append('\1');
stringPackage.append(packageData.length());
stringPackage.append('\1');
stringPackage.append(packageData);

// send the value of stringPackage

The response of a client register package request is only "OK\1'

Push Package

OX Server send this package to specific clients informing this about the folder that must be refreshed. This package is directly sent to the client to his registered port.

Push Package
Name Type Descrption
Folder ID Number The folder id where an event occured

Internal Register Sync Package

This package is sent between OX servers in the cluster to synchronize the client registrations. Before this package is sent the OX server in the cluster must be discovered by the remote host register package.

This is only sent if register distribution is enabled. But the preferred way should be the event distribution.

Internal Register Sync Package
Name Type Descrption
Magic int Number Static value: 1337
Package Length Number The length of informations in this package
Action Number For a client register package the action value is always '2'
User ID Number The user id
Context ID Number The context id of the user
Address String The address of the user who has registered
Port Number The port of the user who has registered

Java Example

public static final int MAGIC = 1337;

public static final int INTERNAL_REGISTER_ACTION = 2;

protected int userId = 1234; // read userId from config
protected int context = 5678 // read context from config

StringBuffer packageData = new StringBuffer();
packageData.append(INTERNAL_REGISTER_ACTION);
packageData.append('\1');
packageData.append(userId);
packageData.append('\1');
packageData.append(contextId);
packageData.append('\1');
        
StringBuffer stringPackage = new StringBuffer();
stringPackage.append(MAGIC);
stringPackage.append('\1');
stringPackage.append(packageData.length());
stringPackage.append('\1');
stringPackage.append(packageData);

// send the value of stringPackage

Internal Push Sync Package

This package is sent between OX servers in the cluster to distribute the events. Before this package is sent the OX server in the cluster must be discovered by the remote host register package.

This is only sent if event distribution is enabled. Every server should listen to this package to get informed about what is going on with all data.

Internal Push Sync Package
Name Type Descrption
Magic int Number Static value: 1337
Package Length Number The length of informations in this package
Action Number For a internal push sync package the action value is always '3'
Folder ID Number The folder id where the event occured
Module Number The Id of the module:

Appointment = 1 Task = 4 Contact = 7 EMail = 19 Folder = 20

Context ID Number The context id of the user
Users String All user id who are affected by this event seperated with a comma.

The module EMail is very limited. The folderId is always 1 because push is only supported in the INBOX of a user. The affected users are always only the owner of the INBOX.

Remote Host Register

This UDP package is used to discover hosts in the cluster network. Therefore this package is sent to the multicast address and port.

Note, the register package must be refreshed after a configurable time. The default timeout is 60 Minutes and can be configured at /opt/open-xchange/etc/groupware/push.properties, com.openexchange.push.udp.registerTimeout:3600000

Remote Host Register
Name Type Descrption
Magic int Number Static value: 1337
Package Length Number The length of informations in this package
Action Number For a remote host register the action value is always '4'
Hostname String The hostname of the registering server
Port Number The port of the registering server

Java Example

public static final int MAGIC = 1337;

public static final int REMOTE_HOST_REGISTER = 4;

/*
 * The server name of registering application
 */
protected String hostname = "yourserver.tux"; // server

/*
 * The port of the of the registering application. 
 * The port where your  application is listening
 */
protected int port = 12345; // port

StringBuffer packageData = new StringBuffer();
packageData.append(INTERNAL_REGISTER_ACTION);
packageData.append('\1');
packageData.append(hostname);
packageData.append('\1');
packageData.append(port);
packageData.append('\1');
        
StringBuffer stringPackage = new StringBuffer();
stringPackage.append(MAGIC);
stringPackage.append('\1');
stringPackage.append(packageData.length());
stringPackage.append('\1');
stringPackage.append(packageData);

// send the value of stringPackage

Example for creating events that trigger the UDP push mechanism

Every bundle is able to create events for triggering the UDP push mechanism. This short example shows how to create events to trigger UDP push packages for email.


import com.openexchange.event.CommonEvent;
import com.openexchange.event.impl.CommonEventImpl;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventAdmin;

CommonEvent emailEvent = new CommonEventImpl(userId, contextId, CommonEvent.INSERT, Types.EMAIL, null, null, null, null, null);
Hashtable<String, CommonEvent> ht = new Hashtable<String, CommonEvent>();
ht.put(CommonEvent.EVENT_KEY, emailEvent);
Event event = new Event("com/openexchange/mail/new", ht);
EventAdmin.postEvent(event);