You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@falcon.apache.org by aj...@apache.org on 2015/09/24 22:49:50 UTC
falcon git commit: FALCON-438 Auto generate documentation for REST
API. Contributed by Narayan Periwal.
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 <aj...@gmail.com>
Authored: Fri Sep 25 00:02:08 2015 +0530
Committer: Ajay Yadava <aj...@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>