falcon-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ajayyad...@apache.org
Subject falcon git commit: FALCON-438 Auto generate documentation for REST API. Contributed by Narayan Periwal.
Date Thu, 24 Sep 2015 20:49:50 GMT
Repository: falcon
Updated Branches:
  refs/heads/master 6c8b33fd5 -> 88d105519


FALCON-438 Auto generate documentation for REST API. Contributed by Narayan Periwal.


Project: http://git-wip-us.apache.org/repos/asf/falcon/repo
Commit: http://git-wip-us.apache.org/repos/asf/falcon/commit/88d10551
Tree: http://git-wip-us.apache.org/repos/asf/falcon/tree/88d10551
Diff: http://git-wip-us.apache.org/repos/asf/falcon/diff/88d10551

Branch: refs/heads/master
Commit: 88d1055196d98b9cd81379074f5c5d68f832bc82
Parents: 6c8b33f
Author: Ajay Yadava <ajaynsit@gmail.com>
Authored: Fri Sep 25 00:02:08 2015 +0530
Committer: Ajay Yadava <ajaynsit@gmail.com>
Committed: Fri Sep 25 00:02:08 2015 +0530

----------------------------------------------------------------------
 CHANGES.txt                                     |   2 +
 docs/src/site/twiki/restapi/ResourceList.twiki  |   2 +
 pom.xml                                         |  18 ++
 prism/enunciate.xml                             |  42 ++++
 prism/pom.xml                                   |  21 ++
 .../falcon/resource/admin/AdminResource.java    |  13 ++
 .../metadata/LineageMetadataResource.java       |  35 ++++
 .../metadata/MetadataDiscoveryResource.java     |   8 +
 .../resource/proxy/InstanceManagerProxy.java    | 198 +++++++++++++++++++
 .../proxy/SchedulableEntityManagerProxy.java    | 160 +++++++++++++++
 webapp/pom.xml                                  |   8 +
 11 files changed, 507 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/CHANGES.txt
----------------------------------------------------------------------
diff --git a/CHANGES.txt b/CHANGES.txt
index d8d5a2a..160e9b2 100755
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -11,6 +11,8 @@ Trunk (Unreleased)
     FALCON-1027 Falcon proxy user support(Sowmya Ramesh)
 
   IMPROVEMENTS
+    FALCON-438 Auto generate documentation for REST API(Narayan Periwal via Ajay Yadava)
+
     FALCON-1483 Add Utils to common to support native scheduler(Pallavi Rao via Ajay Yadava)
 
     FALCON-1417 Make validity end date optional for feed / process(Pragya Mittal via Ajay Yadava)

http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/docs/src/site/twiki/restapi/ResourceList.twiki
----------------------------------------------------------------------
diff --git a/docs/src/site/twiki/restapi/ResourceList.twiki b/docs/src/site/twiki/restapi/ResourceList.twiki
index 8dc4a49..ea3e3b6 100644
--- a/docs/src/site/twiki/restapi/ResourceList.twiki
+++ b/docs/src/site/twiki/restapi/ResourceList.twiki
@@ -29,6 +29,8 @@ curl -i --negotiate -u : "http://<HOST>:<PORT>/<PATH>?<PARAM>=..."
 
 See also: [[../Security.twiki][Security in Falcon]]
 
+The current version of the rest api's documentation is also hosted on the Falcon server and Prism Server (in distributed mode) at the url http://<HOST>:<PORT>/docs
+
 ---++ REST Call on Admin Resource
 
 | *Call Type* | *Resource*                                     | *Description*                               |

http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index 646de69..8127b46 100644
--- a/pom.xml
+++ b/pom.xml
@@ -1157,6 +1157,11 @@
                     <artifactId>maven-dependency-plugin</artifactId>
                     <version>2.8</version>
                 </plugin>
+                <plugin>
+                    <groupId>org.codehaus.enunciate</groupId>
+                    <artifactId>maven-enunciate-plugin</artifactId>
+                    <version>1.30.1</version>
+                </plugin>
             </plugins>
         </pluginManagement>
 
@@ -1317,6 +1322,19 @@
             </plugin>
 
             <plugin>
+                <groupId>org.codehaus.enunciate</groupId>
+                <artifactId>maven-enunciate-plugin</artifactId>
+                <version>1.30.1</version>
+                <dependencies>
+                    <dependency>
+                        <groupId>org.codehaus.enunciate</groupId>
+                        <artifactId>enunciate-rt</artifactId>
+                        <version>1.30.1</version>
+                    </dependency>
+                </dependencies>
+            </plugin>
+
+            <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-release-plugin</artifactId>
                 <version>2.4.1</version>

