From 0822ad8d51667ded7246a95b68662eb007d28519 Mon Sep 17 00:00:00 2001
From: Robert Godfrey <rgodfrey@apache.org>
Date: Mon, 16 Mar 2015 21:51:35 +0000
Subject: QPID-6454 : Add page summarizing all api paths

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1667137 13f79535-47bb-0310-9956-ffa450edef68
---
 .../server/management/plugin/HttpManagement.java   |  22 +++-
 .../plugin/servlet/rest/ApiDocsServlet.java        | 146 +++++++++++++++------
 .../src/main/java/resources/css/apidocs.css        |  31 ++++-
 3 files changed, 158 insertions(+), 41 deletions(-)

(limited to 'qpid/java/broker-plugins')

diff --git a/qpid/java/broker-plugins/management-http/src/main/java/org/apache/qpid/server/management/plugin/HttpManagement.java b/qpid/java/broker-plugins/management-http/src/main/java/org/apache/qpid/server/management/plugin/HttpManagement.java
index 17e306f5bd..e30571615c 100644
--- a/qpid/java/broker-plugins/management-http/src/main/java/org/apache/qpid/server/management/plugin/HttpManagement.java
+++ b/qpid/java/broker-plugins/management-http/src/main/java/org/apache/qpid/server/management/plugin/HttpManagement.java
@@ -25,9 +25,12 @@ import java.io.Writer;
 import java.net.SocketAddress;
 import java.security.GeneralSecurityException;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.EnumSet;
 import java.util.HashSet;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
@@ -308,6 +311,11 @@ public class HttpManagement extends AbstractPluginAdapter<HttpManagement> implem
         addRestServlet(root, "binding", VirtualHostNode.class, VirtualHost.class, Exchange.class, Queue.class, Binding.class);
         addRestServlet(root, "session", VirtualHostNode.class, VirtualHost.class, Connection.class, Session.class);
 
+        ServletHolder apiDocsServlet = new ServletHolder(new ApiDocsServlet(getModel(), Collections.<String>emptyList()));
+        root.addServlet(apiDocsServlet, "/apidocs");
+        root.addServlet(apiDocsServlet, "/apidocs/");
+        root.addServlet(apiDocsServlet, "/apidocs/latest");
+        root.addServlet(apiDocsServlet, "/apidocs/latest/");
         root.addServlet(new ServletHolder(new UserPreferencesServlet()), "/service/userpreferences/*");
         root.addServlet(new ServletHolder(new LoggedOnUserPreferencesServlet()), "/service/preferences");
         root.addServlet(new ServletHolder(new StructureServlet()), "/service/structure");
@@ -454,9 +462,17 @@ public class HttpManagement extends AbstractPluginAdapter<HttpManagement> implem
                                            getContextValue(Long.class, MAX_HTTP_FILE_UPLOAD_SIZE_CONTEXT_NAME),
                                            -1l,
                                            getContextValue(Integer.class, MAX_HTTP_FILE_UPLOAD_SIZE_CONTEXT_NAME)));
-        root.addServlet(servletHolder, "/api/latest/" + name + "/*");
-        root.addServlet(servletHolder, "/api/v" + BrokerModel.MODEL_MAJOR_VERSION + "/" + name + "/*");
-        ServletHolder docServletHolder = new ServletHolder(name+"docs", new ApiDocsServlet(getModel(),hierarchy));
+
+        List<String> paths = Arrays.asList("/api/latest/" + name ,
+                                           "/api/v" + BrokerModel.MODEL_MAJOR_VERSION + "/" + name  );
+
+        for(String path : paths)
+        {
+            root.addServlet(servletHolder, path + "/*");
+        }
+        ServletHolder docServletHolder = new ServletHolder(name+"docs", new ApiDocsServlet(getModel(),
+                                                                                           paths,
+                                                                                           hierarchy));
         root.addServlet(docServletHolder, "/apidocs/latest/" + name + "/");
         root.addServlet(docServletHolder, "/apidocs/v" + BrokerModel.MODEL_MAJOR_VERSION + "/" + name +"/");
         root.addServlet(docServletHolder, "/apidocs/latest/" + name );
diff --git a/qpid/java/broker-plugins/management-http/src/main/java/org/apache/qpid/server/management/plugin/servlet/rest/ApiDocsServlet.java b/qpid/java/broker-plugins/management-http/src/main/java/org/apache/qpid/server/management/plugin/servlet/rest/ApiDocsServlet.java
index 5ef7a80660..5c30378fc6 100644
--- a/qpid/java/broker-plugins/management-http/src/main/java/org/apache/qpid/server/management/plugin/servlet/rest/ApiDocsServlet.java
+++ b/qpid/java/broker-plugins/management-http/src/main/java/org/apache/qpid/server/management/plugin/servlet/rest/ApiDocsServlet.java
@@ -20,19 +20,7 @@ import java.io.IOException;
 import java.io.PrintWriter;
 import java.io.Writer;
 import java.security.AccessControlException;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.Collections;
