Added: samza/site/learn/documentation/latest/rest/resources.html URL: http://svn.apache.org/viewvc/samza/site/learn/documentation/latest/rest/resources.html?rev=1757411&view=auto ============================================================================== --- samza/site/learn/documentation/latest/rest/resources.html (added) +++ samza/site/learn/documentation/latest/rest/resources.html Tue Aug 23 17:38:58 2016 @@ -0,0 +1,239 @@ +<!DOCTYPE html> +<!-- + 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. +--> +<html lang="en"> + <head> + <meta charset="utf-8"> + <title>Samza - Resources</title> + <link href='/css/ropa-sans.css' rel='stylesheet' type='text/css'/> + <link href="/css/bootstrap.min.css" rel="stylesheet"/> + <link href="/css/font-awesome.min.css" rel="stylesheet"/> + <link href="/css/main.css" rel="stylesheet"/> + <link href="/css/syntax.css" rel="stylesheet"/> + <link rel="icon" type="image/png" href="/img/samza-icon.png"> + <script src="/js/jquery-1.11.1.min.js"></script> + </head> + <body> + <div class="wrapper"> + <div class="wrapper-content"> + + <div class="masthead"> + <div class="container"> + <div class="masthead-logo"> + <a href="/" class="logo">samza</a> + </div> + <div class="masthead-icons"> + <div class="pull-right"> + <a href="/startup/download"><i class="fa fa-arrow-circle-o-down masthead-icon"></i></a> + <a href="https://git-wip-us.apache.org/repos/asf?p=samza.git;a=tree"; target="_blank"><i class="fa fa-code masthead-icon" style="font-weight: bold;"></i></a> + <a href="https://twitter.com/samzastream"; target="_blank"><i class="fa fa-twitter masthead-icon"></i></a> + <!-- this icon only shows in versioned pages --> + + + + + <a href="/learn/documentation/0.10/rest/resources.html"><i id="switch-version-button"></i></a> + <!-- links for the navigation bar --> + + + </div> + </div> + </div><!-- /.container --> + </div> + + <div class="container"> + <div class="menu"> + <h1><i class="fa fa-rocket"></i> Getting Started</h1> + <ul> + <li><a href="/startup/hello-samza/latest">Hello Samza</a></li> + <li><a href="/startup/download">Download</a></li> + </ul> + + <h1><i class="fa fa-book"></i> Learn</h1> + <ul> + <li><a href="/learn/documentation/latest">Documentation</a></li> + <li><a href="/learn/documentation/latest/jobs/configuration-table.html">Configuration</a></li> + <li><a href="/learn/documentation/latest/api/javadocs/">Javadocs</a></li> + <li><a href="/learn/tutorials/latest">Tutorials</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/FAQ";>FAQ</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/Apache+Samza";>Wiki</a></li> + <li><a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=51812876";>Papers & Talks</a></li> + <li><a href="http://blogs.apache.org/samza";>Blog</a></li> + </ul> + + <h1><i class="fa fa-comments"></i> Community</h1> + <ul> + <li><a href="/community/mailing-lists.html">Mailing Lists</a></li> + <li><a href="/community/irc.html">IRC</a></li> + <li><a href="https://issues.apache.org/jira/browse/SAMZA";>Bugs</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/Powered+By";>Powered by</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/Ecosystem";>Ecosystem</a></li> + <li><a href="/community/committers.html">Committers</a></li> + </ul> + + <h1><i class="fa fa-code"></i> Contribute</h1> + <ul> + <li><a href="/contribute/rules.html">Rules</a></li> + <li><a href="/contribute/coding-guide.html">Coding Guide</a></li> + <li><a href="/contribute/projects.html">Projects</a></li> + <li><a href="/contribute/design-documents.html">Design Documents</a></li> + <li><a href="/contribute/code.html">Code</a></li> + <li><a href="https://reviews.apache.org/groups/samza";>Review Board</a></li> + <li><a href="/contribute/tests.html">Tests</a></li> + </ul> + + <h1><i class="fa fa-history"></i> Archive</h1> + <ul> + <li><a href="/archive/index.html#latest">latest</a></li> + <li><a href="/archive/index.html#10">0.10</a></li> + <li><a href="/archive/index.html#09">0.9</a></li> + <li><a href="/archive/index.html#08">0.8</a></li> + <li><a href="/archive/index.html#07">0.7</a></li> + </ul> + </div> + + <div class="content"> + <!-- + 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. +--> + +<h2>Resources</h2> + +<!-- + 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. +--> + +<p>Samza REST can expose any JAX-RS Resource. By default, it ships with a <a href="./resources/jobs.html">JobsResource</a> which is discussed below. You can implement your own Resources and specify them in the config.</p> + +<h2 id="implementing-a-new-resource">Implementing a New Resource</h2> + +<p>Samza REST uses the <a href="https://jersey.java.net/";>Jersey</a> implementation of the <a href="https://jax-rs-spec.java.net/";>JAX-RS specification</a>. The Jersey documentation and examples are helpful for creating a new Resource.</p> + +<p>In addition, Samza REST imposes the following conventions, which should be followed for all Resources.</p> + +<h3 id="versioned-paths">Versioned Paths</h3> + +<p>By convention, all resources prefix their path with a version number to enable supporting legacy APIs in the future. For example, the base URL for the JobsResource is</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">/v1/jobs +</code></pre></div> +<p>If a future version of JobsResource implements a different API, it will use a different version number in the base path.</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">/v2/jobs +</code></pre></div> +<p>All resources should be exposed on the latest version so clients can use a common version base for all requests.</p> + +<h3 id="error-messages">Error Messages</h3> + +<p>Every error response will include a JSON message body containing a single <code>message</code> field describing the problem. For example:</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">{ + "message": "Unrecognized status: null" +} +</code></pre></div> +<h3 id="configuration">Configuration</h3> + +<p>There are a few extra steps for Resources that require configuration values.</p> + +<ol> +<li>Implement a configuration class that extends <a href="../api/javadocs/org/apache/samza/config/MapConfig.html">MapConfig</a> with all the constants and accessors for the Resource’s configs. The <a href="javadocs/org/apache/samza/rest/SamzaRestConfig.html">SamzaRestConfig</a> should not be cluttered with Resource configs. See the <a href="javadocs/org/apache/samza/rest/resources/JobsResourceConfig.html">JobsResourceConfig</a> for an example.</li> +<li>Implement or extend a <a href="javadocs/org/apache/samza/rest/resources/ResourceFactory.html">ResourceFactory</a> which will use the global Samza REST config file to instantiate the MapConfig implementation from step 1 and use it to construct the Resource that requires the config. See the <a href="javadocs/org/apache/samza/rest/resources/DefaultResourceFactory.html">DefaultResourceFactory</a> for an example.</li> +<li>Add all the necessary resource properties to the Samza REST config file. The <a href="javadocs/org/apache/samza/rest/SamzaRestApplication.html">SamzaRestApplication</a> passes the global config into the configured ResourceFactories to instantiate the Resources with configs.</li> +</ol> + +<h2 id="adding-a-new-resource-to-the-samza-rest-service">Adding a New Resource to the Samza REST Service</h2> + +<p>Resources are added to the Samza REST Service via config. There are two ways to add a new Resource depending on whether the Resource requires properties from the config file or not. In the former case, the Resource is instantiated once with the config and the instance is registered with the SamzaRestApplication. In the latter case, the Resource <em>class</em> is registered and it can be instantiated many times over the lifecycle of the application.</p> + +<ul> +<li><p>To add a configured Resource add the fully-qualified class name of the ResourceFactory implementation that instantiates the Resource to the <code>rest.resource.factory.classes</code> property in the service config.</p></li> +<li><p>To add a config-less Resource, add the fully-qualified class name of the Resource implementation to the <code>rest.resource.classes</code> property in the service config.</p></li> +</ul> + +<p>For more information on these config properties, see the config table in the <a href="overview.html#configuration">Overview page.</a></p> + +<h2 id="monitors-»"><a href="monitors.html">Monitors »</a></h2> + + + </div> + </div> + + </div><!-- /.wrapper-content --> + </div><!-- /.wrapper --> + + <div class="footer"> + <div class="container"> + <!-- nothing for now. --> + </div> + </div> + + + <script> + $( document ).ready(function() { + if ( $.fn.urlExists( "/learn/documentation/0.10/rest/resources.html" ) ) { + $("#switch-version-button").addClass("fa fa-history masthead-icon"); + } + }); + + /* a function to test whether the url exists or not */ + (function( $ ) { + $.fn.urlExists = function(url) { + var http = new XMLHttpRequest(); + http.open('HEAD', url, false); + http.send(); + return http.status != 404; + }; + }( jQuery )); + </script> + + + <!-- Google Analytics --> + <script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-43122768-1', 'apache.org'); + ga('send', 'pageview'); + + </script> + </body> +</html>
Added: samza/site/learn/documentation/latest/rest/resources/jobs.html URL: http://svn.apache.org/viewvc/samza/site/learn/documentation/latest/rest/resources/jobs.html?rev=1757411&view=auto ============================================================================== --- samza/site/learn/documentation/latest/rest/resources/jobs.html (added) +++ samza/site/learn/documentation/latest/rest/resources/jobs.html Tue Aug 23 17:38:58 2016 @@ -0,0 +1,512 @@ +<!DOCTYPE html> +<!-- + 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. +--> +<html lang="en"> + <head> + <meta charset="utf-8"> + <title>Samza - Jobs Resource</title> + <link href='/css/ropa-sans.css' rel='stylesheet' type='text/css'/> + <link href="/css/bootstrap.min.css" rel="stylesheet"/> + <link href="/css/font-awesome.min.css" rel="stylesheet"/> + <link href="/css/main.css" rel="stylesheet"/> + <link href="/css/syntax.css" rel="stylesheet"/> + <link rel="icon" type="image/png" href="/img/samza-icon.png"> + <script src="/js/jquery-1.11.1.min.js"></script> + </head> + <body> + <div class="wrapper"> + <div class="wrapper-content"> + + <div class="masthead"> + <div class="container"> + <div class="masthead-logo"> + <a href="/" class="logo">samza</a> + </div> + <div class="masthead-icons"> + <div class="pull-right"> + <a href="/startup/download"><i class="fa fa-arrow-circle-o-down masthead-icon"></i></a> + <a href="https://git-wip-us.apache.org/repos/asf?p=samza.git;a=tree"; target="_blank"><i class="fa fa-code masthead-icon" style="font-weight: bold;"></i></a> + <a href="https://twitter.com/samzastream"; target="_blank"><i class="fa fa-twitter masthead-icon"></i></a> + <!-- this icon only shows in versioned pages --> + + + + + <a href="/learn/documentation/0.10/rest/resources/jobs.html"><i id="switch-version-button"></i></a> + <!-- links for the navigation bar --> + + + </div> + </div> + </div><!-- /.container --> + </div> + + <div class="container"> + <div class="menu"> + <h1><i class="fa fa-rocket"></i> Getting Started</h1> + <ul> + <li><a href="/startup/hello-samza/latest">Hello Samza</a></li> + <li><a href="/startup/download">Download</a></li> + </ul> + + <h1><i class="fa fa-book"></i> Learn</h1> + <ul> + <li><a href="/learn/documentation/latest">Documentation</a></li> + <li><a href="/learn/documentation/latest/jobs/configuration-table.html">Configuration</a></li> + <li><a href="/learn/documentation/latest/api/javadocs/">Javadocs</a></li> + <li><a href="/learn/tutorials/latest">Tutorials</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/FAQ";>FAQ</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/Apache+Samza";>Wiki</a></li> + <li><a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=51812876";>Papers & Talks</a></li> + <li><a href="http://blogs.apache.org/samza";>Blog</a></li> + </ul> + + <h1><i class="fa fa-comments"></i> Community</h1> + <ul> + <li><a href="/community/mailing-lists.html">Mailing Lists</a></li> + <li><a href="/community/irc.html">IRC</a></li> + <li><a href="https://issues.apache.org/jira/browse/SAMZA";>Bugs</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/Powered+By";>Powered by</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/Ecosystem";>Ecosystem</a></li> + <li><a href="/community/committers.html">Committers</a></li> + </ul> + + <h1><i class="fa fa-code"></i> Contribute</h1> + <ul> + <li><a href="/contribute/rules.html">Rules</a></li> + <li><a href="/contribute/coding-guide.html">Coding Guide</a></li> + <li><a href="/contribute/projects.html">Projects</a></li> + <li><a href="/contribute/design-documents.html">Design Documents</a></li> + <li><a href="/contribute/code.html">Code</a></li> + <li><a href="https://reviews.apache.org/groups/samza";>Review Board</a></li> + <li><a href="/contribute/tests.html">Tests</a></li> + </ul> + + <h1><i class="fa fa-history"></i> Archive</h1> + <ul> + <li><a href="/archive/index.html#latest">latest</a></li> + <li><a href="/archive/index.html#10">0.10</a></li> + <li><a href="/archive/index.html#09">0.9</a></li> + <li><a href="/archive/index.html#08">0.8</a></li> + <li><a href="/archive/index.html#07">0.7</a></li> + </ul> + </div> + + <div class="content"> + <!-- + 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. +--> + +<h2>Jobs Resource</h2> + +<!-- + 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. +--> + +<p>Exposes operations at the job scope (as opposed to the cluster, container, or task scope). The initial implementation includes the ability to list all jobs, get the status of a particular job, and start or stop an individual job.</p> + +<h1 id="api">API</h1> + +<p>The following sections provide general information about the response structure and detailed descriptions of each of the requests.</p> + +<h2 id="response-structure">Response Structure</h2> + +<p>All responses will contain either a job status or an error message.</p> + +<p><strong>Job Status</strong></p> + +<p>Job status will be of the form:</p> + +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"status"</span><span class="p">:</span><span class="s2">"STOPPED"</span><span class="p">,</span> + <span class="nt">"statusDetail"</span><span class="p">:</span><span class="s2">"KILLED"</span><span class="p">,</span> + <span class="nt">"jobName"</span><span class="p">:</span><span class="s2">"wikipedia-parser"</span><span class="p">,</span> + <span class="nt">"jobId"</span><span class="p">:</span><span class="s2">"1"</span> +<span class="p">}</span></code></pre></div> + +<p><code>status</code> is the abstract Samza status for the job. Initially it will be one of {STARTING, STARTED, STOPPED, UNKNOWN}.</p> + +<p><code>statusDetail</code> is the implementation-specific status for the job. For YARN, it will be one of the values in the YarnApplicationState enum.</p> + +<p><strong>Error Message</strong></p> + +<p>Every error response have the following structure:</p> + +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"message"</span><span class="p">:</span> <span class="s2">"Unrecognized status parameter: null"</span> +<span class="p">}</span></code></pre></div> + +<p><code>message</code> is the only field in the response and contains a description of the problem. +<br/></p> + +<h2 id="get-all-jobs">Get All Jobs</h2> + +<p>Lists all the jobs installed on the host and provides their status.</p> + +<h6 id="request">Request</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">GET /v1/jobs +</code></pre></div> +<h6 id="response">Response</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">Status: 200 OK +</code></pre></div> +<div class="highlight"><pre><code class="json"><span class="p">[</span> + + <span class="p">{</span> + <span class="nt">"status"</span><span class="p">:</span><span class="s2">"STOPPED"</span><span class="p">,</span> + <span class="nt">"statusDetail"</span><span class="p">:</span><span class="s2">"KILLED"</span><span class="p">,</span> + <span class="nt">"jobName"</span><span class="p">:</span><span class="s2">"wikipedia-parser"</span><span class="p">,</span> + <span class="nt">"jobId"</span><span class="p">:</span><span class="s2">"1"</span> + <span class="p">},</span> + <span class="p">{</span> + <span class="nt">"status"</span><span class="p">:</span><span class="s2">"STARTED"</span><span class="p">,</span> + <span class="nt">"statusDetail"</span><span class="p">:</span><span class="s2">"RUNNING"</span><span class="p">,</span> + <span class="nt">"jobName"</span><span class="p">:</span><span class="s2">"wikipedia-feed"</span><span class="p">,</span> + <span class="nt">"jobId"</span><span class="p">:</span><span class="s2">"1"</span> + <span class="p">},</span> + <span class="p">{</span> + <span class="nt">"status"</span><span class="p">:</span><span class="s2">"STOPPED"</span><span class="p">,</span> + <span class="nt">"statusDetail"</span><span class="p">:</span><span class="kc">null</span><span class="p">,</span> + <span class="nt">"jobName"</span><span class="p">:</span><span class="s2">"wikipedia-stats"</span><span class="p">,</span> + <span class="nt">"jobId"</span><span class="p">:</span><span class="s2">"1"</span> + <span class="p">}</span> +<span class="p">]</span></code></pre></div> + +<h6 id="response-codes">Response codes</h6> + +<table class="table table-condensed table-bordered table-striped"> + <thead> + <tr> + <th>Status</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>200 OK</td><td>The operation completed successfully and the current job status for each job is returned.</td> + </tr> + <tr> + <td>500 Server Error</td><td>There was an error executing the command on the server. e.g. The command timed out. +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"message"</span><span class="p">:</span> <span class="s2">"Timeout waiting for job status."</span> +<span class="p">}</span></code></pre></div> +</td> + </tr> + </tbody> +</table> + +<p><br/></p> + +<h2 id="get-job">Get Job</h2> + +<p>Gets the status of the specified job.</p> + +<h6 id="format">Format</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">GET /v1/jobs/{jobName}/{jobId} +</code></pre></div> +<p>The <code>{jobName}</code> and <code>{jobId}</code> path parameters reflect the values of ‘job.name’ and ‘job.id’ in the job config.</p> + +<h6 id="request">Request</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">GET /v1/jobs/wikipedia-feed/1 +</code></pre></div> +<h6 id="response">Response</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">Status: 200 OK +</code></pre></div> +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"status"</span><span class="p">:</span><span class="s2">"STARTED"</span><span class="p">,</span> + <span class="nt">"statusDetail"</span><span class="p">:</span><span class="s2">"RUNNING"</span><span class="p">,</span> + <span class="nt">"jobName"</span><span class="p">:</span><span class="s2">"wikipedia-feed"</span><span class="p">,</span> + <span class="nt">"jobId"</span><span class="p">:</span><span class="s2">"1"</span> +<span class="p">}</span></code></pre></div> + +<h6 id="response-codes">Response codes</h6> + +<table class="table table-condensed table-bordered table-striped"> + <thead> + <tr> + <th>Status</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>200 OK</td><td>The operation completed successfully and the current job status is returned.</td> + </tr> + <tr> + <td>404 Not Found</td><td>The specified job+instance was not found. +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"message"</span><span class="p">:</span> <span class="s2">"Job wikipedia-¯\_(ã)_/¯-feed instance 1 is not installed on this host."</span> +<span class="p">}</span></code></pre></div> +</td> + </tr> + <tr> + <td>500 Server Error</td><td>There was an error executing the command on the server. e.g. The command timed out. +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"message"</span><span class="p">:</span> <span class="s2">"Timeout waiting for job status."</span> +<span class="p">}</span></code></pre></div> +</td> + </tr> + </tbody> +</table> + +<p><br/></p> + +<h2 id="start-job">Start Job</h2> + +<p>Starts the job with the specified app name if it’s not already started. The command will return when it has initiated the start operation.</p> + +<h6 id="format">Format</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">PUT /v1/jobs/{jobName}/{jobId}?status=started +</code></pre></div> +<p>Form parameter <code>status</code> is the intended status of the job at the end of the request.</p> + +<h6 id="example">Example</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">PUT /v1/jobs/wikipedia-feed/1?status=started +</code></pre></div> +<h6 id="response">Response</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">Status: 202 Accepted +</code></pre></div> +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"status"</span><span class="p">:</span><span class="s2">"STARTING"</span><span class="p">,</span> + <span class="nt">"statusDetail"</span><span class="p">:</span><span class="s2">"ACCEPTED"</span><span class="p">,</span> + <span class="nt">"jobName"</span><span class="p">:</span> <span class="s2">"wikipedia-feed"</span><span class="p">,</span> + <span class="nt">"jobId"</span><span class="p">:</span> <span class="s2">"1"</span> +<span class="p">}</span></code></pre></div> + +<h6 id="response-codes">Response codes</h6> + +<table class="table table-condensed table-bordered table-striped"> + <thead> + <tr> + <th>Status</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>200 OK</td><td>The operation completed successfully and the current job status is returned.</td> + </tr> + <tr> + <td>400 Bad Request</td><td>There was a problem with the request. e.g. an invalid status parameter. +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"message"</span><span class="p">:</span> <span class="s2">"Unrecognized status parameter: null"</span> +<span class="p">}</span></code></pre></div> +</td> + <tr> + <td>404 Not Found</td><td>The specified job+instance was not found. +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"message"</span><span class="p">:</span> <span class="s2">"Job wikipedia-¯\_(ã)_/¯-feed instance 1 is not installed on this host."</span> +<span class="p">}</span></code></pre></div> +</td> + </tr> + <tr> + <td>500 Server Error</td><td>There was an error executing the command on the server. e.g. The command timed out. +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"message"</span><span class="p">:</span> <span class="s2">"Timeout waiting for job status."</span> +<span class="p">}</span></code></pre></div> +</td> + </tr> + </tbody> +</table> + +<p><br/></p> + +<h2 id="stop-job">Stop Job</h2> + +<p>Stops the job with the specified app name if it’s not already stopped.</p> + +<h6 id="format">Format</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">PUT /v1/jobs/{jobName}/{jobId}?status=stopped +</code></pre></div> +<p>Form parameter <code>status</code> is the intended status of the job at the end of the request.</p> + +<h6 id="example">Example</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">PUT /v1/jobs/wikipedia-feed/1?status=stopped +</code></pre></div> +<h6 id="response">Response</h6> +<div class="highlight"><pre><code class="language-text" data-lang="text">Status: 202 Accepted +</code></pre></div> +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"status"</span><span class="p">:</span><span class="s2">"STOPPED"</span><span class="p">,</span> + <span class="nt">"statusDetail"</span><span class="p">:</span><span class="s2">"KILLED"</span><span class="p">,</span> + <span class="nt">"jobName"</span><span class="p">:</span> <span class="s2">"wikipedia-feed"</span><span class="p">,</span> + <span class="nt">"jobId"</span><span class="p">:</span> <span class="s2">"1"</span> +<span class="p">}</span></code></pre></div> + +<h6 id="response-codes">Response codes</h6> + +<table class="table table-condensed table-bordered table-striped"> + <thead> + <tr> + <th>Status</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>200 OK</td><td>The operation completed successfully and the current job status is returned.</td> + </tr> + <tr> + <td>400 Bad Request</td><td>There was a problem with the request. e.g. an invalid status parameter. +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"message"</span><span class="p">:</span> <span class="s2">"Unrecognized status parameter: null"</span> +<span class="p">}</span></code></pre></div> +</td> + <tr> + <td>404 Not Found</td><td>The specified job+instance was not found. +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"message"</span><span class="p">:</span> <span class="s2">"Job wikipedia-¯\_(ã)_/¯-feed instance 1 is not installed on this host."</span> +<span class="p">}</span></code></pre></div> +</td> + </tr> + <tr> + <td>500 Server Error</td><td>There was an error executing the command on the server. e.g. The command timed out. +<div class="highlight"><pre><code class="json"><span class="p">{</span> + <span class="nt">"message"</span><span class="p">:</span> <span class="s2">"Timeout waiting for job status."</span> +<span class="p">}</span></code></pre></div> +</td> + </tr> + </tbody> +</table> + +<p><br/></p> + +<h1 id="design">Design</h1> + +<h3 id="abstractions">Abstractions</h3> + +<p>There are three primary abstractions used by the JobsResource that users can implement to handle any details specific to their environment.</p> + +<ol> +<li> <strong>JobProxy</strong>: The JobProxy is the central point of interacting with Samza jobs. It exposes generic methods to start, stop, and get the status of a Samza job. Implementations of this interface can employ custom code to implement these methods tailored to the specific API for any cluster manager.</li> +<li> <strong>InstallationFinder</strong>: The InstallationFinder provides a generic interface to discover all the installed jobs, hiding any customizations in the job package structure and its location (e.g. local vs remote host). The InstallationFinder also resolves the job configuration, which is used to validate and identify the job.</li> +<li> <strong>JobStatusProvider</strong>: The JobStatusProvider allows the JobProxy to get the status of a job in a generic way. The same interface can be used to get the job status on Yarn, Mesos, or standalone jobs. It also enables different implementations for the same cluster. With Yarn, for example, one implementation may get job status via command line and another via the ResourceManager REST API.</li> +</ol> + +<p>The <a href="jobs.html#configuration">configuration</a> must specify a JobProxy factory class explicitly. By contrast, the InstallationFinder and JobStatusProvider abstractions are natural extensions of the JobProxy and are solely provided to demonstrate a pattern for discovering installed jobs and fetching job status. However, they are not an explicit requirement.</p> + +<p>The <code>SimpleYarnJobProxy</code> that ships with Samza REST is intended to demonstrate a functional implementation of a JobProxy which works with the Hello Samza jobs. See the <a href="../../../../tutorials/latest/samza-rest-getting-started.html">tutorial</a> to try it out. You can implement your own JobProxy to adapt the JobsResource to the specifics of your job packaging and deployment model.</p> + +<h3 id="request-flow">Request Flow</h3> + +<p>After validating each request, the JobsResource invokes the appropriate JobProxy command. The JobProxy uses the InstallationFinder to enumerate the installed jobs and the JobStatusProvider to get the runtime status of the jobs.</p> + +<p>The provided <a href="../javadocs/org/apache/samza/rest/proxy/installation/SimpleInstallationFinder.html">SimpleInstallationFinder</a> crawls the file system, starting in the directory specified by the <code>job.installations.path</code> looking for valid Samza job config files. It extracts the <code>job.name</code> and <code>job.id</code> property values and creates an <a href="../javadocs/org/apache/samza/rest/proxy/installation/InstallationRecord.html">InstallationRecord</a> for the each job instance. The InstallationRecord contains all the information needed to start, stop, and get the status for the job.</p> + +<p>The provided <a href="../javadocs/org/apache/samza/rest/proxy/job/YarnCliJobStatusProvider.html">YarnCliJobStatusProvider</a> leverages a ScriptRunner to fetch job status using the Yarn ApplicationCLI.</p> + +<p>The <a href="../javadocs/org/apache/samza/rest/proxy/job/SimpleYarnJobProxy.html">SimpleYarnJobProxy</a> relies on the scripts in the InstallationRecord scriptFilePath (<code>/bin</code>) directory to start and stop jobs.</p> + +<p>The following is a depiction of the implementation that ships with Samza REST:</p> + +<p><img src="/img/latest/learn/documentation/rest/JobsResource.png" alt="JobsResourceDiagram"></p> + +<h2 id="configuration">Configuration</h2> + +<p>The JobsResource properties should be specified in the same file as the Samza REST configuration. They are specified here for clarity.</p> + +<table class="table table-condensed table-bordered table-striped"> + <thead> + <tr> + <th>Name</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td>job.proxy.factory.class</td><td><b>Required:</b> The Job Proxy Factory that will be used to create a Job Proxy to control the job. The value is a fully-qualified class name which must implement JobProxyFactory. Samza ships with one implementation: <pre>org.apache.samza.rest.proxy.job.SimpleYarnJobProxy</pre> <li> Executes shell scripts to start, stop, and get the status of jobs, relying primarily on the YARN ApplicationCLI. It uses the <pre>SimpleInstallationRecord</pre> abstraction to interact with Samza jobs installed on disk.</li></td> + </tr> + <tr> + <td>job.installations.path</td><td><b>Required:</b> The file system path which contains the Samza job installations. The path must be on the same host as the Samza REST Service. Each installation must be a directory with structure conforming to the expectations of the InstallationRecord implementation used by the JobProxy.</td> + </tr> + <tr> + <td>job.config.factory.class</td><td>The config factory to use for reading Samza job configs. This is used to fetch the job.name and job.id properties for each job instance in the InstallationRecord. It’s also used to validate that a particular directory within the installations path actually contains Samza jobs. If not specified <pre>org.apache.samza.config.factories.PropertiesConfigFactory</pre> will be used. </td> + </tr> + </tbody> +</table> + + + </div> + </div> + + </div><!-- /.wrapper-content --> + </div><!-- /.wrapper --> + + <div class="footer"> + <div class="container"> + <!-- nothing for now. --> + </div> + </div> + + + <script> + $( document ).ready(function() { + if ( $.fn.urlExists( "/learn/documentation/0.10/rest/resources/jobs.html" ) ) { + $("#switch-version-button").addClass("fa fa-history masthead-icon"); + } + }); + + /* a function to test whether the url exists or not */ + (function( $ ) { + $.fn.urlExists = function(url) { + var http = new XMLHttpRequest(); + http.open('HEAD', url, false); + http.send(); + return http.status != 404; + }; + }( jQuery )); + </script> + + + <!-- Google Analytics --> + <script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-43122768-1', 'apache.org'); + ga('send', 'pageview'); + + </script> + </body> +</html> Modified: samza/site/learn/documentation/latest/yarn/application-master.html URL: http://svn.apache.org/viewvc/samza/site/learn/documentation/latest/yarn/application-master.html?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/learn/documentation/latest/yarn/application-master.html (original) +++ samza/site/learn/documentation/latest/yarn/application-master.html Tue Aug 23 17:38:58 2016 @@ -46,7 +46,7 @@ - <a href="http://samza.apache.org/learn/documentation/0.10/yarn/application-master.html";><i id="switch-version-button"></i></a> + <a href="/learn/documentation/0.10/yarn/application-master.html"><i id="switch-version-button"></i></a> <!-- links for the navigation bar --> Modified: samza/site/learn/documentation/latest/yarn/isolation.html URL: http://svn.apache.org/viewvc/samza/site/learn/documentation/latest/yarn/isolation.html?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/learn/documentation/latest/yarn/isolation.html (original) +++ samza/site/learn/documentation/latest/yarn/isolation.html Tue Aug 23 17:38:58 2016 @@ -46,7 +46,7 @@ - <a href="http://samza.apache.org/learn/documentation/0.10/yarn/isolation.html";><i id="switch-version-button"></i></a> + <a href="/learn/documentation/0.10/yarn/isolation.html"><i id="switch-version-button"></i></a> <!-- links for the navigation bar --> Modified: samza/site/learn/documentation/latest/yarn/yarn-host-affinity.html URL: http://svn.apache.org/viewvc/samza/site/learn/documentation/latest/yarn/yarn-host-affinity.html?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/learn/documentation/latest/yarn/yarn-host-affinity.html (original) +++ samza/site/learn/documentation/latest/yarn/yarn-host-affinity.html Tue Aug 23 17:38:58 2016 @@ -46,7 +46,7 @@ - <a href="http://samza.apache.org/learn/documentation/0.10/yarn/yarn-host-affinity.html";><i id="switch-version-button"></i></a> + <a href="/learn/documentation/0.10/yarn/yarn-host-affinity.html"><i id="switch-version-button"></i></a> <!-- links for the navigation bar --> Modified: samza/site/learn/tutorials/latest/deploy-samza-job-from-hdfs.html URL: http://svn.apache.org/viewvc/samza/site/learn/tutorials/latest/deploy-samza-job-from-hdfs.html?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/learn/tutorials/latest/deploy-samza-job-from-hdfs.html (original) +++ samza/site/learn/tutorials/latest/deploy-samza-job-from-hdfs.html Tue Aug 23 17:38:58 2016 @@ -46,7 +46,7 @@ - <a href="http://samza.apache.org/learn/tutorials/0.10/deploy-samza-job-from-hdfs.html";><i id="switch-version-button"></i></a> + <a href="/learn/tutorials/0.10/deploy-samza-job-from-hdfs.html"><i id="switch-version-button"></i></a> <!-- links for the navigation bar --> Modified: samza/site/learn/tutorials/latest/deploy-samza-to-CDH.html URL: http://svn.apache.org/viewvc/samza/site/learn/tutorials/latest/deploy-samza-to-CDH.html?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/learn/tutorials/latest/deploy-samza-to-CDH.html (original) +++ samza/site/learn/tutorials/latest/deploy-samza-to-CDH.html Tue Aug 23 17:38:58 2016 @@ -46,7 +46,7 @@ - <a href="http://samza.apache.org/learn/tutorials/0.10/deploy-samza-to-CDH.html";><i id="switch-version-button"></i></a> + <a href="/learn/tutorials/0.10/deploy-samza-to-CDH.html"><i id="switch-version-button"></i></a> <!-- links for the navigation bar --> Modified: samza/site/learn/tutorials/latest/index.html URL: http://svn.apache.org/viewvc/samza/site/learn/tutorials/latest/index.html?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/learn/tutorials/latest/index.html (original) +++ samza/site/learn/tutorials/latest/index.html Tue Aug 23 17:38:58 2016 @@ -46,7 +46,7 @@ - <a href="http://samza.apache.org/learn/tutorials/0.10/index.html";><i id="switch-version-button"></i></a> + <a href="/learn/tutorials/0.10/index.html"><i id="switch-version-button"></i></a> <!-- links for the navigation bar --> @@ -153,6 +153,8 @@ <p><a href="run-hello-samza-without-internet.html">Run Hello-samza without Internet</a></p> +<p><a href="samza-rest-getting-started.html">Getting Started with Samza REST</a></p> + <!-- TODO a bunch of tutorials [Log Walkthrough](log-walkthrough.html) <a href="configuring-kafka-system.html">Configuring a Kafka System</a><br/> Modified: samza/site/learn/tutorials/latest/remote-debugging-samza.html URL: http://svn.apache.org/viewvc/samza/site/learn/tutorials/latest/remote-debugging-samza.html?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/learn/tutorials/latest/remote-debugging-samza.html (original) +++ samza/site/learn/tutorials/latest/remote-debugging-samza.html Tue Aug 23 17:38:58 2016 @@ -46,7 +46,7 @@ - <a href="http://samza.apache.org/learn/tutorials/0.10/remote-debugging-samza.html";><i id="switch-version-button"></i></a> + <a href="/learn/tutorials/0.10/remote-debugging-samza.html"><i id="switch-version-button"></i></a> <!-- links for the navigation bar --> Modified: samza/site/learn/tutorials/latest/run-hello-samza-without-internet.html URL: http://svn.apache.org/viewvc/samza/site/learn/tutorials/latest/run-hello-samza-without-internet.html?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/learn/tutorials/latest/run-hello-samza-without-internet.html (original) +++ samza/site/learn/tutorials/latest/run-hello-samza-without-internet.html Tue Aug 23 17:38:58 2016 @@ -46,7 +46,7 @@ - <a href="http://samza.apache.org/learn/tutorials/0.10/run-hello-samza-without-internet.html";><i id="switch-version-button"></i></a> + <a href="/learn/tutorials/0.10/run-hello-samza-without-internet.html"><i id="switch-version-button"></i></a> <!-- links for the navigation bar --> Modified: samza/site/learn/tutorials/latest/run-in-multi-node-yarn.html URL: http://svn.apache.org/viewvc/samza/site/learn/tutorials/latest/run-in-multi-node-yarn.html?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/learn/tutorials/latest/run-in-multi-node-yarn.html (original) +++ samza/site/learn/tutorials/latest/run-in-multi-node-yarn.html Tue Aug 23 17:38:58 2016 @@ -46,7 +46,7 @@ - <a href="http://samza.apache.org/learn/tutorials/0.10/run-in-multi-node-yarn.html";><i id="switch-version-button"></i></a> + <a href="/learn/tutorials/0.10/run-in-multi-node-yarn.html"><i id="switch-version-button"></i></a> <!-- links for the navigation bar --> Added: samza/site/learn/tutorials/latest/samza-rest-getting-started.html URL: http://svn.apache.org/viewvc/samza/site/learn/tutorials/latest/samza-rest-getting-started.html?rev=1757411&view=auto ============================================================================== --- samza/site/learn/tutorials/latest/samza-rest-getting-started.html (added) +++ samza/site/learn/tutorials/latest/samza-rest-getting-started.html Tue Aug 23 17:38:58 2016 @@ -0,0 +1,259 @@ +<!DOCTYPE html> +<!-- + 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. +--> +<html lang="en"> + <head> + <meta charset="utf-8"> + <title>Samza - Getting Started with Samza REST</title> + <link href='/css/ropa-sans.css' rel='stylesheet' type='text/css'/> + <link href="/css/bootstrap.min.css" rel="stylesheet"/> + <link href="/css/font-awesome.min.css" rel="stylesheet"/> + <link href="/css/main.css" rel="stylesheet"/> + <link href="/css/syntax.css" rel="stylesheet"/> + <link rel="icon" type="image/png" href="/img/samza-icon.png"> + <script src="/js/jquery-1.11.1.min.js"></script> + </head> + <body> + <div class="wrapper"> + <div class="wrapper-content"> + + <div class="masthead"> + <div class="container"> + <div class="masthead-logo"> + <a href="/" class="logo">samza</a> + </div> + <div class="masthead-icons"> + <div class="pull-right"> + <a href="/startup/download"><i class="fa fa-arrow-circle-o-down masthead-icon"></i></a> + <a href="https://git-wip-us.apache.org/repos/asf?p=samza.git;a=tree"; target="_blank"><i class="fa fa-code masthead-icon" style="font-weight: bold;"></i></a> + <a href="https://twitter.com/samzastream"; target="_blank"><i class="fa fa-twitter masthead-icon"></i></a> + <!-- this icon only shows in versioned pages --> + + + + + <a href="/learn/tutorials/0.10/samza-rest-getting-started.html"><i id="switch-version-button"></i></a> + <!-- links for the navigation bar --> + + + </div> + </div> + </div><!-- /.container --> + </div> + + <div class="container"> + <div class="menu"> + <h1><i class="fa fa-rocket"></i> Getting Started</h1> + <ul> + <li><a href="/startup/hello-samza/latest">Hello Samza</a></li> + <li><a href="/startup/download">Download</a></li> + </ul> + + <h1><i class="fa fa-book"></i> Learn</h1> + <ul> + <li><a href="/learn/documentation/latest">Documentation</a></li> + <li><a href="/learn/documentation/latest/jobs/configuration-table.html">Configuration</a></li> + <li><a href="/learn/documentation/latest/api/javadocs/">Javadocs</a></li> + <li><a href="/learn/tutorials/latest">Tutorials</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/FAQ";>FAQ</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/Apache+Samza";>Wiki</a></li> + <li><a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=51812876";>Papers & Talks</a></li> + <li><a href="http://blogs.apache.org/samza";>Blog</a></li> + </ul> + + <h1><i class="fa fa-comments"></i> Community</h1> + <ul> + <li><a href="/community/mailing-lists.html">Mailing Lists</a></li> + <li><a href="/community/irc.html">IRC</a></li> + <li><a href="https://issues.apache.org/jira/browse/SAMZA";>Bugs</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/Powered+By";>Powered by</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/SAMZA/Ecosystem";>Ecosystem</a></li> + <li><a href="/community/committers.html">Committers</a></li> + </ul> + + <h1><i class="fa fa-code"></i> Contribute</h1> + <ul> + <li><a href="/contribute/rules.html">Rules</a></li> + <li><a href="/contribute/coding-guide.html">Coding Guide</a></li> + <li><a href="/contribute/projects.html">Projects</a></li> + <li><a href="/contribute/design-documents.html">Design Documents</a></li> + <li><a href="/contribute/code.html">Code</a></li> + <li><a href="https://reviews.apache.org/groups/samza";>Review Board</a></li> + <li><a href="/contribute/tests.html">Tests</a></li> + </ul> + + <h1><i class="fa fa-history"></i> Archive</h1> + <ul> + <li><a href="/archive/index.html#latest">latest</a></li> + <li><a href="/archive/index.html#10">0.10</a></li> + <li><a href="/archive/index.html#09">0.9</a></li> + <li><a href="/archive/index.html#08">0.8</a></li> + <li><a href="/archive/index.html#07">0.7</a></li> + </ul> + </div> + + <div class="content"> + <!-- + 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. +--> + +<h2>Getting Started with Samza REST</h2> + +<!-- + 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. +--> + +<p>This tutorial depends on <a href="../../../startup/hello-samza/latest/">hello-samza</a> to start some example jobs on a local cluster, which you will then access via the <a href="../../documentation/latest/rest/resources/jobs.html">JobsResource</a>. After completing this tutorial, you will have built and deployed the Samza REST resource locally, changed the configuration for the JobsResource, and executed a couple of basic curl requests to verify the service works.</p> + +<p>Lets get started.</p> + +<h3 id="run-hello-samza-jobs-locally">Run Hello Samza Jobs Locally</h3> + +<p>Follow the <a href="../../../startup/hello-samza/latest/">hello-samza</a> tutorial to setup a local grid and run the wikipedia jobs. Skip the <a href="../../../startup/hello-samza/latest/#shutdown">shutdown step</a> because you need the grid to still be running to query the REST service for jobs. You can optionally skip all the <code>kafka-console-consumer.sh</code> commands if you don’t want to verify the output of the jobs.</p> + +<p>Take note of the path where you cloned hello-samza. You will need this to configure the installations path for the JobsResource.</p> + +<h4 id="build-the-samza-rest-service-package">Build the Samza REST Service package</h4> + +<p>The source code for Samza REST is in the samza-rest module of the Samza repository. It To build it, execute the following gradle task from the root of the project.</p> + +<div class="highlight"><pre><code class="bash">./gradlew samza-rest:clean releaseRestServiceTar</code></pre></div> + +<h4 id="deploy-the-samza-rest-service-locally">Deploy the Samza REST Service Locally</h4> + +<p>To deploy the service, you simply extract the tarball to the desired location. Here, we will deploy the tarball on the local host in</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">SAMZA_ROOT/samza-rest/build/distributions/deploy/samza-rest +</code></pre></div> +<p>where <code>SAMZA_ROOT</code> is the path to the root of your Samza project.</p> + +<p>Run the following commands:</p> + +<div class="highlight"><pre><code class="bash"><span class="nb">cd </span>samza-rest/build/distributions/ +mkdir -p deploy/samza-rest +tar -xvf ./samza-rest-0.10.1-SNAPSHOT.tgz -C deploy/samza-rest</code></pre></div> + +<h4 id="configure-the-installations-path">Configure the Installations Path</h4> + +<p>The JobsResource has a required config <a href="../../documentation/latest/rest/resources/jobs.html#configuration">job.installations.path</a> which specifies the path where the jobs are installed. Edit the configuration file:</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">deploy/samza-rest/config/samza-rest.properties +</code></pre></div> +<p>Set the job.installations.path to:</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">job.installations.path=/hello-samza-ROOT/deploy +</code></pre></div> +<p>where <code>hello-samza-ROOT</code> is the path to your hello-samza clone, noted above. This tells the JobsResource to crawl this location to find all the installed jobs.</p> + +<h4 id="start-the-samza-rest-service">Start the Samza REST Service</h4> + +<p>To deploy the service, run the run-samza-rest-service.sh script from the extracted directory.</p> + +<div class="highlight"><pre><code class="bash"><span class="nb">cd </span>deploy/samza-rest +./bin/run-samza-rest-service.sh <span class="se">\</span> + --config-factory<span class="o">=</span>org.apache.samza.config.factories.PropertiesConfigFactory <span class="se">\</span> + --config-path<span class="o">=</span>file://<span class="nv">$PWD</span>/config/samza-rest.properties</code></pre></div> + +<p>You provide two parameters to the run-samza-rest-service.sh script. One is the config location, and the other, optional, parameter is a factory class that is used to read your configuration file. The SamzaRestService uses your ConfigFactory to get a Config object from the config path. The ConfigFactory is covered in more detail on the <a href="../../documentation/latest/jobs/job-runner.html">Job Runner page</a>. The run-samza-rest-service.sh script will block until the SamzaRestService terminates.</p> + +<p>Note: With the default settings, the JobsResource will expect a YARN cluster with a local Resource Manager accessible via the ApplicationCLI. Without YARN, the JobsResource will not respond to any requests. So it’s important to walk through hello-samza demo before the next step.</p> + +<h3 id="curl-the-default-rest-service">Curl the Default REST Service</h3> + +<p>Curl the JobsResource to get all installed jobs</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">curl localhost:9139/v1/jobs +[{"jobName":"wikipedia-stats","jobId":"1","status":"STARTED","statusDetail":RUNNING},{"jobName":"wikipedia-parser","jobId":"1","status":"STARTED","statusDetail":RUNNING},{"jobName":"wikipedia-feed","jobId":"1","status":"STARTED","statusDetail":RUNNING} +</code></pre></div> +<p>Now curl the JobsResource to stop one of the jobs</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">curl -X PUT localhost:9139/v1/jobs/wikipedia-feed/1?status=stopped +{"jobId":"1","jobName":"wikipedia-feed","status":"STOPPED","statusDetail":"FINISHED"} +</code></pre></div> +<p>Congratulations, you’ve successfully deployed the Samza REST Service and used the JobsResource to list jobs and stop a job!</p> + +<p>See the <a href="../../documentation/latest/rest/resources/jobs.html">JobsResource documentation</a> for the rest of its API.</p> + +<p>See the <a href="../../documentation/latest/rest/resources.html">Resources documentation</a> for more information about Resources and how you can add your own.</p> + + + </div> + </div> + + </div><!-- /.wrapper-content --> + </div><!-- /.wrapper --> + + <div class="footer"> + <div class="container"> + <!-- nothing for now. --> + </div> + </div> + + + <script> + $( document ).ready(function() { + if ( $.fn.urlExists( "/learn/tutorials/0.10/samza-rest-getting-started.html" ) ) { + $("#switch-version-button").addClass("fa fa-history masthead-icon"); + } + }); + + /* a function to test whether the url exists or not */ + (function( $ ) { + $.fn.urlExists = function(url) { + var http = new XMLHttpRequest(); + http.open('HEAD', url, false); + http.send(); + return http.status != 404; + }; + }( jQuery )); + </script> + + + <!-- Google Analytics --> + <script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-43122768-1', 'apache.org'); + ga('send', 'pageview'); + + </script> + </body> +</html> Modified: samza/site/sitemap.xml URL: http://svn.apache.org/viewvc/samza/site/sitemap.xml?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/sitemap.xml (original) +++ samza/site/sitemap.xml Tue Aug 23 17:38:58 2016 @@ -20,7 +20,7 @@ <url> <loc>http://samza.apache.org/</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> <changefreq>daily</changefreq> <priority>1.0</priority> </url> @@ -30,364 +30,406 @@ <url> <loc>http://samza.apache.org/learn/documentation/versioned/yarn/application-master.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/introduction/architecture.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/introduction/background.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/container/checkpointing.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/contribute/code.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/contribute/coding-guide.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/community/committers.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/introduction/concepts.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/jobs/configuration.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/container/coordinator-stream.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/tutorials/versioned/deploy-samza-job-from-hdfs.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/tutorials/versioned/deploy-samza-to-CDH.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/contribute/design-documents.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/container/event-loop.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/index.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/archive/index.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/tutorials/versioned/index.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/index.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/startup/download/index.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/startup/hello-samza/versioned/index.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/comparisons/introduction.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/community/irc.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/yarn/isolation.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/container/jmx.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/jobs/job-runner.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> + + + </url> + + <url> + <loc>http://samza.apache.org/learn/documentation/versioned/rest/resources/jobs.html</loc> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/operations/kafka.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/jobs/logging.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/community/mailing-lists.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/container/metrics.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> + + + </url> + + <url> + <loc>http://samza.apache.org/learn/documentation/versioned/rest/monitors.html</loc> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/comparisons/mupd8.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/api/overview.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> + + + </url> + + <url> + <loc>http://samza.apache.org/learn/documentation/versioned/rest/overview.html</loc> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/jobs/packaging.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/hdfs/producer.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/contribute/projects.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/tutorials/versioned/remote-debugging-samza.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/jobs/reprocessing.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> + + + </url> + + <url> + <loc>http://samza.apache.org/learn/documentation/versioned/rest/resource-directory.html</loc> + <lastmod>2016-08-23</lastmod> + + + </url> + + <url> + <loc>http://samza.apache.org/learn/documentation/versioned/rest/resources.html</loc> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/contribute/rules.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/tutorials/versioned/run-hello-samza-without-internet.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/tutorials/versioned/run-in-multi-node-yarn.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/container/samza-container.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> + + + </url> + + <url> + <loc>http://samza.apache.org/learn/tutorials/versioned/samza-rest-getting-started.html</loc> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/operations/security.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/container/serialization.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/comparisons/spark-streaming.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/container/state-management.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/comparisons/storm.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/container/streams.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/contribute/tests.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/jobs/web-ui-rest-api.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/container/windowing.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/yarn/yarn-host-affinity.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/jobs/yarn-jobs.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> <url> <loc>http://samza.apache.org/learn/documentation/versioned/yarn/yarn-security.html</loc> - <lastmod>2016-08-09</lastmod> + <lastmod>2016-08-23</lastmod> </url> Modified: samza/site/startup/hello-samza/latest/index.html URL: http://svn.apache.org/viewvc/samza/site/startup/hello-samza/latest/index.html?rev=1757411&r1=1757410&r2=1757411&view=diff ============================================================================== --- samza/site/startup/hello-samza/latest/index.html (original) +++ samza/site/startup/hello-samza/latest/index.html Tue Aug 23 17:38:58 2016 @@ -46,7 +46,7 @@ - <a href="http://samza.apache.org/startup/hello-samza/0.10/index.html";><i id="switch-version-button"></i></a> + <a href="/startup/hello-samza/0.10/index.html"><i id="switch-version-button"></i></a> <!-- links for the navigation bar -->
