add documentation

src/main/java/examples/SQLExamples.java

@@ -4,13 +4,13 @@
 import io.vertx.core.json.JsonObject;
 import io.vertx.ext.sql.ResultSet;
 import io.vertx.ext.sql.SQLConnection;
+import io.vertx.ext.sql.SQLRowStream;
 import io.vertx.ext.sql.UpdateResult;
 
 import java.util.ArrayList;
 import java.util.List;
 
 /**
- *
  * @author <a href="http://tfox.org">Tim Fox</a>
  */
 public class SQLExamples {
@@ -42,7 +42,7 @@ public void example3(ResultSet resultSet) {
 
     List<JsonArray> results = resultSet.getResults();
 
-    for (JsonArray row: results) {
+    for (JsonArray row : results) {
 
       String id = row.getString(0);
       String fName = row.getString(1);
@@ -57,7 +57,7 @@ public void example3__1(ResultSet resultSet) {
 
     List<JsonObject> rows = resultSet.getRows();
 
-    for (JsonObject row: rows) {
+    for (JsonObject row : rows) {
 
       String id = row.getString("ID");
       String fName = row.getString("FNAME");
@@ -127,7 +127,7 @@ public void example5(SQLConnection connection) {
   public void example6(SQLConnection connection) {
 
     String sql = "CREATE TABLE PEOPLE (ID int generated by default as identity (start with 1 increment by 1) not null," +
-                 "FNAME varchar(255), LNAME varchar(255), SHOE_SIZE int);";
+      "FNAME varchar(255), LNAME varchar(255), SHOE_SIZE int);";
 
     connection.execute(sql, execute -> {
       if (execute.succeeded()) {
@@ -202,7 +202,7 @@ public void example10(SQLConnection connection) {
 
     String func = "{ call customer_lastname(?, ?) }";
 
-    connection.callWithParams(func, new JsonArray().add("John"), new JsonArray().addNull().add("VARCHAR"), res-> {
+    connection.callWithParams(func, new JsonArray().add("John"), new JsonArray().addNull().add("VARCHAR"), res -> {
 
       if (res.succeeded()) {
         ResultSet result = res.result();
@@ -247,4 +247,34 @@ public void example13(ResultSet rs) {
       // do something with the result set...
     } while ((rs = rs.getNext()) != null);
   }
+
+  public void example14(SQLConnection connection) {
+    connection.queryStream("SELECT * FROM large_table", stream -> {
+      if (stream.succeeded()) {
+        stream.result().handler(row -> {
+          // do something with the row...
+        });
+      }
+    });
+  }
+
+  public void example15(SQLConnection connection) {
+    connection.queryStream("SELECT * FROM large_table; SELECT * FROM other_table", stream -> {
+      if (stream.succeeded()) {
+        SQLRowStream sqlRowStream = stream.result();
+
+        sqlRowStream
+          .resultSetClosed(v -> {
+            // will ask to restart the stream with the new result set if any
+            sqlRowStream.moreResults();
+          })
+          .handler(row -> {
+            // do something with the row...
+          })
+          .endHandler(v -> {
+            // no more data available...
+          });
+      }
+    });
+  }
 }

src/main/java/io/vertx/ext/sql/package-info.java

@@ -218,6 +218,25 @@
  * {@link examples.SQLExamples#example13}
  * ----
  *
+ * === Streaming
+ *
+ * When dealing with large data sets, it is not advised to use API just described but to stream data since it avoids
+ * inflating the whole response into memory and JSON and data is just processed on a row by row basis, for example:
+ *
+ * [source,$lang]
+ * ----
+ * {@link examples.SQLExamples#example14}
+ * ----
+ *
+ * You still have full control on when the stream is pauses, resumed and ended. For cases where your query returns
+ * multiple result sets you should use the result set ended event to fetch the next one if available. If there is more
+ * data the stream handler will receive the new data, otherwise the end handler is invoked.
+ *
+ * [source,$lang]
+ * ----
+ * {@link examples.SQLExamples#example15}
+ * ----
+ *
  * === Using transactions
  *
  * To use transactions first set auto-commit to false with {@link io.vertx.ext.sql.SQLConnection#setAutoCommit(boolean, io.vertx.core.Handler)}.