Deprecate attach() and next() methods in ResultSetAdapter.

gk-brown · gk-brown · commit f1da6fe80691 · 2020-01-28T06:33:25.000-05:00
diff --git a/README.md b/README.md
@@ -953,97 +953,6 @@ the values of the "first_name" and "last_name" columns would be returned in a ne
 ]
 ```
 
-### Nested Queries
-`ResultSetAdapter` can also be used to return the results of nested queries. The `attach()` method assigns a subquery to a key in the result map:
-
-```java
-public void attach(String key, String subquery) { ... }
-public void attach(String key, Parameters subquery) { ... }
-```
-
-Each attached query is executed once per row in the result set. The resulting rows are returned in a list that is associated with the corresponding key. 
-
-Internally, subqueries are executed as prepared statements using the `Parameters` class. All values in the base row are supplied as parameter values to each subquery. 
-
-An example based on the MySQL "employees" sample database is shown below. The base query retreives the employee's number, first name, and last name from the "employees" table. Subqueries to return the employee's salary and title history are optionally attached based on the values provided in the `details` parameter:
-
-```java
-@RequestMethod("GET")
-@ResourcePath("?:employeeNumber")
-public Map<String, ?> getEmployee(List<String> details) throws SQLException {
-    String employeeNumber = getKey("employeeNumber");
-
-    Parameters parameters = Parameters.parse("SELECT emp_no AS employeeNumber, "
-        + "first_name AS firstName, "
-        + "last_name AS lastName "
-        + "FROM employees WHERE emp_no = :employeeNumber");
-
-    Map<String, ?> employee;
-    try (Connection connection = dataSource.getConnection();
-        PreparedStatement statement = connection.prepareStatement(parameters.getSQL())) {
-        parameters.apply(statement, mapOf(
-            entry("employeeNumber", employeeNumber))
-        );
-
-        try (ResultSet resultSet = statement.executeQuery()) {
-            ResultSetAdapter resultSetAdapter = new ResultSetAdapter(resultSet);
-
-            for (String detail : details) {
-                switch (detail) {
-                    case "titles": {
-                        resultSetAdapter.attach("titles", "SELECT title, "
-                            + "from_date AS fromDate, "
-                            + "to_date AS toDate "
-                            + "FROM titles WHERE emp_no = :employeeNumber");
-
-                        break;
-                    }
-
-                    case "salaries": {
-                        resultSetAdapter.attach("salaries", "SELECT salary, "
-                            + "from_date AS fromDate, "
-                            + "to_date AS toDate "
-                            + "FROM salaries WHERE emp_no = :employeeNumber");
-
-                        break;
-                    }
-                }
-            }
-
-            employee = resultSetAdapter.next();
-        }
-    }
-
-    return employee;
-}
-```
-
-A sample response including both titles and salaries is shown below:
-
-```json
-{
-  "employeeNumber": 10004,
-  "firstName": "Chirstian",
-  "lastName": "Koblick",
-  "titles": [
-    {
-      "title": "Senior Engineer",
-      "fromDate": 817794000000,
-      "toDate": 253370782800000
-    },
-    ...
-  ],
-  "salaries": [
-    {
-      "salary": 74057,
-      "fromDate": 1006837200000,
-      "toDate": 253370782800000
-    },
-    ...
-  ]
-}
-```
-
 ## StreamAdapter
 The `StreamAdapter` class presents the contents of a stream as an iterable sequence. This can be used to serialize the result of a stream operation without needing to first collect the results, which may be expensive if the stream is large:
 
diff --git a/build.gradle b/build.gradle
@@ -14,7 +14,7 @@
 
 subprojects {
     group = 'org.httprpc'    
-    version = '7.0.2'
+    version = '7.0.3'
 
     apply plugin: 'java-library'
     apply plugin: 'maven-publish'
diff --git a/httprpc-client/src/main/java/org/httprpc/sql/ResultSetAdapter.java b/httprpc-client/src/main/java/org/httprpc/sql/ResultSetAdapter.java
@@ -35,6 +35,7 @@ public class ResultSetAdapter implements Iterable<Map<String, Object>> {
     private ResultSet resultSet;
     private ResultSetMetaData resultSetMetaData;
 
+    // TODO Remove this when attach() method is dropped
     private LinkedHashMap<String, Parameters> subqueries = new LinkedHashMap<>();
 
     private Iterator<Map<String, Object>> iterator = new Iterator<Map<String, Object>>() {
@@ -149,7 +150,10 @@ public ResultSetAdapter(ResultSet resultSet) {
      *
      * @param subquery
      * The subquery to attach.
+     *
+     * @deprecated Use {@link Stream} operations instead.
      */
+    @Deprecated
     public void attach(String key, String subquery) {
         attach(key, Parameters.parse(subquery));
     }
@@ -162,7 +166,10 @@ public void attach(String key, String subquery) {
      *
      * @param subquery
      * The subquery to attach.
+     *
+     * @deprecated Use {@link Stream} operations instead.
      */
+    @Deprecated
     public void attach(String key, Parameters subquery) {
         if (key == null) {
             throw new IllegalArgumentException();
@@ -180,7 +187,10 @@ public void attach(String key, Parameters subquery) {
      *
      * @return
      * The next result, or <tt>null</tt> if there are no more results.
+     *
+     * @deprecated Use {@link Stream} operations instead.
      */
+    @Deprecated
     public Map<String, Object> next() {
         return iterator.hasNext() ? iterator.next() : null;
     }
diff --git a/httprpc-server/src/main/java/org/httprpc/WebService.java b/httprpc-server/src/main/java/org/httprpc/WebService.java
@@ -653,7 +653,11 @@ private void describeResource(String path, Resource resource, TreeMap<Class<?>,
             xmlStreamWriter.writeEndElement();
 
             for (Map.Entry<String, LinkedList<Handler>> entry : resource.handlerMap.entrySet()) {
-                for (Handler handler : entry.getValue()) {
+                List<Handler> handlers = entry.getValue();
+
+                handlers.sort(Comparator.comparing(handler -> handler.method.getName()));
+
+                for (Handler handler : handlers) {
                     Parameter[] parameters = handler.method.getParameters();
 
                     xmlStreamWriter.writeStartElement("pre");
diff --git a/httprpc-test/src/main/java/org/httprpc/test/mysql/EmployeeService.java b/httprpc-test/src/main/java/org/httprpc/test/mysql/EmployeeService.java
diff --git a/httprpc-test/src/main/webapp/index.jsp b/httprpc-test/src/main/webapp/index.jsp
@@ -207,15 +207,5 @@
 <br/>
 <a href="${pageContext.request.contextPath}/pets/average-age">Average Age</a><br/>
 
-<hr/>
-
-<a href="${pageContext.request.contextPath}/employees?api">Employees (API)</a><br/>
-<br/>
-<a href="${pageContext.request.contextPath}/employees">Employees</a><br/>
-<a href="${pageContext.request.contextPath}/employees?name=bal*">Employees ("bal*")</a><br/>
-<br/>
-<a href="${pageContext.request.contextPath}/employees/10001">Employee 10001</a><br/>
-<a href="${pageContext.request.contextPath}/employees/10001?details=titles&details=salaries">Employee 10001 (details)</a><br/>
-
 </body>
 </html>
diff --git a/settings.gradle b/settings.gradle
@@ -1,5 +1,3 @@
 rootProject.name = 'HTTP-RPC'
 
 include  'httprpc', 'httprpc-client', 'httprpc-server', 'httprpc-test'
-
-enableFeaturePreview('STABLE_PUBLISHING')
