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
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
