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 <[email protected]> Authored: Fri Sep 25 00:02:08 2015 +0530 Committer: Ajay Yadava <[email protected]> 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: [email protected],[email protected] + * @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: [email protected],[email protected] + * @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>