http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/prism/enunciate.xml
----------------------------------------------------------------------
diff --git a/prism/enunciate.xml b/prism/enunciate.xml
new file mode 100644
index 0000000..efa4708
--- /dev/null
+++ b/prism/enunciate.xml
@@ -0,0 +1,42 @@
+<?xml version="1.0"?>
+<!--
+  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.
+-->
+
+<enunciate label="falcon" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xsi:noNamespaceSchemaLocation="http://enunciate.codehaus.org/schemas/enunciate-1.25.xsd">
+    <namespaces>
+        <namespace uri="https://git-wip-us.apache.org/repos/asf/falcon.git" id="falcon"/>
+    </namespaces>
+    <services>
+        <rest defaultRestSubcontext="/api" >
+            <custom-resource-parameter-annotation qualifiedName="org.glassfish.jersey.media.multipart.FormDataParam"/>
+        </rest>
+        <api-import pattern="org.apache.falcon.resource.admin.AdminResource" />
+        <api-import pattern="org.apache.falcon.resource.proxy.InstanceManagerProxy" />
+        <api-import pattern="org.apache.falcon.resource.proxy.SchedulableEntityManagerProxy" />
+        <api-import pattern="org.apache.falcon.resource.metadata.LineageMetadataResource" />
+        <api-import pattern="org.apache.falcon.resource.metadata.MetadataDiscoveryResource" />
+    </services>
+
+    <modules>
+        <docs docsDir="docs" title="Falcon Server REST API"/>
+        <csharp disabled="true"/>
+        <c disabled="true"/>
+        <obj-c disabled="true"></obj-c>
+    </modules>
+</enunciate>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/prism/pom.xml
----------------------------------------------------------------------
diff --git a/prism/pom.xml b/prism/pom.xml
index 6eca0b9..5f12cc0 100644
--- a/prism/pom.xml
+++ b/prism/pom.xml
@@ -167,10 +167,14 @@
                 <artifactId>maven-war-plugin</artifactId>
                 <version>2.4</version>
                 <configuration>
+                    <packagingExcludes>docs/downloads.html</packagingExcludes>
                     <webResources>
                         <resource>
                             <directory>../html5-ui</directory>
 			            </resource>
+                        <resource>
+                            <directory>target/restapi</directory>
+                        </resource>
                     </webResources>
                     <attachClasses>true</attachClasses>
                 </configuration>
@@ -260,6 +264,23 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>org.codehaus.enunciate</groupId>
+                <artifactId>maven-enunciate-plugin</artifactId>
+                <version>1.30.1</version>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>docs</goal>
+                        </goals>
+                        <configuration>
+                            <configFile>enunciate.xml</configFile>
+                            <!-- the directory where to put the docs -->
+                            <docsDir>${project.build.directory}/restapi/docs</docsDir>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 </project>

