UDPPush

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);