From 806a1c23e15fdeb336f7e125ea61cd5c4073f0eb Mon Sep 17 00:00:00 2001
From: John Blum <jblum@pivotal.io>
Date: Sun, 24 Jun 2018 20:32:07 -0700
Subject: [PATCH] Add continuous-query.adoc documenting the auto-configuration
 of Apache Geode/Pivotal GemFire Continuous Query (CQ).

---
 .../src/docs/asciidoc/continuous-query.adoc   | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 spring-geode-docs/src/docs/asciidoc/continuous-query.adoc

diff --git a/spring-geode-docs/src/docs/asciidoc/continuous-query.adoc b/spring-geode-docs/src/docs/asciidoc/continuous-query.adoc
new file mode 100644
index 00000000..eada377b
--- /dev/null
+++ b/spring-geode-docs/src/docs/asciidoc/continuous-query.adoc
@@ -0,0 +1,87 @@
+[[geode-continuous-query]]
+== Continuous Query
+
+Arguably, the most invaluable of applications are those that can process a stream of events as they happen,
+and intelligently react in near real-time to the countless changes in the data over time.  The most useful
+of frameworks are those that can make processing a stream of events, as they happen, as easy as possible.
+
+Spring Boot for Apache Geode & Pivotal GemFire does just that, without users having to perform any complex setup
+or configure any necessary infrastructure components to enable such functionality.  Developers can simply define
+the criteria for the data they are interested in and implement a handler to process the stream of events
+as they occur.
+
+Apache Geode & Pivotal GemFire make defining criteria for data of interests easy when using
+{apache-geode-docs}/developing/continuous_querying/chapter_overview.html[Continuous Query (CQ)]. With CQ, you can
+express the criteria matching the data of interests using a query predicate.  Apache Geode & Pivotal GemFire supports
+the {apache-geode-docs}/developing/querying_basics/query_basics.html[Object Query Language (OQL)] for defining
+and executing queries.  OQL is not unlike SQL, and supports projections, query predicates, ordering and aggregates.
+And, when used in CQs, they execute continuously, firing events when the data changes in such ways as to match
+the criteria expressed in the query predicate.
+
+Spring Boot for Apache Geode/Pivotal GemFire combines the ease of expressing interests in data using an OQL
+query statement with implementing the listener handler callback, in 1 easy step.
+
+For example, suppose we want to perform some follow up action anytime a customer's loan application is either
+approved or denied.
+
+First, the application model for our `EligibilityDecision` class might look something like:
+
+.EligibilityDecision class
+[source,java]
+----
+@Region("EligibilityDecisions")
+class EligibilityDecision {
+
+    private final Person person;
+
+    private Status status = Status.UNDETERMINED;
+
+    private final Timespan timespan;
+
+    ...
+
+    enum Status {
+
+        APPROVED,
+        DENIED,
+        UNDETERMINED,
+
+    }
+}
+----
+
+Then, we can implement and declare our CQ event handler methods:
+
+[source,java]
+----
+@Component
+class EligibilityDecisionPostProcessor {
+
+
+    @ContinuousQuery(name = "ApprovedDecisionsHandler",
+        query = "SELECT decisions.*
+                 FROM /EligibilityDecisions decisions
+                 WHERE decisions.getStatus().name().equalsIgnoreCase('APPROVED')")
+    public void processApprovedDecisions(CqEvent event) {
+        ...
+    }
+
+    @ContinuousQuery(name = "DeniedDecisionsHandler",
+        query = "SELECT decisions.*
+                 FROM /EligibilityDecisions decisions
+                 WHERE decisions.getStatus().name().equalsIgnoreCase('DENIED')")
+    public void processDeniedDecisions(CqEvent event) {
+        ...
+    }
+}
+----
+
+Thus, anytime eligibility is processed and a decision as been made, either approved or denied, our application
+will get notified, and as an application developer, you are free to code your handler and respond to the event
+anyway you like.  And, because our Continuous Query handler class is a component, or bean in the Spring
+`ApplicationContext`, we can auto-wire any other beans to carry out the applications function.
+
+This is not unlike Spring's {spring-framework-docs}/integration.html#jms-annotated[Annotation-based listener endpoints]
+using in (JMS) message listeners/handlers, except in Spring Boot for Apache Geode/Pivotal GemFire, you do not need to do
+anything special to enable this functionality.  Just declare the `@ContinuousQuery` annotation on a POJO handler method
+and off you go.  Simple!