http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/prism/src/main/java/org/apache/falcon/resource/admin/AdminResource.java
----------------------------------------------------------------------
diff --git a/prism/src/main/java/org/apache/falcon/resource/admin/AdminResource.java b/prism/src/main/java/org/apache/falcon/resource/admin/AdminResource.java
index 50b668c..c83886f 100644
--- a/prism/src/main/java/org/apache/falcon/resource/admin/AdminResource.java
+++ b/prism/src/main/java/org/apache/falcon/resource/admin/AdminResource.java
@@ -43,6 +43,10 @@ import java.util.Properties;
 @Path("admin")
 public class AdminResource {
 
+    /**
+     * Get stack trace of the falcon server.
+     * @return Stack trace of the server.
+     */
     @GET
     @Path("stack")
     @Produces(MediaType.TEXT_PLAIN)
@@ -67,6 +71,10 @@ public class AdminResource {
 
     private PropertyList version;
 
+    /**
+     * Get version of the falcon server.
+     * @return Version of the server.
+     */
     @GET
     @Path("version")
     @Produces({MediaType.TEXT_XML, MediaType.APPLICATION_JSON})
@@ -96,6 +104,11 @@ public class AdminResource {
         return version;
     }
 
+    /**
+     * Get configuration information of the falcon server.
+     * @param type config-type can be build, deploy, startup or runtime
+     * @return Configuration information of the server.
+     */
     @GET
     @Path("config/{type}")
     @Produces({MediaType.TEXT_XML, MediaType.APPLICATION_JSON})

http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/prism/src/main/java/org/apache/falcon/resource/metadata/LineageMetadataResource.java
----------------------------------------------------------------------
diff --git a/prism/src/main/java/org/apache/falcon/resource/metadata/LineageMetadataResource.java b/prism/src/main/java/org/apache/falcon/resource/metadata/LineageMetadataResource.java
index d595221..8c5346f 100644
--- a/prism/src/main/java/org/apache/falcon/resource/metadata/LineageMetadataResource.java
+++ b/prism/src/main/java/org/apache/falcon/resource/metadata/LineageMetadataResource.java
@@ -79,6 +79,7 @@ public class LineageMetadataResource extends AbstractMetadataResource {
      *
      * GET http://host/metadata/lineage/serialize
      * graph.getVertices();
+     * @return Serialize graph to a file configured using *.falcon.graph.serialize.path in Custom startup.properties.
      */
     @GET
     @Path("/serialize")
@@ -96,6 +97,11 @@ public class LineageMetadataResource extends AbstractMetadataResource {
     }
 
 
+    /**
+     * It returns the graph depicting the relationship between the various processes and feeds in a given pipeline.
+     * @param pipeline Name of the pipeline
+     * @return It returns a json graph
+     */
     @GET
     @Path("/entities")
     @Produces({MediaType.APPLICATION_JSON})
@@ -138,6 +144,7 @@ public class LineageMetadataResource extends AbstractMetadataResource {
      *
      * GET http://host/metadata/lineage/vertices/all
      * graph.getVertices();
+     * @return All vertices in lineage graph.
      */
     @GET
     @Path("/vertices/all")
@@ -157,6 +164,8 @@ public class LineageMetadataResource extends AbstractMetadataResource {
      *
      * GET http://host/metadata/lineage/vertices/id
      * graph.getVertex(id);
+     * @param vertexId The unique id of the vertex.
+     * @return Vertex with the specified id.
      */
     @GET
     @Path("/vertices/{id}")
@@ -193,6 +202,9 @@ public class LineageMetadataResource extends AbstractMetadataResource {
      * This is NOT a rexster API.
      * <p/>
      * GET http://host/metadata/lineage/vertices/properties/id
+     * @param vertexId The unique id of the vertex.
+     * @param relationships It has default value of false. Pass true if relationships should be fetched.
+     * @return Properties associated with the specified vertex.
      */
     @GET
     @Path("/vertices/properties/{id}")
@@ -292,6 +304,9 @@ public class LineageMetadataResource extends AbstractMetadataResource {
      * <p/>
      * GET http://host/metadata/lineage/vertices?key=<key>&value=<value>
      * graph.getVertices(key, value);
+     * @param key The key to be matched.
+     * @param value The associated value of the key.
+     * @return All vertices matching given property key and a value.
      */
     @GET
     @Path("/vertices")
@@ -313,9 +328,26 @@ public class LineageMetadataResource extends AbstractMetadataResource {
     /**
      * Get a list of adjacent edges with a direction.
      *
+     * <br/>
+     * To get the adjacent out vertices of vertex pass direction as out, in to get adjacent in vertices and both to get
+     * both in and out adjacent vertices.<br/>
+     * Similarly to get the out edges of vertex pass outE, inE to get in edges and bothE to get the both in and out
+     * edges of vertex.<br/>
+     * out : get the adjacent out vertices of vertex<br/>
+     * in : get the adjacent in vertices of vertex<br/>
+     * both : get the both adjacent in and out vertices of vertex<br/>
+     * outCount : get the number of out vertices of vertex<br/>
+     * inCount : get the number of in vertices of vertex<br/>
+     * bothCount : get the number of adjacent in and out vertices of vertex<br/>
+     * outIds : get the identifiers of out vertices of vertex<br/>
+     * inIds : get the identifiers of in vertices of vertex<br/>
+     * bothIds : get the identifiers of adjacent in and out vertices of vertex<br/>
      * GET http://host/metadata/lineage/vertices/id/direction
      * graph.getVertex(id).get{Direction}Edges();
      * direction: {(?!outE)(?!bothE)(?!inE)(?!out)(?!both)(?!in)(?!query).+}
+     * @param vertexId The id of the vertex.
+     * @param direction The direction associated with the edges.
+     * @return Adjacent vertices of the vertex for the specified direction.
      */
     @GET
     @Path("vertices/{id}/{direction}")
@@ -385,6 +417,7 @@ public class LineageMetadataResource extends AbstractMetadataResource {
      *
      * GET http://host/metadata/lineage/edges/all
      * graph.getEdges();
+     * @return All edges in lineage graph.
      */
     @GET
     @Path("/edges/all")
@@ -405,6 +438,8 @@ public class LineageMetadataResource extends AbstractMetadataResource {
      *
      * GET http://host/metadata/lineage/edges/id
      * graph.getEdge(id);
+     * @param edgeId The unique id of the edge.
+     * @return Edge with the specified id.
      */
     @GET
     @Path("/edges/{id}")

http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/prism/src/main/java/org/apache/falcon/resource/metadata/MetadataDiscoveryResource.java
----------------------------------------------------------------------
diff --git a/prism/src/main/java/org/apache/falcon/resource/metadata/MetadataDiscoveryResource.java b/prism/src/main/java/org/apache/falcon/resource/metadata/MetadataDiscoveryResource.java
index 220cc42..60c1089 100644
--- a/prism/src/main/java/org/apache/falcon/resource/metadata/MetadataDiscoveryResource.java
+++ b/prism/src/main/java/org/apache/falcon/resource/metadata/MetadataDiscoveryResource.java
@@ -52,6 +52,10 @@ public class MetadataDiscoveryResource extends AbstractMetadataResource {
      * Get list of dimensions for the given dimension-type.
      * <p/>
      * GET http://host/metadata/discovery/dimension-type/list
+     * @param clusterName <optional query param> Show dimensions related to this cluster.
+     * @param dimensionType Valid dimension types are cluster_entity,feed_entity, process_entity, user, colo, tags,
+     *                      groups, pipelines
+     * @return List of dimensions that match requested type [and cluster].
      */
     @GET
     @Path("/{type}/list")
@@ -89,6 +93,10 @@ public class MetadataDiscoveryResource extends AbstractMetadataResource {
      * Get relations of a dimension identified by type and name.
      *
      * GET http://host/metadata/discovery/dimension-type/dimension-name/relations
+     * @param dimensionName Name of the dimension.
+     * @param dimensionType Valid dimension types are cluster_entity,feed_entity, process_entity, user, colo, tags,
+     *                      groups, pipelines
+     * @return Get all relations of a specific dimension.
      */
     @GET
     @Path("/{type}/{name}/relations")

http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/prism/src/main/java/org/apache/falcon/resource/proxy/InstanceManagerProxy.java
----------------------------------------------------------------------
diff --git a/prism/src/main/java/org/apache/falcon/resource/proxy/InstanceManagerProxy.java b/prism/src/main/java/org/apache/falcon/resource/proxy/InstanceManagerProxy.java
index 3343c52..96c99f0 100644
--- a/prism/src/main/java/org/apache/falcon/resource/proxy/InstanceManagerProxy.java
+++ b/prism/src/main/java/org/apache/falcon/resource/proxy/InstanceManagerProxy.java
@@ -86,6 +86,25 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
     }
 
     //SUSPEND CHECKSTYLE CHECK ParameterNumberCheck
+    /**
+     * Get a list of instances currently running for a given entity.
+     * @param type Valid options are cluster, feed or process.
+     * @param entity Name of the entity.
+     * @param colo <optional param> Colo on which the query should be run.
+     * @param lifeCycles <optional param> Valid lifecycles for feed are Eviction/Replication(default) and for process
+     *                   is Execution(default).
+     * @param filterBy <optional param> Filter results by list of field:value pairs. Example:
+     *                 filterBy=CLUSTER:primary-cluster
+     *                 Supported filter fields are CLUSTER, SOURCECLUSTER, STARTEDAFTER.
+     *                 Query will do an AND among filterBy fields.
+     * @param orderBy <optional param> Field by which results should be ordered
+     *                Supports ordering by "status","startTime","endTime","cluster".
+     * @param sortOrder <optional param> Valid options are "asc" and "desc"
+     * @param offset <optional param> Show results from the offset, used for pagination. Defaults to 0.
+     * @param numResults <optional param> Number of results to show per request, used for pagination.
+     *                   Only integers > 0 are valid, Default is 10.
+     * @return List of instances currently running.
+     */
     @GET
     @Path("running/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -116,6 +135,29 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
        getStatus(...) method actually gets all instances, filtered by a specific status. This is
        a better named API which achieves the same result
      */
+    /**
+     * Get list of all instances of a given entity.
+     * @param type Valid options are cluster, feed or process.
+     * @param entity Name of the entity.
+     * @param startStr <optional param> Show instances from this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *                 By default, it is set to (end - (10 * entityFrequency)).
+     * @param endStr <optional param> Show instances up to this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *               Default is set to now.
+     * @param colo <optional param> Colo on which the query should be run.
+     * @param lifeCycles <optional param> Valid lifecycles for feed are Eviction/Replication(default) and for process
+     *                   is Execution(default).
+     * @param filterBy <optional param> Filter results by list of field:value pairs. Example:
+     *                 filterBy=STATUS:RUNNING,CLUSTER:primary-cluster
+     *                 Supported filter fields are STATUS, CLUSTER, SOURCECLUSTER, STARTEDAFTER.
+     *                 Query will do an AND among filterBy fields.
+     * @param orderBy <optional param> Field by which results should be ordered.
+     *                Supports ordering by "status","startTime","endTime","cluster".
+     * @param sortOrder <optional param> Valid options are "asc" and "desc"
+     * @param offset <optional param> Show results from the offset, used for pagination. Defaults to 0.
+     * @param numResults <optional param> Number of results to show per request, used for pagination.
+     *                   Only integers > 0 are valid, Default is 10.
+     * @return List of instances of given entity
+     */
     @GET
     @Path("list/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -144,6 +186,30 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
         }.execute(colo, type, entity);
     }
 
+    /**
+     * Get status of a specific instance of an entity.
+     * @param type Valid options are cluster, feed or process.
+     * @param entity Name of the entity.
+     * @param startStr <optional param> Show instances from this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *                 By default, it is set to (end - (10 * entityFrequency)).
+     * @param endStr <optional param> Show instances up to this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *               Default is set to now.
+     * @param colo <optional param> Colo on which the query should be run.
+     * @param lifeCycles <optional param> Valid lifecycles for feed are Eviction/Replication(default) and for process
+     *                   is Execution(default).
+     * @param filterBy <optional param> Filter results by list of field:value pairs. Example:
+     *                 filterBy=STATUS:RUNNING,CLUSTER:primary-cluster
+     *                 Supported filter fields are STATUS, CLUSTER, SOURCECLUSTER, STARTEDAFTER.
+     *                 Query will do an AND among filterBy fields.
+     * @param orderBy <optional param> Field by which results should be ordered.
+     *                Supports ordering by "status","startTime","endTime","cluster".
+     * @param sortOrder <optional param> Valid options are "asc" and "desc"
+     * @param offset <optional param> Show results from the offset, used for pagination. Defaults to 0.
+     * @param numResults <optional param> Number of results to show per request, used for pagination.
+     *                   Only integers > 0 are valid, Default is 10.
+     * @return Status of the specified instance along with job urls for all actions of user workflow and non-succeeded
+     *         actions of the main-workflow.
+     */
     @GET
     @Path("status/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -172,6 +238,27 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
         }.execute(colo, type, entity);
     }
 
+    /**
+     * Get summary of instance/instances of an entity.
+     * @param type Valid options are cluster, feed or process.
+     * @param entity Name of the entity.
+     * @param startStr <optional param> Show instances from this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *                 By default, it is set to (end - (10 * entityFrequency)).
+     * @param endStr <optional param> Show instances up to this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *               Default is set to now.
+     * @param colo <optional param> Colo on which the query should be run.
+     * @param lifeCycles <optional param> Valid lifecycles for feed are Eviction/Replication(default) and for process
+     *                   is Execution(default).
+     * @param filterBy <optional param> Filter results by list of field:value pairs.
+     *                 Example1: filterBy=STATUS:RUNNING,CLUSTER:primary-cluster
+     *                 Example2: filterBy=Status:RUNNING,Status:KILLED
+     *                 Supported filter fields are STATUS, CLUSTER.
+     *                 Query will do an AND among filterBy fields.
+     * @param orderBy <optional param> Field by which results should be ordered.
+     *                Supports ordering by "cluster". Example: orderBy=cluster
+     * @param sortOrder <optional param> Valid options are "asc" and "desc". Example: sortOrder=asc
+     * @return Summary of the instances over the specified time range
+     */
     @GET
     @Path("summary/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -197,6 +284,17 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
         }.execute(colo, type, entity);
     }
 
+    /**
+     * Get falcon feed instance availability.
+     * @param type Valid options is feed.
+     * @param entity Name of the entity.
+     * @param start <optional param> Show instances from this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *              By default, it is set to (end - (10 * entityFrequency)).
+     * @param end <optional param> Show instances up to this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *            Default is set to now.
+     * @param colo Colo on which the query should be run.
+     * @return Feed instance availability status
+     */
     @GET
     @Path("listing/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -217,6 +315,16 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
         }.execute(colo, type, entity);
     }
 
+    /**
+     * Get the params passed to the workflow for an instance of feed/process.
+     * @param type Valid options are cluster, feed or process.
+     * @param entity Name of the entity.
+     * @param start should be the nominal time of the instance for which you want the params to be returned
+     * @param colo <optional param> Colo on which the query should be run.
+     * @param lifeCycles <optional param> Valid lifecycles for feed are Eviction/Replication(default) and for process is
+     *                   Execution(default).
+     * @return List of instances currently running.
+     */
     @GET
     @Path("params/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -237,6 +345,30 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
         }.execute(colo, type, entity);
     }
 
+    /**
+     * Get log of a specific instance of an entity.
+     * @param type Valid options are cluster, feed or process.
+     * @param entity Name of the entity.
+     * @param startStr <optional param> Show instances from this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *                 By default, it is set to (end - (10 * entityFrequency)).
+     * @param endStr <optional param> Show instances up to this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *               Default is set to now.
+     * @param colo <optional param> Colo on which the query should be run.
+     * @param runId <optional param> Run Id.
+     * @param lifeCycles <optional param> Valid lifecycles for feed are Eviction/Replication(default) and for process is
+     *                   Execution(default).
+     * @param filterBy <optional param> Filter results by list of field:value pairs.
+     *                 Example: filterBy=STATUS:RUNNING,CLUSTER:primary-cluster
+     *                 Supported filter fields are STATUS, CLUSTER, SOURCECLUSTER, STARTEDAFTER.
+     *                 Query will do an AND among filterBy fields.
+     * @param orderBy <optional param> Field by which results should be ordered.
+     *                Supports ordering by "status","startTime","endTime","cluster".
+     * @param sortOrder <optional param> Valid options are "asc" and "desc"
+     * @param offset <optional param> Show results from the offset, used for pagination. Defaults to 0.
+     * @param numResults <optional param> Number of results to show per request, used for pagination. Only integers > 0
+     *                   are valid, Default is 10.
+     * @return Log of specified instance.
+     */
     @GET
     @Path("logs/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -266,6 +398,18 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
         }.execute(colo, type, entity);
     }
 
+    /**
+     * Kill currently running instance(s) of an entity.
+     * @param request Servlet Request
+     * @param type Valid options are feed or process.
+     * @param entity name of the entity.
+     * @param startStr start time of the instance(s) that you want to refer to
+     * @param endStr end time of the instance(s) that you want to refer to
+     * @param colo Colo on which the query should be run.
+     * @param lifeCycles <optional param> can be Eviction/Replication(default) for feed and Execution(default) for
+     *                   process.
+     * @return Result of the kill operation.
+     */
     @POST
     @Path("kill/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -290,6 +434,18 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
         }.execute(colo, type, entity);
     }
 
+    /**
+     * Suspend instances of an entity.
+     * @param request Servlet Request
+     * @param type Valid options are feed or process.
+     * @param entity name of the entity.
+     * @param startStr the start time of the instance(s) that you want to refer to
+     * @param endStr the end time of the instance(s) that you want to refer to
+     * @param colo Colo on which the query should be run.
+     * @param lifeCycles <optional param> can be Eviction/Replication(default) for feed and Execution(default) for
+     *                   process.
+     * @return Results of the suspend command.
+     */
     @POST
     @Path("suspend/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -313,6 +469,18 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
         }.execute(colo, type, entity);
     }
 
+    /**
+     * Resume suspended instances of an entity.
+     * @param request Servlet Request
+     * @param type Valid options are feed or process.
+     * @param entity name of the entity.
+     * @param startStr start time of the instance(s) that you want to refer to
+     * @param endStr the end time of the instance(s) that you want to refer to
+     * @param colo Colo on which the query should be run.
+     * @param lifeCycles <optional param> can be Eviction/Replication(default) for feed and Execution(default) for
+     *                   process.
+     * @return Results of the resume command.
+     */
     @POST
     @Path("resume/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -337,6 +505,20 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
         }.execute(colo, type, entity);
     }
 
+    /**
+     * Rerun instances of an entity. On issuing a rerun, by default the execution resumes from the last failed node in
+     * the workflow.
+     * @param type Valid options are feed or process.
+     * @param entity name of the entity.
+     * @param startStr start is the start time of the instance that you want to refer to
+     * @param endStr end is the end time of the instance that you want to refer to
+     * @param request Servlet Request
+     * @param colo Colo on which the query should be run.
+     * @param lifeCycles <optional param> can be Eviction/Replication(default) for feed and Execution(default) for
+     *                   process.
+     * @param isForced <optional param> can be used to forcefully rerun the entire instance.
+     * @return Results of the rerun command.
+     */
     @POST
     @Path("rerun/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -363,6 +545,14 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
     }
 
 
+    /**
+     * Get dependent instances for a particular instance.
+     * @param entityType Valid options are feed or process.
+     * @param entityName Name of the entity
+     * @param instanceTimeStr <mandatory param> time of the given instance
+     * @param colo Colo on which the query should be run.
+     * @return Dependent instances for the specified instance
+     */
     @GET
     @Path("dependencies/{type}/{entity}")
     @Produces(MediaType.APPLICATION_JSON)
@@ -384,6 +574,14 @@ public class InstanceManagerProxy extends AbstractInstanceManager {
         }.execute(colo, entityType, entityName);
     }
 
+    /**
+     *
+     * @param entityType type of the entity. Only feed and process are valid entity types for triage.
+     * @param entityName name of the entity.
+     * @param instanceTime time of the instance which should be used to triage.
+     * @param colo Colo on which the query should be run.
+     * @return It returns a json graph
+     */
     @GET
     @Path("triage/{type}/{name}")
     @Produces(MediaType.APPLICATION_JSON)

http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/prism/src/main/java/org/apache/falcon/resource/proxy/SchedulableEntityManagerProxy.java
----------------------------------------------------------------------
diff --git a/prism/src/main/java/org/apache/falcon/resource/proxy/SchedulableEntityManagerProxy.java b/prism/src/main/java/org/apache/falcon/resource/proxy/SchedulableEntityManagerProxy.java
index 61a80c1..47038e5 100644
--- a/prism/src/main/java/org/apache/falcon/resource/proxy/SchedulableEntityManagerProxy.java
+++ b/prism/src/main/java/org/apache/falcon/resource/proxy/SchedulableEntityManagerProxy.java
@@ -110,6 +110,13 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         return new BufferedRequest(request);
     }
 
+    /**
+     * Submit the given entity.
+     * @param request Servlet Request
+     * @param type Valid options are cluster, feed or process.
+     * @param ignore colo is ignored
+     * @return Result of the submission.
+     */
     @POST
     @Path("submit/{type}")
     @Consumes({MediaType.TEXT_XML, MediaType.TEXT_PLAIN})
@@ -169,6 +176,13 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         }
     }
 
