[
https://issues.apache.org/jira/browse/QUARKS-123?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15252149#comment-15252149
]
ASF GitHub Bot commented on QUARKS-123:
---------------------------------------
Github user queeniema commented on a diff in the pull request:
https://github.com/apache/incubator-quarks-website/pull/40#discussion_r60612102
--- Diff: site/recipes/recipe_adaptable_polling_source.md ---
@@ -0,0 +1,138 @@
+---
+title: Changing a Polled Source Stream's Period
+---
+
+The [Writing a Source Function](recipe_source_function.html) recipe
introduced the basics of creating a source stream by polling a data source
periodically.
+
+Oftentimes, a user wants the poll frequency to be adaptable rather than
static. For example, an event such a sudden rise in a temperature sensor may
motivate more frequent polling of the sensor and analysis of the data until the
condition subsides. A change in the poll frequency may be driven by locally
performed analytics or via a command from an external source.
+
+A Quarks IotProvider and IoTDevice with its command streams would be a
natural way to control the application. In this recipe we will just simulate a
"set poll period" command stream.
+
+The ``Topology.poll()`` documentation describes how the poll period may be
changed at runtime.
+
+The mechanism is based on a more general Quarks runtime
``quarks.execution.services.ControlService`` service. The runtime registers
"control beans" for entities that are controllable. These controls can be
retrieved at runtime via the service.
+
+At runtime, ``Topology.poll()`` registers a
``quarks.execution.mbeans.PeriodicMXBean`` control. Retrieving the control at
runtime requires setting an alias on the poll generated stream using
``TStream.alias()``.
+
+## Create the polled stream and set its alias
+
+```java
+ Topology top = ...;
+ SimulatedTemperatureSensor tempSensor = new
SimulatedTemperatureSensor();
+ TStream<Double> engineTemp = top.poll(tempSensor, 1,
TimeUnit.SECONDS)
+ .alias("engineTemp")
+ .tag("engineTemp");
+```
+
+It's also a good practice to add tags to streams to improve the usability
of the development mode Quarks console.
+
+## Define a "set poll period" method
+
+```java
+ static <T> void setPollPeriod(TStream<T> pollStream, long period,
TimeUnit unit) {
+ // get the topology's runtime ControlService service
+ ControlService cs =
pollStream.topology().getRuntimeServiceSupplier()
+
.get().getService(ControlService.class);
+
+ // using the the stream's alias, get its PeriodicMXBean control
+ PeriodicMXBean control = cs.getControl("periodic",
pollStream.getAlias(), PeriodicMXBean.class);
+
+ // change the poll period using the control
+ System.out.println("Setting period="+period+" "+unit+"
stream="+pollStream);
+ control.setPeriod(period, unit);
+ }
+```
+
+## Process the "set poll period" command stream
+
+Our commands are on the "TStream<JsonObject> cmds" stream. Each
JsonObject tuple is a command with the properties "period" and "unit".
--- End diff --
Consider putting `JsonObject` in an inline code block
> Add recipe for poll() source with adaptable poll rate
> -----------------------------------------------------
>
> Key: QUARKS-123
> URL: https://issues.apache.org/jira/browse/QUARKS-123
> Project: Quarks
> Issue Type: Task
> Components: Documentation
> Reporter: Dale LaBossiere
> Assignee: Dale LaBossiere
>
> A use case is something like: an application wants to increase the poll
> frequency / rate of analytics once some trigger condition occurs. The
> trigger condition may be detected by local analytics. Or perhaps the change
> in poll frequency will be the result of receiving an IotDevice command.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
