Changeset 6091 in josm for trunk/src/org/openstreetmap/josm

Timestamp:

2013-07-29T18:56:51+02:00 (11 years ago)

Author:

akks

Message:

see #8612, #8228: remote control - add examples [patch by simon04, parts], add /feature request to detect commands

Location:

trunk/src/org/openstreetmap/josm/io/remotecontrol

Files:

• RequestProcessor.java (modified) (6 diffs, 1 prop)
• handler/AddNodeHandler.java (modified) (1 diff, 1 prop)
• handler/AddWayHandler.java (modified) (1 diff)
• handler/FeaturesHandler.java (copied) (copied from trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/VersionHandler.java ) (5 diffs, 1 prop)
• handler/ImageryHandler.java (modified) (4 diffs, 1 prop)
• handler/ImportHandler.java (modified) (1 diff, 1 prop)
• handler/LoadAndZoomHandler.java (modified) (1 diff, 1 prop)
• handler/LoadObjectHandler.java (modified) (1 diff)
• handler/OpenFileHandler.java (modified) (1 diff)
• handler/RequestHandler.java (modified) (6 diffs, 1 prop)
• handler/VersionHandler.java (modified) (1 diff, 1 prop)

trunk/src/org/openstreetmap/josm/io/remotecontrol/RequestProcessor.java

@@ -8 +8 @@
 import java.io.OutputStream;
 import java.io.OutputStreamWriter;
+import java.io.PrintWriter;
+import java.io.StringWriter;
 import java.io.Writer;
 import java.net.Socket;
@@ -17 +19 @@
 import java.util.StringTokenizer;
 import java.util.TreeMap;
+import java.util.logging.Level;
+import java.util.logging.Logger;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -22 +26 @@
 import org.openstreetmap.josm.io.remotecontrol.handler.AddNodeHandler;
 import org.openstreetmap.josm.io.remotecontrol.handler.AddWayHandler;
+import org.openstreetmap.josm.io.remotecontrol.handler.FeaturesHandler;
 import org.openstreetmap.josm.io.remotecontrol.handler.ImageryHandler;
 import org.openstreetmap.josm.io.remotecontrol.handler.ImportHandler;
@@ -127 +132 @@
         addRequestHandlerClass(LoadObjectHandler.command, LoadObjectHandler.class, true);
         addRequestHandlerClass(OpenFileHandler.command, OpenFileHandler.class, true);
+        addRequestHandlerClass(FeaturesHandler.command, FeaturesHandler.class, true);
     }
 
@@ -204 +210 @@
             Class<? extends RequestHandler> handlerClass = handlers.get(command);
             if (handlerClass == null) {
-                // no handler found
-                StringBuilder usage = new StringBuilder(1024);
-                for (Entry<String, Class<? extends RequestHandler>> handler : handlers.entrySet()) {
-                    String[] mandatory = handler.getValue().newInstance().getMandatoryParams();
-                    usage.append("<li>");
-                    usage.append(handler.getKey());
-                    if (mandatory != null) {
-                        usage.append("<br/>mandatory parameter: ").append(Utils.join(", ", Arrays.asList(mandatory)));
-                    }
-                    usage.append("</li>");
-                }
+                String usage = getUsageAsHtml();
                 String websiteDoc = "http://josm.openstreetmap.de/wiki/Help/Preferences/RemoteControl";
                 String help = "No command specified! The following commands are available:<ul>"
@@ -365 +361 @@
             out.write("\r\n");
     }