+    /**
+     * Validates the submitted entity.
+     * @param request Servlet Request
+     * @param type Valid options are cluster, feed or process.
+     * @param skipDryRun Optional query param, Falcon skips oozie dryrun when value is set to true.
+     * @return Result of the validation.
+     */
     @POST
     @Path("validate/{type}")
     @Consumes({MediaType.TEXT_XML, MediaType.TEXT_PLAIN})
@@ -198,6 +212,14 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         }.execute();
     }
 
+    /**
+     * Delete the specified entity.
+     * @param request Servlet Request
+     * @param type Valid options are cluster, feed or process.
+     * @param entity Name of the entity.
+     * @param ignore colo is ignored
+     * @return Results of the delete operation.
+     */
     @DELETE
     @Path("delete/{type}/{entity}")
     @Produces({MediaType.TEXT_XML, MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON})
@@ -238,6 +260,15 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         return consolidateResult(results, APIResult.class);
     }
 
+    /**
+     * Updates the submitted entity.
+     * @param request Servlet Request
+     * @param type Valid options are feed or process.
+     * @param entityName Name of the entity.
+     * @param ignore colo is ignored
+     * @param skipDryRun Optional query param, Falcon skips oozie dryrun when value is set to true.
+     * @return Result of the validation.
+     */
     @POST
     @Path("update/{type}/{entity}")
     @Produces({MediaType.TEXT_XML, MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON})
