1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.14"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Raritan PX2/PX3 JSON-RPC API: Event Service</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Raritan PX2/PX3 JSON-RPC API
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.14 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Event Service </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>A large number of IDL-defined interfaces define events to notify client applications about changed data (sensor readings, updated settings, etc.). Changes are pushed from the server to the client without need for frequent polling. This allows to write client application that respond quickly to changes; for instance the web GUI makes heavy use of this feature.</p>
<dl class="section note"><dt>Note</dt><dd>This section is not about configuring event rules and actions! See <a class="el" href="eventengine.html">Event Rules and Actions</a> instead.</dd></dl>
<h2>Push Mechanism</h2>
<p>The event service uses a so-called long polling technique to emulate a push mechanism. Clients invoke the <b>pollEvents()</b> method to get new events. The server delays the handling of this request for up to 30 seconds as long as no new events are availble. The request is immediately completed as soon as events become available, allowing the client to respond without delay.</p>
<p>Long polling is particularly useful for applications that support handling multiple requests in parallel, either by using asynchronous response handling or multithreading. If this is not possible, clients can use the non-blocking variant <b>pollEventsNb()</b>, which returns immediately even when no events are available. The client must call this method frequently to get new events, which is still better than individually polling a large number of objects.</p>
<h2>Programming Model</h2>
<p>Events are distributed by the <b>event.Service</b> instance at <code>/eventservice</code>. Clients need to register an event channel, which is their own server-side queue for pending events. Event channels must be actively used to be kept alive. Event channels that are not accessed for 30 seconds are destroyed to reclaim server memory.</p>
<p>After registering an event channel, the client uses the <b>demandEvent</b> and <b>cancelEvent</b> family of methods to configure a filter for events they are interested in. Events can be selected based on type (e.g. numeric sensor reading change) and/or originating object (e.g. the inlet current sensor). Subscriptions can be added and removed at any time as long as the event channel is alive.</p>
<p>Finally, the client repeatedly calls the <b>pollEvents</b> method to get new events. The request completes as soon as new events become available that match one of the client's subscriptions, or after a maximum wait time of 30 seconds.</p>
<h2>Event Definitions</h2>
<p>Supported events and their contained data fields are defined in IDL as a hierarchy of <code>valueobject</code> declaration. The root event type is <code>raritan.rpc.idl.Event</code>, all other events are derived from that type.</p>
<p>All events have a <b>source</b> data field that contains a reference to the object originating the event. E.g., the <b>source</b> of an <b>Outlet.StateChangedEvent</b> is the outlet whose state has changed. Most events declare additional data fields, in this case the old and new outlet state.</p>
<p>Subscriptions for a base event type include derived types. For instance, the <b>AccountAdded</b> and <b>AccountDeleted</b> events in the <b>UserManager</b> interface both extend the base <b>AccountEvent</b>. A client subscribing for this base event will receive add and delete events.</p>
<div class="fragment"><div class="line"><span class="comment"># Python example: Blocking event poll</span></div><div class="line"></div><div class="line"><span class="keyword">import</span> raritan.rpc.event</div><div class="line"><span class="keyword">import</span> raritan.rpc.sensors</div><div class="line"></div><div class="line">event_service = raritan.rpc.event.Service(<span class="stringliteral">"/eventservice"</span>, agent)</div><div class="line"></div><div class="line"><span class="comment"># Register an event channel</span></div><div class="line">channel = event_service.createChannel()</div><div class="line"></div><div class="line"><span class="comment"># Subscribe for reading/state updates from any sensor</span></div><div class="line">channel.demandEventTypes([</div><div class="line"> raritan.rpc.sensors.NumericSensor.ReadingChangedEvent,</div><div class="line"> raritan.rpc.sensors.StateSensor.StateChangedEvent</div><div class="line">])</div><div class="line"></div><div class="line"><span class="comment"># Poll for events until interrupted</span></div><div class="line">print(<span class="stringliteral">"Polling for events, Ctrl-C to stop ..."</span>)</div><div class="line"><span class="keywordflow">try</span>:</div><div class="line"> <span class="keywordflow">while</span> <span class="keyword">True</span>:</div><div class="line"> result, events = channel.pollEvents()</div><div class="line"> <span class="keywordflow">for</span> event <span class="keywordflow">in</span> events:</div><div class="line"> print(event)</div><div class="line"><span class="keywordflow">except</span> KeyboardInterrupt:</div><div class="line"> print(<span class="stringliteral">"\n"</span>)</div></div><!-- fragment --> </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Aug 21 2020 10:20:37 for Raritan PX2/PX3 JSON-RPC API by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.14
</small></address>
</body>
</html>
|