+    
+    public static String getHandlersInfoAsJSON() {
+        StringBuilder r = new StringBuilder();
+        boolean first = true;
+        r.append("[");
+        
+        for (Entry<String, Class<? extends RequestHandler>> p : handlers.entrySet()) {
+            if (first) {
+                first = false;
+            } else {
+                r.append(", ");
+            }
+            r.append(getHanldlerInfoAsJSON(p.getKey()));
+        }
+        r.append("]");
+
+        return r.toString();
+    }
+
+    public static String getHanldlerInfoAsJSON(String cmd) {
+        StringWriter w = new StringWriter();
+        PrintWriter r = new PrintWriter(w);
+        RequestHandler handler = null;
+        try {
+            Class c = handlers.get(cmd);
+            if (c==null) return null;
+            handler = handlers.get(cmd).newInstance();
+        } catch (Exception ex) {
+            ex.printStackTrace();
+            return null;
+        }
+        if (handler==null) return null;
+
+        r.printf("{ \"request\" : \"%s\"", cmd);
+        r.append(", \"parameters\" : [");
+
+        String params[] = handler.getMandatoryParams();
+        if (params != null) {
+            for (int i = 0; i < params.length; i++) {
+                if (i == 0) {
+                    r.append('\"');
+                } else {
+                    r.append(", \"");
+                }
+                r.append(params[i]).append('\"');
+            }
+        }
+        r.append("], \"optional\" : [");
+        String optional[] = handler.getOptionalParams();
+        if (optional != null) {
+            for (int i = 0; i < optional.length; i++) {
+                if (i == 0) {
+                    r.append('\"');
+                } else {
+                    r.append(", \"");
+                }
+                r.append(optional[i]).append('\"');
+            }
+        }
+        
+        r.append("], \"examples\" : [");
+        String examples[] = handler.getUsageExamples();
+        if (examples != null) {
+            for (int i = 0; i < examples.length; i++) {
+                if (i == 0) {
+                    r.append('\"');
+                } else {
+                    r.append(", \"");
+                }
+                r.append(examples[i]).append('\"');
+            }
+        }
+        r.append("]}");
+        try {
+            return w.toString();
+        } finally {
+            try {
+                w.close();
+            } catch (IOException ex) {
+            }
+        }
+    }
+
+
+    /**
+     * Reports HTML message with the description of all available commands
+     * @return
+     * @throws IllegalAccessException
+     * @throws InstantiationException 
+     */
+    public static String getUsageAsHtml() throws IllegalAccessException, InstantiationException {
+        // no handler found
+        StringBuilder usage = new StringBuilder(1024);
+        for (Entry<String, Class<? extends RequestHandler>> handler : handlers.entrySet()) {
+            RequestHandler sample = handler.getValue().newInstance();
+            String[] mandatory = sample.getMandatoryParams();
+            String[] optional = sample.getOptionalParams();
+            String[] examples = sample.getUsageExamples();
+            usage.append("<li>");
+            usage.append(handler.getKey());
+            if (mandatory != null) {
+                usage.append("<br/>mandatory parameters: ").append(Utils.join(", ", Arrays.asList(mandatory)));
+            }
+            if (optional != null) {
+                usage.append("<br/>optional parameters: ").append(Utils.join(", ", Arrays.asList(optional)));
+            }
+            if (examples != null) {
+                usage.append("<br/>examples: ");
+                for (String ex: examples) {
+                    usage.append("<br/> <a href=\"http://localhost:8111"+ex+"\">"+ex+"</a>");
+                }
+            }
+            usage.append("</li>");
+        }
+        return usage.toString();
+    }
 }

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/AddNodeHandler.java

@@ -44 +44 @@
         return new String[] { "lat", "lon" };
     }
+    
+    @Override
+    public String[] getOptionalParams()
+    {
+        return new String[] { "addtags" };
+    }
 
+    @Override
+    public String[] getUsageExamples() {
+        return new String[] {
+            "/add_node?lat=11&lon=22",
+            "/add_node?lon=13.3&lat=53.2&addtags=natural=tree|name=%20%20%20==Great%20Oak==" 
+        };
+    }
+    
     @Override
     public String getPermissionMessage() {

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/AddWayHandler.java

@@ -46 +46 @@
         return new String[]{"way"};
     }
+    
+    @Override
+    public String[] getOptionalParams() {
+        return new String[] { "addtags" };
+    }
 