@@ -317,6 +348,14 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         return consolidateResult(results, APIResult.class);
     }
 
+    /**
+     * Force updates the entity.
+     * @param type Valid options are feed or process.
+     * @param entityName Name of the entity.
+     * @param coloExpr Colo on which the query should be run.
+     * @param skipDryRun Optional query param, Falcon skips oozie dryrun when value is set to true.
+     * @return Result of the validation.
+     */
     @POST
     @Path("touch/{type}/{entity}")
     @Produces({MediaType.TEXT_XML, MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON})
@@ -341,6 +380,13 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         }.execute();
     }
 
+    /**
+     * Get status of the entity.
+     * @param type Valid options are cluster, feed or process.
+     * @param entity Name of the entity.
+     * @param coloExpr Colo on which the query should be run.
+     * @return Status of the entity.
+     */
     @GET
     @Path("status/{type}/{entity}")
     @Produces({MediaType.TEXT_XML, MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON})
@@ -362,6 +408,12 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         }.execute();
     }
 
+    /**
+     * Get dependencies of the entity.
+     * @param type Valid options are cluster, feed or process.
+     * @param entity Name of the entity.
+     * @return Dependencies of the entity.
+     */
     @GET
     @Path("dependencies/{type}/{entity}")
     @Produces({MediaType.TEXT_XML, MediaType.APPLICATION_JSON})
