Add personalrank and neighborrank RESTful API

hugegraph-api/pom.xml

@@ -86,7 +86,7 @@
                             </addDefaultSpecificationEntries>
                         </manifest>
                         <manifestEntries>
-                            <Implementation-Version>0.37.0.0</Implementation-Version>
+                            <Implementation-Version>0.38.0.0</Implementation-Version>
                         </manifestEntries>
                     </archive>
                 </configuration>

hugegraph-api/src/main/java/com/baidu/hugegraph/api/traversers/EdgesAPI.java

@@ -93,7 +93,7 @@ public String shards(@Context GraphManager manager,
         HugeGraph g = graph(manager, graph);
         List<Shard> shards = g.graphTransaction()
                               .metadata(HugeType.EDGE_OUT, "splits", splitSize);
-        return manager.serializer(g).writeShards(shards);
+        return manager.serializer(g).writeList("shards", shards);
     }
 
     @GET

hugegraph-api/src/main/java/com/baidu/hugegraph/api/traversers/KneighborAPI.java

@@ -80,6 +80,6 @@ public String get(@Context GraphManager manager,
         HugeTraverser traverser = new HugeTraverser(g);
         Set<Id> ids = traverser.kneighbor(source, dir, edgeLabel, depth,
                                           degree, limit);
-        return manager.serializer(g).writeIds("vertices", ids);
+        return manager.serializer(g).writeList("vertices", ids);
     }
 }

hugegraph-api/src/main/java/com/baidu/hugegraph/api/traversers/KoutAPI.java

@@ -85,6 +85,6 @@ public String get(@Context GraphManager manager,
         HugeTraverser traverser = new HugeTraverser(g);
         Set<Id> ids = traverser.kout(sourceId, dir, edgeLabel, depth,
                                      nearest, degree, capacity, limit);
-        return manager.serializer(g).writeIds("vertices", ids);
+        return manager.serializer(g).writeList("vertices", ids);
     }
 }

hugegraph-api/src/main/java/com/baidu/hugegraph/api/traversers/NeighborRankAPI.java