-import java.util.EnumSet;
-import java.util.HashMap;
-import java.util.HashSet;
-import java.util.Iterator;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-import java.util.UUID;
+import java.util.*;
 
 import javax.servlet.ServletConfig;
 import javax.servlet.ServletException;
@@ -64,19 +52,47 @@ public class ApiDocsServlet extends AbstractServlet
 {
     private static final Logger LOGGER = LoggerFactory.getLogger(ApiDocsServlet.class);
     private final Model _model;
-    private final Collection<Class<? extends ConfiguredObject>> _types;
+    private final List<Class<? extends ConfiguredObject>> _types;
 
     private Class<? extends ConfiguredObject>[] _hierarchy;
 
     private static final Set<Character> VOWELS = new HashSet<>(Arrays.asList('a','e','i','o','u'));
 
+    public static final Comparator<Class<? extends ConfiguredObject>> CLASS_COMPARATOR =
+            new Comparator<Class<? extends ConfiguredObject>>()
+            {
+                @Override
+                public int compare(final Class<? extends ConfiguredObject> o1,
+                                   final Class<? extends ConfiguredObject> o2)
+                {
+                    return o1.getSimpleName().compareTo(o2.getSimpleName());
+                }
+
+            };
+    private static final Map<Class<? extends ConfiguredObject>, List<String>> REGISTERED_CLASSES = new TreeMap<>(CLASS_COMPARATOR);
 
-    public ApiDocsServlet(final Model model, Class<? extends ConfiguredObject>... hierarchy)
+
+    public ApiDocsServlet(final Model model, final List<String> registeredPaths, Class<? extends ConfiguredObject>... hierarchy)
     {
         super();
         _model = model;
         _hierarchy = hierarchy;
-        _types = _model.getTypeRegistry().getTypeSpecialisations(getConfiguredClass());
+        _types = hierarchy.length == 0 ? null : new ArrayList<>(_model.getTypeRegistry().getTypeSpecialisations(getConfiguredClass()));
+        if(_types != null)
+        {
+            Collections.sort(_types, CLASS_COMPARATOR);
+        }
+        if(_hierarchy.length != 0)
+        {
+            List<String> paths = REGISTERED_CLASSES.get(getConfiguredClass());
+            if(paths == null)
+            {
+                paths = new ArrayList<>();
+                REGISTERED_CLASSES.put(getConfiguredClass(), paths);
+            }
+            paths.addAll(registeredPaths);
+
+        }
 
     }
 
@@ -88,11 +104,51 @@ public class ApiDocsServlet extends AbstractServlet
 
 
         PrintWriter writer = response.getWriter();
+
         writePreamble(writer);
         writeHead(writer);
-        writeUsage(writer, request);
-        writeTypes(writer);
-        writeAttributes(writer);
+
+        if(_hierarchy.length == 0)
+        {
+            writer.println("<table class=\"api\">");
+            writer.println("<thead>");
+            writer.println("<tr>");
+            writer.println("<th class=\"type\">Type</th>");
+            writer.println("<th class=\"path\">Path</th>");
+            writer.println("<th class=\"description\">Description</th>");
+            writer.println("</tr>");
+            writer.println("</thead>");
+            writer.println("<tbody>");
+            for(Map.Entry<Class<? extends ConfiguredObject>, List<String>> entry : REGISTERED_CLASSES.entrySet())
+            {
+                List<String> paths = entry.getValue();
+                Class<? extends ConfiguredObject> objClass = entry.getKey();
+                writer.println("<tr>");
+                writer.println("<td class=\"type\" rowspan=\""+ paths.size()+"\"><a href=\"latest/"+ objClass.getSimpleName().toLowerCase()+"\">"+objClass.getSimpleName()+"</a></td>");
+                writer.println("<td class=\"path\">" + paths.get(0) + "</td>");
+                writer.println("<td class=\"description\" rowspan=\""+ paths.size()+"\">"+
+                               objClass.getAnnotation(ManagedObject.class).description()+"</td>");
+                writer.println("</tr>");
+                for(int i = 1; i < paths.size(); i++)
+                {
+                    writer.println("<tr>");
+                    writer.println("<td class=\"path\">" + paths.get(i) + "</td>");
+                    writer.println("</tr>");
+                }
+
+            }
+            writer.println("</tbody>");
+            writer.println("</table>");
+
+        }
+        else
+        {
+            writeCategoryDescription(writer);
+            writeUsage(writer, request);
+            writeTypes(writer);
+            writeAttributes(writer);
+        }
+
         writeFoot(writer);
     }
 