@@ -372,6 +424,12 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         return super.getDependencies(type, entity);
     }
 
+    /**
+     * Get definition of the entity.
+     * @param type Valid options are cluster, feed or process.
+     * @param entityName Name of the entity.
+     * @return Definition of the entity.
+     */
     @GET
     @Path("definition/{type}/{entity}")
     @Produces({MediaType.TEXT_XML, MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON})
@@ -380,6 +438,15 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         return super.getEntityDefinition(type, entityName);
     }
 
+    /**
+     * Schedule an entity.
+     * @param request Servlet Request
+     * @param type Valid options are feed or process.
+     * @param entity Name of the entity.
+     * @param coloExpr Colo on which the query should be run.
+     * @param skipDryRun Optional query param, Falcon skips oozie dryrun when value is set to true.
+     * @return Result of the schedule command.
+     */
     @POST
     @Path("schedule/{type}/{entity}")
     @Produces({MediaType.TEXT_XML, MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON})
@@ -407,6 +474,14 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         }.execute();
     }
 
+    /**
+     * Submits and schedules an entity.
+     * @param request Servlet Request
+     * @param type Valid options are feed or process.
+     * @param coloExpr Colo on which the query should be run.
+     * @param skipDryRun Optional query param, Falcon skips oozie dryrun when value is set to true.
+     * @return Result of the submit and schedule command.
+     */
     @POST
     @Path("submitAndSchedule/{type}")
     @Consumes({MediaType.TEXT_XML, MediaType.TEXT_PLAIN})
