Netflux REST Services
 | Provides the REST resources needed to create and retrieve the entity channels that are used for real-time synchronization in XWiki. |
| Type | JAR |
| Category | API |
| Developed by | |
| Active Installs | 16 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Compatibility | Since 13.9RC1 |
Table of contents
Description
The Netflux module provides support for real-time WebSocket-based communication in XWiki, by implementing the following features:
- An API to associate one or more real-time communication channels to an XWiki entity. Each channel has an auto-generated key, used when joining, and a human-readable path, used to distinguish between the channels associated to the same entity.
- A script service and a REST resource to help create and retrieve entity channels.
- A WebSocket server end-point used to join channels and to exchange channel or direct messages. This end-point implements the Netflux server protocol.
On the client side the JavaScript API is provided by the Netflux client, which has to be installed separately.
The Netflux module supersedes the Realtime Netflux Backend extension.
Usage
From Velocity
You can use the provided script service to create and retrieve existing entity channels. You won't be able to do more than that though because the interaction with the entity channels (joining and exchanging messages) is done through the Netflux client, from JavaScript (see below).
#set ($channel = $services.netflux.createChannel($doc.documentReference, ['content', 'wysiwyg']))
Created channel $channel.key
#set ($channels = $services.netflux.getChannels($doc.documentReference, ['content']))
Document content channels:
#foreach ($channel in $channels)
* $channel.key (path: $stringtool.join($channel.path, '/'), userCount: $channel.userCount)
#end
{{/velocity}}
From JavaScript
You have to use the Netflux client to interact with the entity channels. First you need to connect to the Netflux WebSocket and then you need to join an existing entity channel using the channel key. In order to create and retrieve the channel key you have to use the provided Netflux REST resource.
paths: {
'netflux-client': $jsontool.serialize($services.webjars.url('org.xwiki.contrib:netflux-websocket-webjar',
'netflux-client.min.js')),
// Needed by Netflux client.
'es6-promise': $jsontool.serialize($services.webjars.url('es6-promise', 'es6-promise.min.js'))
}
});
require(['jquery', 'netflux-client'], function($, netfluxClient) {
var netfluxWebSocketURL = $jsontool.serialize($services.websocket.url('netflux'));
// Connect to the Netflux WebSocket.
netfluxClient.connect(netfluxWebSocketURL).then(network => {
// Create and retrieve the channels.
var channelsRestURL = XWiki.currentDocument.getRestURL('channels');
$.getJSON(channelsRestURL, $.param({
// You can omit this if you want to retrieve all the existing channels, or pass an array if you want to create
// multiple channels.
path: 'content/wysiwyg',
// You can omit this if you just want to retrieve the list of channels.
create: true
}, true)).done(channels => {
// Join the created channel.
network.join(channels[0].key).then(afterJoinChannel);
});
});
var afterJoinChannel = function(channel) {
console.log(`Joined channel ${channel.id}.`);
console.log(`Channel members are: ${channel.members.join(', ')}.`);
// Add event listeners.
channel.on('join', user => {
console.log(`${user} joined the channel ${channel.id}.`);
console.log(`Channel members are: ${channel.members.join(', ')}.`);
});
channel.on('leave', user => {
console.log(`${user} left the channel ${channel.id}.`);
console.log(`Channel members are: ${channel.members.join(', ')}.`);
});
channel.on('message', (message, from) => {
console.log(`Received channel message '${message}' from ${from}.`);
});
// Send messages.
channel.bcast('Hi!').then(() => {
console.log('Message sent to channel.');
});
};
});
REST API
Entity channels can be created and retrieved using the following REST API.
/wikis/{wikiName}/spaces/{spaceName: .+}/pages/{pageName}/channels[?create={true,false}[&path=p]*]
- HTTP Method: GET
- Media Types: application/xml or application/json
- Description: The list of Netflux channels associated with the specified XWiki document and matching the query string filters.
- Query Parameters:
- path: (optional) one of more paths used to filter the document channels; if a path ends with a slash then it is treated as a path prefix
- create: (optional) whether to create the missing channels specified with the path parameter (when the path is not a prefix, i.e. when the path doesn't end with a slash)
- Status Code:
- 200: if the request was successful
- Response:
- a list of entity channel objects, each containing: the entity reference, the path, the channel key used to join the channel and the user count
Examples:
curl -u Admin:admin -H 'Accept: application/json' \
http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Sandbox/pages/WebHome/channels
# [{
# "entityReference":{"value":"xwiki:Sandbox.WebHome","type":"DOCUMENT"},
# "path":["content","wysiwyg"],
# "key":"82e4d85bd024bcca517ff04bb369b70c723845111dcb341d",
# "userCount":2
# }]
# Request a specific channel for a given XWiki document, creating it if it doesn't exist already:
curl -u Admin:admin -H 'Accept: application/json' \
"http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Sandbox/pages/WebHome/channels?path=content%2Fwiki&create=true"
# [{
# "entityReference":{"value":"xwiki:Sandbox.WebHome","type":"DOCUMENT"},
# "path":["content","wiki"],
# "key":"3b34f67f66326d86f4115f8f77914f597ecd147d377997f5",
# "userCount":0
# }]
# Request channels with a given path prefix:
curl -u Admin:admin -H 'Accept: application/json' \
http://localhost:8080/xwiki/rest/wikis/xwiki/spaces/Sandbox/pages/WebHome/channels?path=content%2F
# [{
# "entityReference":{"value":"xwiki:Sandbox.WebHome","type":"DOCUMENT"},
# "path":["content","wysiwyg"],
# "key":"82e4d85bd024bcca517ff04bb369b70c723845111dcb341d",
# "userCount":2
# },{
# "entityReference":{"value":"xwiki:Sandbox.WebHome","type":"DOCUMENT"},
# "path":["content","wiki"],
# "key":"3b34f67f66326d86f4115f8f77914f597ecd147d377997f5",
# "userCount":0
# }]
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-netflux-rest 16.9.0):
- org.xwiki.platform:xwiki-platform-netflux-api 16.9.0
- org.xwiki.platform:xwiki-platform-rest-server 16.9.0
- jakarta.ws.rs:jakarta.ws.rs-api 2.1.6