@@ -0,0 +1,159 @@
+/*
+ * Copyright 2017 HugeGraph Authors
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with this
+ * work for additional information regarding copyright ownership. The ASF
+ * licenses this file to You under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.baidu.hugegraph.api.traversers;
+
+import static com.baidu.hugegraph.traversal.algorithm.HugeTraverser.DEFAULT_CAPACITY;
+import static com.baidu.hugegraph.traversal.algorithm.HugeTraverser.DEFAULT_DEGREE;
+import static com.baidu.hugegraph.traversal.algorithm.HugeTraverser.DEFAULT_PATHS_LIMIT;
+import static com.baidu.hugegraph.traversal.algorithm.HugeTraverser.NO_LIMIT;
+import static com.baidu.hugegraph.traversal.algorithm.NeighborRankTraverser.MAX_STEPS;
+import static com.baidu.hugegraph.traversal.algorithm.NeighborRankTraverser.MAX_TOP;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import javax.inject.Singleton;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.Context;
+
+import org.slf4j.Logger;
+
+import com.baidu.hugegraph.HugeGraph;
+import com.baidu.hugegraph.api.API;
+import com.baidu.hugegraph.api.graph.VertexAPI;
+import com.baidu.hugegraph.backend.id.Id;
+import com.baidu.hugegraph.core.GraphManager;
+import com.baidu.hugegraph.schema.EdgeLabel;
+import com.baidu.hugegraph.server.RestServer;
+import com.baidu.hugegraph.traversal.algorithm.NeighborRankTraverser;
+import com.baidu.hugegraph.type.define.Directions;
+import com.baidu.hugegraph.util.E;
+import com.baidu.hugegraph.util.Log;
+import com.codahale.metrics.annotation.Timed;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+@Path("graphs/{graph}/traversers/neighborrank")
+@Singleton
+public class NeighborRankAPI extends API {
+
+    private static final Logger LOG = Log.logger(RestServer.class);
+
+    @POST
+    @Timed
+    @Produces(APPLICATION_JSON_WITH_CHARSET)
+    public String neighborRank(@Context GraphManager manager,
+                               @PathParam("graph") String graph,
+                               RankRequest request) {
+        E.checkArgumentNotNull(request, "The rank request body can't be null");
+        E.checkArgumentNotNull(request.source,
+                               "The source of rank request can't be null");
+        E.checkArgument(request.steps != null && !request.steps.isEmpty(),
+                        "The steps of rank request can't be empty");
+        E.checkArgument(request.steps.size() <= MAX_STEPS,
+                        "The steps length of rank request can't exceed %s",
+                        MAX_STEPS);
+        E.checkArgument(request.alpha > 0 && request.alpha <= 1.0,
+                        "The alpha of rank request must belong (0, 1], " +
+                        "but got '%s'", request.alpha);
+
+        LOG.debug("Graph [{}] get neighbor rank from '{}' with steps '{}', " +
+                  "alpha '{}' and capacity '{}'", graph, request.source,
+                  request.steps, request.alpha, request.capacity);
+
+        Id sourceId = VertexAPI.checkAndParseVertexId(request.source);
+        HugeGraph g = graph(manager, graph);
+
+        List<NeighborRankTraverser.Step> steps = steps(g, request);
+        NeighborRankTraverser traverser;
+        traverser = new NeighborRankTraverser(g, request.alpha,
+                                              request.capacity);
+        List<Map<Id, Double>> ranks = traverser.neighborRank(sourceId, steps);
+        return manager.serializer(g).writeList("ranks", ranks);
+    }
+
+    private static List<NeighborRankTraverser.Step> steps(HugeGraph graph,
+                                                          RankRequest req) {
+        List<NeighborRankTraverser.Step> steps = new ArrayList<>();
+        for (Step step : req.steps) {
+            steps.add(step.jsonToStep(graph));
+        }
+        return steps;
+    }
+
+    private static class RankRequest {
+
+        @JsonProperty("source")
+        private String source;
+        @JsonProperty("steps")
+        private List<Step> steps;
+        @JsonProperty("alpha")
+        private double alpha;
+        @JsonProperty("capacity")
+        public long capacity = Long.valueOf(DEFAULT_CAPACITY);
+
+        @Override
+        public String toString() {
+            return String.format("RankRequest{source=%s,steps=%s,alpha=%s," +
+                                 "capacity=%s}", this.source, this.steps,
+                                 this.alpha, this.capacity);
+        }
+    }
+
+    private static class Step {
+
+        @JsonProperty("direction")
+        public Directions direction;
+        @JsonProperty("labels")
+        public List<String> labels;
+        @JsonProperty("degree")
+        public long degree = Long.valueOf(DEFAULT_DEGREE);
+        @JsonProperty("top")
+        public int top = Integer.valueOf(DEFAULT_PATHS_LIMIT);
+
+        @Override
+        public String toString() {
+            return String.format("Step{direction=%s,labels=%s,degree=%s," +
+                                 "top=%s}", this.direction, this.labels,
+                                 this.degree, this.top);
+        }
+
+        private NeighborRankTraverser.Step jsonToStep(HugeGraph graph) {
+            E.checkArgument(this.degree > 0 || this.degree == NO_LIMIT,
+                            "The degree must be > 0, but got: %s",
+                            this.degree);
+            E.checkArgument(this.top > 0 && this.top <= MAX_TOP,
+                            "The top of each layer cannot exceed %s", MAX_TOP);
+            Map<Id, String> labelIds = new HashMap<>();
+            if (this.labels != null) {
+                for (String label : this.labels) {
+                    EdgeLabel el = graph.edgeLabel(label);
+                    labelIds.put(el.id(), label);
+                }
+            }
+            return new NeighborRankTraverser.Step(this.direction, labelIds,
+                                                  this.degree, this.top);
+        }
+    }
+}

hugegraph-api/src/main/java/com/baidu/hugegraph/api/traversers/PersonalRankAPI.java

@@ -0,0 +1,145 @@
+/*
+ * Copyright 2017 HugeGraph Authors
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with this
+ * work for additional information regarding copyright ownership. The ASF
+ * licenses this file to You under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.baidu.hugegraph.api.traversers;
+
+import static com.baidu.hugegraph.traversal.algorithm.HugeTraverser.DEFAULT_DEGREE;
+import static com.baidu.hugegraph.traversal.algorithm.HugeTraverser.DEFAULT_LIMIT;
+import static com.baidu.hugegraph.traversal.algorithm.HugeTraverser.NO_LIMIT;
+
+import java.util.Map;
+
+import javax.inject.Singleton;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.Context;
+
+import org.slf4j.Logger;
+
+import com.baidu.hugegraph.HugeGraph;
+import com.baidu.hugegraph.api.API;
+import com.baidu.hugegraph.api.graph.VertexAPI;
+import com.baidu.hugegraph.backend.id.Id;
+import com.baidu.hugegraph.core.GraphManager;
+import com.baidu.hugegraph.server.RestServer;
+import com.baidu.hugegraph.traversal.algorithm.PersonalRankTraverser;
+import com.baidu.hugegraph.util.CollectionUtil;
+import com.baidu.hugegraph.util.E;
+import com.baidu.hugegraph.util.InsertionOrderUtil;
+import com.baidu.hugegraph.util.Log;
+import com.codahale.metrics.annotation.Timed;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+@Path("graphs/{graph}/traversers/personalrank")
+@Singleton
+public class PersonalRankAPI extends API {
+
+    private static final Logger LOG = Log.logger(RestServer.class);
+
+    @POST
+    @Timed
+    @Produces(APPLICATION_JSON_WITH_CHARSET)
+    public String personalRank(@Context GraphManager manager,
+                               @PathParam("graph") String graph,
+                               RankRequest request) {
+        E.checkArgumentNotNull(request, "The rank request body can't be null");
+        E.checkArgument(request.source != null,
+                        "The source vertex id of rank request can't be null");
+        E.checkArgument(request.label != null,
+                        "The edge label of rank request can't be null");
+        E.checkArgument(request.alpha > 0 && request.alpha <= 1.0,
+                        "The alpha of rank request must belong (0, 1], " +
+                        "but got '%s'", request.alpha);
+        E.checkArgument(request.degree > 0 || request.degree == NO_LIMIT,
+                        "The degree of rank request must be > 0, but got: %s",
+                        request.degree);
+        E.checkArgument(request.limit > 0 || request.limit == NO_LIMIT,
+                        "The limit of rank request must be > 0, but got: %s",
+                        request.limit);
+        E.checkArgument(request.maxDepth >= 1,
+                        "The max depth of rank request must >= 1, but got '%s'",
+                        request.maxDepth);
+
+        LOG.debug("Graph [{}] get personal rank from '{}' with " +
+                  "edge label '{}', alpha '{}', degree '{}', " +
+                  "max depth '{}' and sorted '{}'",
+                  graph, request.source, request.label, request.alpha,
+                  request.degree, request.maxDepth, request.sorted);
+
+        Id sourceId = VertexAPI.checkAndParseVertexId(request.source);
+        HugeGraph g = graph(manager, graph);
+
+        PersonalRankTraverser traverser;
+        traverser = new PersonalRankTraverser(g, request.alpha, request.degree,
+                                              request.maxDepth);
+        Map<Id, Double> ranks = traverser.personalRank(sourceId, request.label,
+                                                       request.withLabel);
+        ranks = topN(ranks, request.sorted, request.limit);
+        return manager.serializer(g).writeMap(ranks);
+    }
+
+    private static Map<Id, Double> topN(Map<Id, Double> ranks,
+                                        boolean sorted, long limit) {
+        if (sorted) {
+            ranks = CollectionUtil.sortByValue(ranks, false);
+        }
+        Map<Id, Double> results = InsertionOrderUtil.newMap();
+        long count = 0;
+        for (Map.Entry<Id, Double> entry : ranks.entrySet()) {
+            results.put(entry.getKey(), entry.getValue());
+            if (++count >= limit) {
+                break;
+            }
+        }
+        return results;
+    }
+
+    private static class RankRequest {
+
+        @JsonProperty("source")
+        private String source;
+        @JsonProperty("label")
+        private String label;
+        @JsonProperty("alpha")
+        private double alpha;
+        @JsonProperty("degree")
+        private long degree = Long.valueOf(DEFAULT_DEGREE);
+        @JsonProperty("limit")
+        private long limit = Long.valueOf(DEFAULT_LIMIT);
+        @JsonProperty("max_depth")
+        private int maxDepth;
+        @JsonProperty("with_label")
+        private PersonalRankTraverser.WithLabel withLabel =
+                PersonalRankTraverser.WithLabel.BOTH_LABEL;
+        @JsonProperty("sorted")
+        private boolean sorted = true;
+
+        @Override
+        public String toString() {
+            return String.format("RankRequest{source=%s,label=%s," +
+                                 "alpha=%s,degree=%s,limit=%s, maxDepth=%s," +
+                                 "withLabel=%s,sorted=%s}",
+                                 this.source, this.label, this.alpha,
+                                 this.degree, this.limit, this.maxDepth,
+                                 this.withLabel, this.sorted);
+        }
+    }
+}

hugegraph-api/src/main/java/com/baidu/hugegraph/api/traversers/ShortestPathAPI.java

@@ -85,6 +85,6 @@ public String get(@Context GraphManager manager,
         List<Id> path = traverser.shortestPath(sourceId, targetId, dir,
                                                edgeLabel, depth, degree,
                                                skipDegree, capacity);
-        return manager.serializer(g).writeIds("path", path);
+        return manager.serializer(g).writeList("path", path);
     }
 }

hugegraph-api/src/main/java/com/baidu/hugegraph/api/traversers/VerticesAPI.java

@@ -93,7 +93,7 @@ public String shards(@Context GraphManager manager,
         HugeGraph g = graph(manager, graph);
         List<Shard> shards = g.graphTransaction()
                               .metadata(HugeType.VERTEX, "splits", splitSize);
-        return manager.serializer(g).writeShards(shards);
+        return manager.serializer(g).writeList("shards", shards);
     }
 
     @GET

hugegraph-api/src/main/java/com/baidu/hugegraph/serializer/JsonSerializer.java

@@ -61,7 +61,13 @@ public static JsonSerializer instance() {
         return INSTANCE;
     }
 
-    private String writeList(String label, List<?> list) {
+    @Override
+    public String writeMap(Map<?, ?> map) {
+        return JsonUtil.toJson(map);
+    }
+
+    @Override
+    public String writeList(String label, Collection<?> list) {
         try (ByteArrayOutputStream out = new ByteArrayOutputStream(LBUF_SIZE)) {
             out.write(String.format("{\"%s\": ", label).getBytes(API.CHARSET));
             out.write(JsonUtil.toJson(list).getBytes(API.CHARSET));
@@ -197,15 +203,6 @@ public String writeEdges(Iterator<Edge> edges, boolean paging) {
         return this.writeIterator("edges", edges, paging);
     }
 
-    @Override
-    public String writeIds(String name, Collection<Id> ids) {
-        if (ids instanceof List) {
-            return this.writeList(name, (List<?>) ids);
-        } else {
-            return this.writeList(name, new ArrayList<>(ids));
-        }
-    }
-
     @Override
     public String writePaths(String name, Collection<HugeTraverser.Path> paths,
                              boolean withCrossPoint,
@@ -243,9 +240,4 @@ public String writeCrosspoints(CrosspointsPaths paths,
                                   "vertices", iterator);
         return JsonUtil.toJson(results);
     }
-
-    @Override
-    public String writeShards(List<Shard> shards) {
-        return this.writeList("shards", shards);
-    }
 }