@@ -426,6 +501,14 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         return consolidateResult(results, APIResult.class);
     }
 
+    /**
+     * Suspend an entity.
+     * @param request Servlet Request
+     * @param type Valid options are feed or process.
+     * @param entity Name of the entity.
+     * @param coloExpr Colo on which the query should be run.
+     * @return Status of the entity.
+     */
     @POST
     @Path("suspend/{type}/{entity}")
     @Produces({MediaType.TEXT_XML, MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON})
@@ -450,6 +533,14 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
         }.execute();
     }
 
+    /**
+     * Resume a supended entity.
+     * @param request Servlet Request
+     * @param type Valid options are feed or process.
+     * @param entity Name of the entity.
+     * @param coloExpr Colo on which the query should be run.
+     * @return Result of the resume command.
+     */
     @POST
     @Path("resume/{type}/{entity}")
     @Produces({MediaType.TEXT_XML, MediaType.TEXT_PLAIN, MediaType.APPLICATION_JSON})
@@ -475,6 +566,39 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
     }
 
     //SUSPEND CHECKSTYLE CHECK ParameterNumberCheck
+
+    /**
+     *
+     * Get list of the entities.
+     * We have two filtering parameters for entity tags: "tags" and "tagkeys".
+     * "tags" does the exact match in key=value fashion, while "tagkeys" finds all the entities with the given key as a
+     * substring in the tags. This "tagkeys" filter is introduced for the user who doesn't remember the exact tag but
+     * some keywords in the tag. It also helps users to save the time of typing long tags.
+     * The returned entities will match all the filtering criteria.
+     * @param type Comma-separated entity types. Can be empty. Valid entity types are cluster, feed or process.
+     * @param fields <optional param> Fields of entity that the user wants to view, separated by commas.
+     *               Valid options are STATUS, TAGS, PIPELINES, CLUSTERS.
+     * @param nameSubsequence <optional param> Subsequence of entity name. Not case sensitive.
+     *                        The entity name needs to contain all the characters in the subsequence in the same order.
+     *                        Example 1: "sample1" will match the entity named "SampleFeed1-2".
+     *                        Example 2: "mhs" will match the entity named "New-My-Hourly-Summary".
+     * @param tagKeywords <optional param> Keywords in tags, separated by comma. Not case sensitive.
+     *                    The returned entities will have tags that match all the tag keywords.
+     * @param tags <optional param> Return list of entities that have specified tags, separated by a comma.
+     *             Query will do AND on tag values.
+     *             Example: tags=consumer=consumer@xyz.com,owner=producer@xyz.com
+     * @param filterBy <optional param> Filter results by list of field:value pairs.
+     *                 Example: filterBy=STATUS:RUNNING,PIPELINES:clickLogs
+     *                 Supported filter fields are NAME, STATUS, PIPELINES, CLUSTER.
+     *                 Query will do an AND among filterBy fields.
+     * @param orderBy <optional param> Field by which results should be ordered.
+     *                Supports ordering by "name".
+     * @param sortOrder <optional param> Valid options are "asc" and "desc"
+     * @param offset <optional param> Show results from the offset, used for pagination. Defaults to 0.
+     * @param resultsPerPage <optional param> Number of results to show per request, used for pagination. Only
+     *                       integers > 0 are valid, Default is 10.
+     * @return Total number of results and a list of entities.
+     */
     @GET
     @Path("list{type : (/[^/]+)?}")
     @Produces({MediaType.TEXT_XML, MediaType.APPLICATION_JSON})
