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

7 files changed, 186 insertions, 45 deletions

diff --git a/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Exchange.java b/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Exchange.java
index 52c40fe123..00e78b46e0 100644
--- a/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Exchange.java
+++ b/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Exchange.java
@@ -25,9 +25,14 @@ import java.util.Map;
 
 import org.apache.qpid.server.message.MessageDestination;
 
-@ManagedObject
+@ManagedObject( description = Exchange.CLASS_DESCRIPTION )
 public interface Exchange<X extends Exchange<X>> extends ConfiguredObject<X>, MessageDestination
 {
+    String CLASS_DESCRIPTION = "<p>An Exchange is a named entity within the Virtualhost which receives messages from "
+                               + "producers and routes them to matching Queues within the Virtualhost.</p>"
+                               + "<p>The server provides a set of exchange types with each exchange type implementing "
+                               + "a different routing algorithm.</p>";
+
     String ALTERNATE_EXCHANGE                   = "alternateExchange";
 
     // Attributes
diff --git a/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Port.java b/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Port.java
index 999a3594b4..a2b052e56a 100644
--- a/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Port.java
+++ b/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Port.java
@@ -25,9 +25,17 @@ import java.util.Set;
 
 import com.google.common.util.concurrent.ListenableFuture;
 
-@ManagedObject
+@ManagedObject( description = Port.CLASS_DESCRIPTION )
 public interface Port<X extends Port<X>> extends ConfiguredObject<X>
 {
+    String CLASS_DESCRIPTION = "<p>The Broker supports configuration of Ports to specify the particular AMQP messaging "
+                               + "and HTTP/JMX management connectivity it offers for use.</p>"
+                               + "<p>Each Port is configured with the particular Protocols and Transports it supports, "
+                               + "as well as the Authentication Provider to be used to authenticate connections. Where "
+                               + "SSL is in use, the Port configuration also defines which Keystore to use and (where "
+                               + "supported) which TrustStore(s) and whether Client Certificates should be "
+                               + "requested/required.</p>";
+
     String BINDING_ADDRESS                      = "bindingAddress";
     String PORT                                 = "port";
     String PROTOCOLS                            = "protocols";
diff --git a/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Queue.java b/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Queue.java
index ba1f262cfc..fe3c8de4ac 100644
--- a/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Queue.java
+++ b/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/Queue.java
@@ -27,9 +27,14 @@ import java.util.Map;
 import org.apache.qpid.server.queue.QueueEntryVisitor;
 import org.apache.qpid.server.store.MessageDurability;
 
-@ManagedObject( defaultType = "standard" )
+@ManagedObject( defaultType = "standard", description = Queue.CLASS_DESCRIPTION )
 public interface Queue<X extends Queue<X>> extends ConfiguredObject<X>
 {
+    String CLASS_DESCRIPTION = "<p>Queues are named entities within a VirtualHost that hold/buffer messages for later "
+                               + "delivery to consumer applications. Consumers subscribe to a queue in order to receive "
+                               + "messages for it.</p>"
+                               + "<p>The Broker supports different queue types, each with different delivery semantics. "
+                               + "It also allows for messages on a queue to be treated as a group.</p>";
 
     String ALERT_REPEAT_GAP = "alertRepeatGap";
     String ALERT_THRESHOLD_MESSAGE_AGE = "alertThresholdMessageAge";
diff --git a/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/VirtualHost.java b/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/VirtualHost.java
index 24e8900b9e..843b300413 100644
--- a/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/VirtualHost.java
+++ b/qpid/java/broker-core/src/main/java/org/apache/qpid/server/model/VirtualHost.java
@@ -31,9 +31,15 @@ import org.apache.qpid.server.message.MessageInstance;
 import org.apache.qpid.server.model.port.AmqpPort;
 import org.apache.qpid.server.store.MessageStore;
 
-@ManagedObject( defaultType = "ProvidedStore")
+@ManagedObject( defaultType = "ProvidedStore", description = VirtualHost.CLASS_DESCRIPTION)
 public interface VirtualHost<X extends VirtualHost<X, Q, E>, Q extends Queue<?>, E extends Exchange<?> > extends ConfiguredObject<X>
 {
+    String CLASS_DESCRIPTION = "<p>A virtualhost is a namespace in which messaging is performed. Virtualhosts are "
+                               + "independent; the messaging goes on a within a virtualhost is independent of any "
+                               + "messaging that goes on in another virtualhost. For instance, a queue named <i>foo</i> "
+                               + "defined in one virtualhost is completely independent of a queue named <i>foo</i> in "
+                               + "another virtualhost.</p>"
+                               + "<p>A virtualhost is backed by storage which is used to store the messages.</p>";
 
     String QUEUE_DEAD_LETTER_QUEUE_ENABLED            = "queue.deadLetterQueueEnabled";
 
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;