+    @Override
+    public String[] getUsageExamples() {
+        return new String[] {
+            "/add_way?way=53.2,13.3;53.3,13.3;53.3,13.2",
+            "/add_way?&addtags=building=yes&way=45.437213,-2.810792;45.437988,-2.455983;45.224080,-2.455036;45.223302,-2.809845;45.437213,-2.810792"
+        };
+    }
+    
     @Override
     protected void handleRequest() throws RequestHandlerErrorException, RequestHandlerBadRequestException {

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/FeaturesHandler.java

@@ -2 +2 @@
 package org.openstreetmap.josm.io.remotecontrol.handler;
 
+import org.openstreetmap.josm.Main;
 import static org.openstreetmap.josm.tools.I18n.tr;
 
@@ -8 +9 @@
 
 /**
- * Handler for version request.
+ * Reports avalable commands, their parameters and examples
+ * @since 6091
  */
-public class VersionHandler extends RequestHandler {
+public class FeaturesHandler extends RequestHandler {
 
     /**
      * The remote control command name used to reply version.
      */
-    public static final String command = "version";
+    public static final String command = "features";
 
     @Override
     protected void handleRequest() throws RequestHandlerErrorException,
             RequestHandlerBadRequestException {
-        content = RequestProcessor.PROTOCOLVERSION;
+        StringBuilder buf = new StringBuilder();
+        String q=args.get("q");
+        if (q!=null) {
+            buf.append("[");
+            boolean first = true;
+            for (String s: q.split("[,\\s]+")) {
+               if (first) {
+                   first = false;
+               } else {
+                   buf.append(", ");
+               }
+               String info = RequestProcessor.getHanldlerInfoAsJSON("/"+s);
+               if (info!=null) {
+                   buf.append(info);
+               } else {
+                   Main.warn("Unknown handler {0} passed to /features request", s);
+               }
+            }
+            buf.append("]");
+        } else {
+            buf.append(RequestProcessor.getHandlersInfoAsJSON());
+        }
+            
+        content = buf.toString();
         contentType = "application/json";
         if (args.containsKey("jsonp")) {
@@ -29 +54 @@
     @Override
     public String getPermissionMessage() {
-        return tr("Remote Control has been asked to report its protocol version. This enables web sites to detect a running JOSM.");
+        return tr("Remote Control has been asked to report its supported features. This enables web sites to guess a running JOSM version");
     }
 
@@ -41 +66 @@
         return null;
     }
+    
+    @Override
+    public String[] getOptionalParams() {
+        return new String[]{"jsonp", "q"};
+    }
 
     @Override
@@ -46 +76 @@
         // Nothing to do
     }
+
+    @Override
+    public String[] getUsageExamples() {
+        return new String[] {"/features", "/features?q=import,add_node"}; 
+    }
 }

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/ImageryHandler.java

@@ -2 +2 @@
 package org.openstreetmap.josm.io.remotecontrol.handler;
 
+import java.util.Arrays;
 import static org.openstreetmap.josm.tools.I18n.tr;
 
@@ -11 +12 @@
 import org.openstreetmap.josm.gui.util.GuiHelper;
 import org.openstreetmap.josm.io.remotecontrol.PermissionPrefWithDefault;
+import org.openstreetmap.josm.tools.Utils;
 
 /**
@@ -32 +34 @@
     public String[] getMandatoryParams() {
         return new String[]{"url"};
+    }
+    
+    @Override
+    public String[] getOptionalParams() {
+        return new String[] { "title", "type", "cookies", "min_zoom", "max_zoom"};
     }
 
@@ -100 +107 @@
         this.args = args;
     }
-
+    
     @Override
     protected void validateRequest() throws RequestHandlerBadRequestException {
         // Nothing to do
     }
+
+    @Override
+    public String[] getUsageExamples() {
+        final String types = Utils.join("|", Utils.transform(Arrays.asList(ImageryInfo.ImageryType.values()), new Utils.Function<ImageryInfo.ImageryType, String>() {
+            @Override
+            public String apply(ImageryInfo.ImageryType x) {
+                return x.getUrlString();
+            }
+        }));
+        return new String[] { "/imagery?title=osm&type=tms&url=http://tile.openstreetmap.org/%7Bzoom%7D/%7Bx%7D/%7By%7D.png",
+            "/imagery?title=landsat&type=wms&url=http://irs.gis-lab.info/?layers=landsat&SRS=%7Bproj%7D&WIDTH=%7Bwidth%7D&HEIGHT=%7Bheight%7D&BBOX=%7Bbbox%7D",
+            "/imagery?title=...&type={"+types+"}&url=....[&cookies=...][&min_zoom=...][&max_zoom=...]"};
+    }
 }

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/ImportHandler.java

@@ -45 +45 @@
         return new String[]{"url"};
     }
+    
+    @Override
+    public String[] getOptionalParams() {
+        return new String[] {"new_layer"};
+    }
 
+    @Override
+    public String[] getUsageExamples() {
+        return new String[] { "/import?urlhttp://josm.openstreetmap.de/browser/josm/trunk/data_nodist/direction-arrows.osm" };
+    }
+    
     @Override
     public String getPermissionMessage() {

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/LoadAndZoomHandler.java

@@ -73 +73 @@
 
     @Override
+    public String[] getOptionalParams()
+    {
+        return new String[] {"new_layer", "addtags", "select", "zoom_mode"};
+    }
+
+    @Override
+    public String[] getUsageExamples() {
+        if (command.equals(myCommand)) {
+            return new String[] { 
+                "/load_and_zoom?addtags=wikipedia:de=Wei%C3%9Fe_Gasse|maxspeed=5&select=way23071688,way23076176,way23076177,&left=13.740&right=13.741&top=51.05&bottom=51.049",
+                "/load_and_zoom?left=8.19&right=8.20&top=48.605&bottom=48.590&select=node413602999&new_layer=true"};
+        } else {
+            return new String[] { 
+                "/zoom?left=8.19&right=8.20&top=48.605&bottom=48.590&select=node413602999"};
+        }
+    }
+    
+    @Override
     protected void handleRequest() throws RequestHandlerErrorException
     {

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/LoadObjectHandler.java

@@ -32 +32 @@
     public String[] getMandatoryParams() {
         return new String[]{"objects"};
+    }
+    
+    @Override
+    public String[] getOptionalParams()
+    {
+        return new String[] {"new_layer", "addtags"};
+    }
+
+    @Override
+    public String[] getUsageExamples() {
+        return new String[] {"/load_object?new_layer=true&objects=w106159509",
+            "/load_object?new_layer=true&objects=r2263653&relation_members=true"
+        };
     }
 

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/OpenFileHandler.java

@@ -25 +25 @@
         return new String[]{"filename"};
     }
+    
+    @Override
+    public String[] getOptionalParams() {
+        return null;
+    }
+
+    @Override
+    public String[] getUsageExamples() {
+        return new String[] {"/open_file?filename=/tmp/test.osm"};
+    }
 
     @Override

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/RequestHandler.java

@@ -7 +7 @@
 import java.net.URLDecoder;
 import java.text.MessageFormat;
+import java.util.Collections;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.LinkedList;
 import java.util.List;
@@ -106 +108 @@
 
     abstract public String[] getMandatoryParams();
+    
+    public String[] getOptionalParams() {
+        return null;
+    }
+     
+    public String[] getUsageExamples() {
+        return null;
+    }
 
     /**
@@ -176 +186 @@
                 String query = req.substring(req.indexOf('?') + 1);
                 if (query.indexOf('#') != -1) {
-                    query = query.substring(0, query.indexOf('#'));
-                }
+                            query = query.substring(0, query.indexOf('#'));
+                        }
                 String[] params = query.split("&", -1);
                 for (String param : params) {
@@ -194 +204 @@
     void checkMandatoryParams() throws RequestHandlerBadRequestException {
         String[] mandatory = getMandatoryParams();
-        if(mandatory == null) return;
-
+        String[] optional = getOptionalParams();
         List<String> missingKeys = new LinkedList<String>();
         boolean error = false;
-        for (String key : mandatory) {
+        if(mandatory != null) for (String key : mandatory) {
             String value = args.get(key);
             if ((value == null) || (value.length() == 0)) {
@@ -206 +215 @@
             }
         }
+        HashSet<String> knownParams = new HashSet<String>();
+        if (mandatory != null) Collections.addAll(knownParams, mandatory);
+        if (optional != null) Collections.addAll(knownParams, optional);
+        for (String par: args.keySet()) {
+            if (!knownParams.contains(par)) {
+                Main.warn("Unknown remote control parameter {0}, skipping it", par);
+            }
+        }
         if (error) {
             throw new RequestHandlerBadRequestException(
@@ -211 +228 @@
                     + Utils.join(", ", missingKeys));
         }
+        
     }
 

trunk/src/org/openstreetmap/josm/io/remotecontrol/handler/VersionHandler.java

@@ -43 +43 @@
 
     @Override
+    public String[] getOptionalParams() {
+        return new String[]{"jsonp"};
+    }
+
+    @Override
     protected void validateRequest() throws RequestHandlerBadRequestException {
         // Nothing to do
     }
+
+    @Override
+    public String[] getUsageExamples() {
+        return new String[] { "/version", "/version?jsonp=test"};
+    }
 }