@@ -499,6 +623,33 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
                 orderBy, sortOrder, offset, resultsPerPage, doAsUser);
     }
 
+    /**
+     * Given an EntityType and cluster, get list of entities along with summary of N recent instances of each entity.
+     * @param type Valid options are feed or process.
+     * @param cluster Show entities that belong to this cluster.
+     * @param startStr <optional param> Show entity summaries from this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *                 By default, it is set to (end - 2 days).
+     * @param endStr <optional param> Show entity summary up to this date. Date format is yyyy-MM-dd'T'HH:mm'Z'.
+     *               Default is set to now.
+     * @param entityFields <optional param> Fields of entity that the user wants to view, separated by commas.
+     *                     Valid options are STATUS, TAGS, PIPELINES.
+     * @param entityFilter <optional param> Filter results by list of field:value pairs.
+     *                     Example: filterBy=STATUS:RUNNING,PIPELINES:clickLogs
+     *                     Supported filter fields are NAME, STATUS, PIPELINES, CLUSTER.
+     *                     Query will do an AND among filterBy fields.
+     * @param entityTags <optional param> Return list of entities that have specified tags, separated by a comma.
+     *                   Query will do AND on tag values.
+     *                   Example: tags=consumer=consumer@xyz.com,owner=producer@xyz.com
+     * @param entityOrderBy <optional param> Field by which results should be ordered.
+     *                      Supports ordering by "name".
+     * @param entitySortOrder <optional param> Valid options are "asc" and "desc"
+     * @param entityOffset <optional param> Show results from the offset, used for pagination. Defaults to 0.
+     * @param numEntities <optional param> Number of results to show per request, used for pagination. Only
+     *                    integers > 0 are valid, Default is 10.
+     * @param numInstanceResults <optional param> Number of recent instances to show per entity. Only integers > 0 are
+     *                           valid, Default is 7.
+     * @return Show entities along with summary of N instances for each entity.
+     */
     @GET
     @Path("summary/{type}")
     @Produces({MediaType.TEXT_XML, MediaType.APPLICATION_JSON})
@@ -522,6 +673,15 @@ public class SchedulableEntityManagerProxy extends AbstractSchedulableEntityMana
                 entityTags, entityOrderBy, entitySortOrder, entityOffset, numEntities, numInstanceResults, doAsUser);
     }
 
+    /**
+     * Get the name of the feed along with the location type(meta/data/stats) and cluster on which the given path
+     * belongs to this feed.
+     * @param type Valid option is feed.
+     * @param path path of the instance for which you want to determine the feed
+     *             Example: /data/project1/2014/10/10/23/ Path has to be the complete path and can't be a part of it.
+     * @return Returns the name of the feed along with the location type(meta/data/stats) and cluster on which the given
+     *         path belongs to this feed.
+     */
     @GET
     @Path("lookup/{type}")
     @Produces({MediaType.APPLICATION_JSON, MediaType.TEXT_PLAIN})

http://git-wip-us.apache.org/repos/asf/falcon/blob/88d10551/webapp/pom.xml
----------------------------------------------------------------------
diff --git a/webapp/pom.xml b/webapp/pom.xml
index 828f7f5..77ef662 100644
--- a/webapp/pom.xml
+++ b/webapp/pom.xml
@@ -42,6 +42,7 @@
                         <version>2.4</version>
                         <configuration>
                             <packagingExcludes>WEB-INF/classes/deploy.properties</packagingExcludes>
+                            <packagingExcludes>docs/downloads.html</packagingExcludes>
                             <webResources>
                                 <resource>
                                     <directory>../falcon-ui/dist</directory>
@@ -50,6 +51,9 @@
                                     <directory>src/main/webapp/WEB-INF/distributed</directory>
                                     <targetPath>WEB-INF</targetPath>
                                 </resource>
+                                <resource>
+                                    <directory>../prism/target/restapi</directory>
+                                </resource>
                             </webResources>
                         </configuration>
                     </plugin>
@@ -250,6 +254,7 @@
                 <artifactId>maven-war-plugin</artifactId>
                 <version>2.4</version>
                 <configuration>
+                    <packagingExcludes>docs/downloads.html</packagingExcludes>
                     <webResources>
                         <resource>
                             <directory>../html5-ui</directory>
@@ -262,6 +267,9 @@
                             <directory>src/main/webapp/WEB-INF/embedded</directory>
                             <targetPath>WEB-INF</targetPath>
                         </resource>
+                        <resource>
+                            <directory>../prism/target/restapi</directory>
+                        </resource>
                     </webResources>
                 </configuration>
             </plugin>


Mime
View raw message