@@ -101,7 +157,7 @@ public class ApiDocsServlet extends AbstractServlet
         writer.println("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"");
         writer.println("\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">");
         writer.println("<html>");
-        writer.println("<body>");
+
 
     }
 
@@ -109,16 +165,35 @@ public class ApiDocsServlet extends AbstractServlet
     {
         writer.println("<head>");
         writer.println("<link rel=\"stylesheet\" type=\"text/css\" href=\"/css/apidocs.css\">");
+        writeTitle(writer);
+
+        writer.println("</head>");
+        writer.println("<body>");
+    }
+
+    private void writeTitle(final PrintWriter writer)
+    {
         writer.print("<title>");
-        writer.print("Qpid API : " + getConfiguredClass().getSimpleName());
+        if(_hierarchy.length == 0)
+        {
+            writer.print("Qpid API");
+        }
+        else
+        {
+            writer.print("Qpid API: " + getConfiguredClass().getSimpleName());
+        }
         writer.println("</title>");
+    }
 
-        writer.println("</head>");
+    private void writeCategoryDescription(PrintWriter writer)
+    {
+        writer.println("<h1>"+getConfiguredClass().getSimpleName()+"</h1>");
+        writer.println(getConfiguredClass().getAnnotation(ManagedObject.class).description());
     }
 
     private void writeUsage(final PrintWriter writer, final HttpServletRequest request)
     {
-        writer.println("<a name=\"usage\"><h1>Usage</h1></a>");
+        writer.println("<a name=\"usage\"><h2>Usage</h2></a>");
         writer.println("<table class=\"usage\">");
         writer.println("<tbody>");
         writer.print("<tr><th class=\"operation\">Read</th><td class=\"method\">GET</td><td class=\"path\">" + request.getServletPath()
@@ -141,22 +216,19 @@ public class ApiDocsServlet extends AbstractServlet
             writer.print("/&lt;" + category.getSimpleName().toLowerCase() + " name or id&gt;");
         }
 
-        if(_hierarchy.length>1)
+        writer.print(
+                "<tr><th class=\"operation\">Create</th><td class=\"method\">PUT or POST</td><td class=\"path\">"
+                + request.getServletPath().replace("apidocs", "api"));
+        for (int i = 0; i < _hierarchy.length - 1; i++)
         {
-            writer.print(
-                    "<tr><th class=\"operation\">Create</th><td class=\"method\">PUT or POST</td><td class=\"path\">"
-                    + request.getServletPath().replace("apidocs", "api"));
-            for (int i = 0; i < _hierarchy.length - 1; i++)
-            {
-                writer.print("/&lt;" + _hierarchy[i].getSimpleName().toLowerCase() + " name or id&gt;");
-            }
+            writer.print("/&lt;" + _hierarchy[i].getSimpleName().toLowerCase() + " name or id&gt;");
+        }
 
-            writer.print("<tr><th class=\"operation\">Delete</th><td class=\"method\">DELETE</td><td class=\"path\">"
-                         + request.getServletPath().replace("apidocs", "api"));
-            for (final Class<? extends ConfiguredObject> category : _hierarchy)
-            {
-                writer.print("/&lt;" + category.getSimpleName().toLowerCase() + " name or id&gt;");
-            }
+        writer.print("<tr><th class=\"operation\">Delete</th><td class=\"method\">DELETE</td><td class=\"path\">"
+                     + request.getServletPath().replace("apidocs", "api"));
+        for (final Class<? extends ConfiguredObject> category : _hierarchy)
+        {
+            writer.print("/&lt;" + category.getSimpleName().toLowerCase() + " name or id&gt;");
         }
 
         writer.println("</tbody>");
diff --git a/qpid/java/broker-plugins/management-http/src/main/java/resources/css/apidocs.css b/qpid/java/broker-plugins/management-http/src/main/java/resources/css/apidocs.css
index f79eaaaa50..5baecf7c02 100644
--- a/qpid/java/broker-plugins/management-http/src/main/java/resources/css/apidocs.css
+++ b/qpid/java/broker-plugins/management-http/src/main/java/resources/css/apidocs.css
@@ -46,11 +46,40 @@ table.attributes td.name {
     width: 20em;
 }
 
-
 table.attributes td.type {
     width: 7em;
 }
 
+table.api td,th {
+    vertical-align: top;
+}
+
+
+table.api td.type {
+    width: 12em;
+}
+
+
+table.api td.path {
+    width: 20em;
+}
+
+
+table.api td.description {
+    width: 25em;
+}
+
+table.api a:link {
+    color: #333;
+    text-decoration: none;
+}
+
+table.api a:visited {
+    color: #666;
+    text-decoration: none;
+}
+
+
 div.restriction {
     border-bottom: 1px dotted #666;
     display: inline;
-- 
cgit v1.2.1