PyPI - amps-python-client - Versions diffs - 5.3.4.1__zip → 5.3.4.3__zip - Mend

amps-python-client 5.3.4.1zip → 5.3.4.3zip

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (918) hide show

amps-python-client-5.3.4.3/docs/user-guide/html/chapters/spark.html ADDED Viewed

@@ -0,0 +1,819 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>33. Spark &#8212; AMPS User Guide 5.3.4.0 documentation</title>
+    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '../',
+        VERSION:     '5.3.4.0',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true,
+        SOURCELINK_SUFFIX: '.txt'
+      };
+    </script>
+    <script type="text/javascript" src="../_static/jquery.js"></script>
+    <script type="text/javascript" src="../_static/underscore.js"></script>
+    <script type="text/javascript" src="../_static/doctools.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" />
+    <link rel="next" title="34. Auxiliary Modules" href="auxiliary_modules.html" />
+    <link rel="prev" title="32. Configuration File Shortcuts" href="config-file-shortcuts.html" />
+  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+  </head>
+  <body role="document">
+  <div class="document">
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+            <p class="logo"><a href="../index.html">
+              <img class="logo" src="../_static/flag_logo.png" alt="Logo"/>
+            </a></p>
+  <h3><a href="../index.html">Table Of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">33. Spark</a><ul>
+<li><a class="reference internal" href="#getting-help-with-spark">Getting Help with Spark</a></li>
+<li><a class="reference internal" href="#spark-commands">Spark Commands</a><ul>
+<li><a class="reference internal" href="#publish">Publish</a><ul>
+<li><a class="reference internal" href="#common-options-spark-publish">Common Options - Spark Publish</a></li>
+<li><a class="reference internal" href="#examples">Examples</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#sow">SOW</a><ul>
+<li><a class="reference internal" href="#common-options-spark-sow">Common Options - Spark SOW</a></li>
+<li><a class="reference internal" href="#id2">Examples</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#subscribe">Subscribe</a><ul>
+<li><a class="reference internal" href="#common-options-spark-subscribe">Common Options - Spark Subscribe</a></li>
+<li><a class="reference internal" href="#id3">Examples</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#sow-and-subscribe">sow_and_subscribe</a><ul>
+<li><a class="reference internal" href="#common-options-spark-sow-and-subscribe">Common Options - Spark sow_and_subscribe</a></li>
+<li><a class="reference internal" href="#id4">Examples</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#sow-delete">sow_delete</a><ul>
+<li><a class="reference internal" href="#common-options-sow-delete">Common Options - sow_delete</a></li>
+<li><a class="reference internal" href="#id5">Examples</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ping">Ping</a><ul>
+<li><a class="reference internal" href="#common-options-spark-ping">Common Options - Spark Ping</a></li>
+<li><a class="reference internal" href="#id6">Examples</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#spark-authentication">Spark Authentication</a></li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+  <li><a href="../index.html">Documentation overview</a><ul>
+      <li>Previous: <a href="config-file-shortcuts.html" title="previous chapter">32. Configuration File Shortcuts</a></li>
+      <li>Next: <a href="auxiliary_modules.html" title="next chapter">34. Auxiliary Modules</a></li>
+  </ul></li>
+</ul>
+</div>
+<div id="searchbox" style="display: none" role="search">
+  <h3>Quick search</h3>
+    <form class="search" action="../search.html" method="get">
+      <div><input type="text" name="q" /></div>
+      <div><input type="submit" value="Go" /></div>
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+  <div class="section" id="spark">
+<span id="utilities-spark"></span><span id="id1"></span><h1>33. Spark<a class="headerlink" href="#spark" title="Permalink to this headline">¶</a></h1>
+<p id="index-0">AMPS contains a basic command-line client, <code class="docutils literal"><span class="pre">spark</span></code>, which can be used
+to run queries, place subscriptions, and publish data. While it
+provides support for each of these functions, <code class="docutils literal"><span class="pre">spark</span></code> is provided as
+a useful tool for informal testing and troubleshooting of AMPS instances
+and is not intended to be a replacement for a client library. For example, you
+can use <code class="docutils literal"><span class="pre">spark</span></code> to test whether an AMPS instance is reachable from a
+particular system, or use <code class="docutils literal"><span class="pre">spark</span></code> to perform <em>ad hoc</em> queries to
+inspect the data in AMPS. <code class="docutils literal"><span class="pre">spark</span></code> does not support all of the
+features available in AMPS client libraries, and does not display
+the headers or metadata returned by AMPS.</p>
+<p>This chapter describes the commands available in the <code class="docutils literal"><span class="pre">spark</span></code> utility.
+For more information on the features available in AMPS, see the
+relevant chapters within this <em>User Guide</em>.</p>
+<p>The <code class="docutils literal"><span class="pre">spark</span></code> utility is included in the <code class="docutils literal"><span class="pre">bin</span></code> directory of the AMPS
+install location. The <code class="docutils literal"><span class="pre">spark</span></code> client is written in Java, so running
+<code class="docutils literal"><span class="pre">spark</span></code> requires a Java Virtual Machine for Java 1.7 or later.</p>
+<p>To run this client, simply type <code class="docutils literal"><span class="pre">./bin/spark</span></code> at the command line from
+the AMPS installation directory. AMPS will output the help screen as
+shown below, with a brief description of the <code class="docutils literal"><span class="pre">spark</span></code> client features.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></span>%&gt; ./bin/spark
+<span class="o">===============================</span>
+- Spark - AMPS client utility -
+<span class="o">===============================</span>
+Usage:
+    spark <span class="nb">help</span> <span class="o">[</span>command<span class="o">]</span>
+Supported Commands:
+    <span class="nb">help</span>
+    ping
+    publish
+    sow
+    sow_and_subscribe
+    sow_delete
+    subscribe
+Example:
+    %&gt; ./spark <span class="nb">help</span> sow
+Returns the <span class="nb">help</span> and usage information <span class="k">for</span> the <span class="s1">&#39;sow&#39;</span> command.
+</pre></div>
+</div>
+<p><em>Spark screen usage</em></p>
+<div class="section" id="getting-help-with-spark">
+<h2>Getting Help with Spark<a class="headerlink" href="#getting-help-with-spark" title="Permalink to this headline">¶</a></h2>
+<p><code class="docutils literal"><span class="pre">spark</span></code> requires that a supported command is passed as an argument. Within
+each supported command, there are additional unique requirements and
+options available to change the behavior of <code class="docutils literal"><span class="pre">spark</span></code> and how it interacts
+with the AMPS engine.</p>
+<p>For example, if more information was needed to run a <code class="docutils literal"><span class="pre">publish</span></code> command
+in <code class="docutils literal"><span class="pre">spark</span></code>, the following would display the help screen for the <code class="docutils literal"><span class="pre">spark</span></code>
+client&#8217;s <code class="docutils literal"><span class="pre">publish</span></code> feature.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></span>%&gt;./spark <span class="nb">help</span> <span class="nv">publish</span>
+<span class="o">===============================</span>
+- Spark - AMPS client utility -
+<span class="o">===============================</span>
+Usage:
+  spark publish <span class="o">[</span>options<span class="o">]</span>
+Required Parameters:
+  server    -- AMPS server to connect to
+  topic     -- topic to publish to
+Options:
+  authenticator -- Custom AMPS authenticator factory to use
+  delimiter     -- decimal value of message separator character
+                   <span class="o">(</span>default <span class="m">10</span><span class="o">)</span>
+  delta         -- use delta publish
+  file          -- file to publish records from, standard <span class="k">in</span> when omitted
+  proto         -- protocol to use <span class="o">(</span>amps, fix, nvfix, xml<span class="o">)</span>
+                   <span class="o">(</span>type, prot are synonyms <span class="k">for</span> backward compatibility<span class="o">)</span>
+                   <span class="o">(</span>default: amps<span class="o">)</span>
+  rate          -- decimal value used to send messages
+                   at a fixed rate.  <span class="s1">&#39;.25&#39;</span> implies <span class="m">1</span> message every
+                   <span class="m">4</span> seconds. <span class="s1">&#39;1000&#39;</span> implies <span class="m">1000</span> messages per second.
+Example:
+  % ./spark publish -server localhost:9003 -topic Trades -file data.fix
+    Connects to the AMPS instance listening on port <span class="m">9003</span> and publishes records
+    found <span class="k">in</span> the <span class="s1">&#39;data.fix&#39;</span> file to topic <span class="s1">&#39;Trades&#39;</span>.
+</pre></div>
+</div>
+<p><em>Usage of Spark publish command</em></p>
+</div>
+<div class="section" id="spark-commands">
+<h2>Spark Commands<a class="headerlink" href="#spark-commands" title="Permalink to this headline">¶</a></h2>
+<p>Below, the commands supported by <code class="docutils literal"><span class="pre">spark</span></code> will be shown, along with
+some examples of how to use the various commands and descriptions of the
+most commonly used options. For the full range of options provided by
+<code class="docutils literal"><span class="pre">spark</span></code>, including options provided for compatibility with previous
+<code class="docutils literal"><span class="pre">spark</span></code> releases, use the <code class="docutils literal"><span class="pre">spark</span> <span class="pre">help</span></code> command as described above.</p>
+<div class="section" id="publish">
+<h3>Publish<a class="headerlink" href="#publish" title="Permalink to this headline">¶</a></h3>
+<p id="index-1">The <code class="docutils literal"><span class="pre">publish</span></code> command is used to publish data to a topic on an AMPS
+server.</p>
+<div class="section" id="common-options-spark-publish">
+<h4>Common Options - Spark Publish<a class="headerlink" href="#common-options-spark-publish" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils" id="id7">
+<caption><span class="caption-text"><em>Spark publish options</em></span><a class="headerlink" href="#id7" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Option</strong></th>
+<th class="head"><strong>Definition</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">server</span>
+</pre></div>
+</div>
+</td>
+<td>AMPS server to connect to.</td>
+</tr>
+<tr class="row-odd"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">topic</span>
+</pre></div>
+</div>
+</td>
+<td>Topic to publish to.</td>
+</tr>
+<tr class="row-even"><td>delimiter</td>
+<td>Decimal value of message separator character (default 10).</td>
+</tr>
+<tr class="row-odd"><td>delta</td>
+<td>Use delta publish (sends a <code class="docutils literal"><span class="pre">delta_publish</span></code> command to
+AMPS).</td>
+</tr>
+<tr class="row-even"><td>file</td>
+<td>File to publish messages from, stdin when omitted. <code class="docutils literal"><span class="pre">spark</span></code>
+interprets each line in the input as a message. The file
+provided to this argument can be either uncompressed or
+compressed in ZIP format.</td>
+</tr>
+<tr class="row-odd"><td>proto</td>
+<td><p class="first">Protocol to use. In this release, <code class="docutils literal"><span class="pre">spark</span></code> supports
+<code class="docutils literal"><span class="pre">amps</span></code>, <code class="docutils literal"><span class="pre">fix</span></code>, <code class="docutils literal"><span class="pre">nvfix</span></code> and <code class="docutils literal"><span class="pre">xml</span></code>. Defaults to
+<code class="docutils literal"><span class="pre">amps</span></code>.</p>
+<p class="last"><code class="docutils literal"><span class="pre">spark</span></code> also supports <code class="docutils literal"><span class="pre">json</span></code> as a synonym for <code class="docutils literal"><span class="pre">amps</span></code>
+in this release.</p>
+</td>
+</tr>
+<tr class="row-even"><td>rate</td>
+<td>Messages to publish per second. This is a decimal value, so
+values less than 1 can be provided to create a delay of more
+than a second between messages. &#8216;.25&#8217; implies 1 message
+every 4 seconds. &#8216;1000&#8217; implies 1000 messages per second.</td>
+</tr>
+<tr class="row-odd"><td>type</td>
+<td>For protocols and transports that accept multiple message
+types on a given transport, this specifies the message type
+to use.</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="examples">
+<h4>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h4>
+<p>The examples shown below will demonstrate how to publish records to
+AMPS using the <code class="docutils literal"><span class="pre">spark</span></code> client in one of the three following ways: a
+single record, a python script or by file.</p>
+<p><strong>Publish a Single Message</strong></p>
+<div class="highlight-bash" id="spark-publish-single-record"><div class="highlight"><pre><span></span>%&gt; <span class="nb">echo</span> <span class="s1">&#39;{ &quot;id&quot; : 1, &quot;data&quot;: &quot;hello, world!&quot; }&#39;</span> <span class="p">|</span>  <span class="se">\</span>
+   ./spark publish -server localhost:9007 -type json -topic order
+   total messages published: <span class="m">1</span> <span class="o">(</span><span class="m">50</span>.00/s<span class="o">)</span>
+</pre></div>
+</div>
+<p><em>Publishing a single XML message</em></p>
+<p>In the example shown above, a single record is published to AMPS using the
+<code class="docutils literal"><span class="pre">echo</span></code> command. If you are comfortable with creating records by hand
+this is a simple and effective way to test publishing in AMPS.</p>
+<p>The JSON message is published to the topic <em>order</em> on the AMPS instance.
+This publish can be followed with a <code class="docutils literal"><span class="pre">sow</span></code> command in <code class="docutils literal"><span class="pre">spark</span></code> to test
+if the record was indeed published to the <em>order</em> topic.</p>
+<p><strong>Publish using Python</strong></p>
+<div class="highlight-bash" id="spark-publish-python"><div class="highlight"><pre><span></span>%&gt; python -c <span class="s2">&quot;for n in xrange(100): print &#39;{\&quot;id\&quot;:%d}&#39; % n&quot;</span> <span class="p">|</span> <span class="se">\</span>
+   ./spark publish -topic disorder -type json -rate <span class="m">50</span> <span class="se">\</span>
+   -server localhost:9007
+   total messages published: <span class="m">100</span> <span class="o">(</span><span class="m">50</span>.00/s<span class="o">)</span>
+</pre></div>
+</div>
+<p><em>Publish multiple messages using Python</em></p>
+<p>In the example shown above, the <code class="docutils literal"><span class="pre">-c</span></code> flag is used to pass in a simple
+loop and print command to the python interpreter and have it print the
+results to <code class="docutils literal"><span class="pre">stdout</span></code>.</p>
+<p>The python script generates 100 JSON messages of the form <code class="docutils literal"><span class="pre">{&quot;id&quot;:0}</span></code>,
+<code class="docutils literal"><span class="pre">{&quot;id&quot;:1}</span></code> ... <code class="docutils literal"><span class="pre">{&quot;id&quot;:99}</span></code>. The output of this command is then
+<em>piped</em> to spark using the <code class="docutils literal"><span class="pre">|</span></code> character, which will publish the
+messages to the <em>disorder</em> topic inside the AMPS instance.</p>
+<p><strong>Publish from a File</strong></p>
+<div class="highlight-bash" id="spark-publish-file"><div class="highlight"><pre><span></span>%&gt; ./spark publish -server localhost:9007 -type json -topic chaos <span class="se">\</span>
+   -file data.json
+   total messages published: <span class="m">50</span> <span class="o">(</span><span class="m">12000</span>.00/s<span class="o">)</span>
+</pre></div>
+</div>
+<p><em>Spark publish from a file</em></p>
+<p>Generating a file of test data is a common way to test AMPS
+functionality. The example shown above demonstrates how to publish
+a file of data to the topic <em>chaos</em> in an AMPS server. As previously
+mentioned, <code class="docutils literal"><span class="pre">spark</span></code> interprets each line of the file as a distinct message.</p>
+</div>
+</div>
+<div class="section" id="sow">
+<h3>SOW<a class="headerlink" href="#sow" title="Permalink to this headline">¶</a></h3>
+<p id="index-2">The <code class="docutils literal"><span class="pre">sow</span></code> command allows a <code class="docutils literal"><span class="pre">spark</span></code> client to query the latest
+messages which have been persisted to a topic. The SOW in AMPS acts as a
+database last update cache, and the <code class="docutils literal"><span class="pre">sow</span></code> command in <code class="docutils literal"><span class="pre">spark</span></code> is one
+of the ways to query the database. This <code class="docutils literal"><span class="pre">sow</span></code> command supports regular
+expression topic matching and content filtering, which allow a query to
+be very specific when looking for data.</p>
+<p>For the <code class="docutils literal"><span class="pre">sow</span></code> command to succeed, the topic queried must provide a
+SOW. This includes SOW topics and views, queues, and conflated topics.
+These features of AMPS are discussed in more detail within this <em>User Guide</em>.</p>
+<div class="section" id="common-options-spark-sow">
+<h4>Common Options - Spark SOW<a class="headerlink" href="#common-options-spark-sow" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils" id="id8">
+<caption><span class="caption-text"><em>Spark sow options</em></span><a class="headerlink" href="#id8" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Option</strong></th>
+<th class="head"><strong>Definition</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">server</span>
+</pre></div>
+</div>
+</td>
+<td>AMPS server to connect to.</td>
+</tr>
+<tr class="row-odd"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">topic</span>
+</pre></div>
+</div>
+</td>
+<td>Topic to query.</td>
+</tr>
+<tr class="row-even"><td>batchsize</td>
+<td>Batch Size to use during query. A batch size &gt; 1 can help
+improve performance, as described in the chapter of the
+<em>User Guide</em> discussing the SOW.</td>
+</tr>
+<tr class="row-odd"><td>filter</td>
+<td>The content filter to use.</td>
+</tr>
+<tr class="row-even"><td>proto</td>
+<td><p class="first">Protocol to use. In this release, <code class="docutils literal"><span class="pre">spark</span></code> supports
+<code class="docutils literal"><span class="pre">amps</span></code>, <code class="docutils literal"><span class="pre">fix</span></code>, <code class="docutils literal"><span class="pre">nvfix</span></code> and <code class="docutils literal"><span class="pre">xml</span></code>. Defaults to
+<code class="docutils literal"><span class="pre">amps</span></code>.</p>
+<p class="last"><code class="docutils literal"><span class="pre">spark</span></code> also supports <code class="docutils literal"><span class="pre">json</span></code> as a synonym for <code class="docutils literal"><span class="pre">amps</span></code>
+in this release.</p>
+</td>
+</tr>
+<tr class="row-odd"><td>orderby</td>
+<td>An expression that AMPS will use to order the results.</td>
+</tr>
+<tr class="row-even"><td>topn</td>
+<td>Request AMPS to limit the query response to the first N
+records returned.</td>
+</tr>
+<tr class="row-odd"><td>type</td>
+<td>For protocols and transports that accept multiple message
+types on a given transport, this specifies the message type
+to use.</td>
+</tr>
+<tr class="row-even"><td>format</td>
+<td><p class="first">Optional format used for displaying messages. May contain
+literal separator characters mixed with format tags. Allowed
+tags are: <code class="docutils literal"><span class="pre">{bookmark}</span></code>, <code class="docutils literal"><span class="pre">{command}</span></code>,
+<code class="docutils literal"><span class="pre">{correlation_id}</span></code>, <code class="docutils literal"><span class="pre">{data}</span></code>, <code class="docutils literal"><span class="pre">{expiration}</span></code>,
+<code class="docutils literal"><span class="pre">{lease_period}</span></code>, <code class="docutils literal"><span class="pre">{length}</span></code>, <code class="docutils literal"><span class="pre">{sowkey}</span></code>,
+<code class="docutils literal"><span class="pre">{user_id}</span></code>, <code class="docutils literal"><span class="pre">{timestamp}</span></code>, <code class="docutils literal"><span class="pre">{topic}</span></code></p>
+<p>Notice that not all headers may be available on every
+request, depending on the options provided to the request.
+See the AMPS Command Reference for details.</p>
+<p class="last">Example: <code class="docutils literal"><span class="pre">-format</span> <span class="pre">&quot;{command}:{data}&quot;</span></code></p>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="id2">
+<h4>Examples<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-bash"><div class="highlight"><pre><span></span>%&gt; ./spark sow -server localhost:9007 -type json -topic order -filter <span class="s2">&quot;/id = &#39;1&#39;&quot;</span>
+<span class="o">{</span> <span class="s2">&quot;id&quot;</span> : <span class="m">1</span>, <span class="s2">&quot;data&quot;</span> : <span class="s2">&quot;hello, world&quot;</span> <span class="o">}</span>
+Total messages received: <span class="m">1</span> <span class="o">(</span>Infinity/s<span class="o">)</span>
+</pre></div>
+</div>
+<p><em>Spark SOW Query</em></p>
+<p>This <code class="docutils literal"><span class="pre">sow</span></code> command will query the <em>order</em> topic and filter results
+which match the xpath expression <code class="docutils literal"><span class="pre">/id</span> <span class="pre">=</span> <span class="pre">'1'</span></code>. This query will return
+the result published in the
+<a class="reference internal" href="#spark-publish-single-record"><span class="std std-ref">publish a single record</span></a> example.</p>
+<p>If the topic does not provide a SOW, the command returns an error
+indicating that the command is not valid for that topic.</p>
+</div>
+</div>
+<div class="section" id="subscribe">
+<h3>Subscribe<a class="headerlink" href="#subscribe" title="Permalink to this headline">¶</a></h3>
+<p id="index-3">The <code class="docutils literal"><span class="pre">subscribe</span></code> command allows a <code class="docutils literal"><span class="pre">spark</span></code> client to query all
+incoming messages to a topic in real time. Similar to the <code class="docutils literal"><span class="pre">sow</span></code>
+command, the <code class="docutils literal"><span class="pre">subscribe</span></code> command supports regular expression topic
+matching and content filtering, which allow a query to be very specific
+when looking for data as it is published to AMPS. Unlike the <code class="docutils literal"><span class="pre">sow</span></code>
+command, a subscription can be placed on a topic which does not have a
+persistent SOW cache configured. This allows a <code class="docutils literal"><span class="pre">subscribe</span></code> command to be
+very flexible in the messages it can be configured to receive.</p>
+<div class="section" id="common-options-spark-subscribe">
+<h4>Common Options - Spark Subscribe<a class="headerlink" href="#common-options-spark-subscribe" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils">
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Option</strong></th>
+<th class="head"><strong>Definition</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">server</span>
+</pre></div>
+</div>
+</td>
+<td>AMPS server to connect to.</td>
+</tr>
+<tr class="row-odd"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">topic</span>
+</pre></div>
+</div>
+</td>
+<td>Topic to subscribe to.</td>
+</tr>
+<tr class="row-even"><td>delta</td>
+<td>Use delta subscription (sends a <code class="docutils literal"><span class="pre">delta_subscribe</span></code> command
+to AMPS).</td>
+</tr>
+<tr class="row-odd"><td>filter</td>
+<td>Content filter to use.</td>
+</tr>
+<tr class="row-even"><td>proto</td>
+<td><p class="first">Protocol to use. In this release, <code class="docutils literal"><span class="pre">spark</span></code> supports
+<code class="docutils literal"><span class="pre">amps</span></code>, <code class="docutils literal"><span class="pre">fix</span></code>, <code class="docutils literal"><span class="pre">nvfix</span></code> and <code class="docutils literal"><span class="pre">xml</span></code>. Defaults to
+<code class="docutils literal"><span class="pre">amps</span></code>.</p>
+<p class="last"><code class="docutils literal"><span class="pre">spark</span></code> also supports <code class="docutils literal"><span class="pre">json</span></code> as a synonym for <code class="docutils literal"><span class="pre">amps</span></code>
+in this release.</p>
+</td>
+</tr>
+<tr class="row-odd"><td>ack</td>
+<td>Enable acknowledgments when receiving from a queue. Notice
+that, when this option is provided, <code class="docutils literal"><span class="pre">spark</span></code> acknowledges
+messages from the queue, signaling to AMPS that the message
+has been fully processed. (See the <em>User Guide</em> chapter on
+AMPS message queues for more information.)</td>
+</tr>
+<tr class="row-even"><td>backlog</td>
+<td>Request a <code class="docutils literal"><span class="pre">max_backlog</span></code> of greater than 1 when receiving
+from a queue. (See the <em>User Guide</em> chapter on AMPS message
+queues for more information.)</td>
+</tr>
+<tr class="row-odd"><td>type</td>
+<td>For protocols and transports that accept multiple message
+types on a given transport, this specifies the message type
+to use.</td>
+</tr>
+<tr class="row-even"><td>format</td>
+<td><p class="first">Optional format used for displaying messages. May contain
+literal separator characters mixed with format tags. Allowed
+tags are: <code class="docutils literal"><span class="pre">{bookmark}</span></code>, <code class="docutils literal"><span class="pre">{command}</span></code>,
+<code class="docutils literal"><span class="pre">{correlation_id}</span></code>, <code class="docutils literal"><span class="pre">{data}</span></code>, <code class="docutils literal"><span class="pre">{expiration}</span></code>,
+<code class="docutils literal"><span class="pre">{lease_period}</span></code>, <code class="docutils literal"><span class="pre">{length}</span></code>, <code class="docutils literal"><span class="pre">{sowkey}</span></code>,
+<code class="docutils literal"><span class="pre">{user_id}</span></code>, <code class="docutils literal"><span class="pre">{timestamp}</span></code>, <code class="docutils literal"><span class="pre">{topic}</span></code></p>
+<p>Notice that not all headers may be available on every
+request, depending on the options provided to the request.
+See the AMPS Command Reference for details.</p>
+<p class="last">Example: <code class="docutils literal"><span class="pre">-format</span> <span class="pre">&quot;{command}:{data}&quot;</span></code></p>
+</td>
+</tr>
+</tbody>
+</table>
+<p><em>Spark subscribe options</em></p>
+</div>
+<div class="section" id="id3">
+<h4>Examples<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-bash" id="spark-subscribe"><div class="highlight"><pre><span></span> %&gt; ./spark subscribe -server localhost:9007 -topic chaos <span class="se">\</span>
+                        -type json -filter <span class="s2">&quot;/name = &#39;cup&#39;&quot;</span>
+<span class="o">{</span> <span class="s2">&quot;name&quot;</span> : <span class="s2">&quot;cup&quot;</span>, <span class="s2">&quot;place&quot;</span> : <span class="s2">&quot;cupboard&quot;</span> <span class="o">}</span>
+</pre></div>
+</div>
+<p><em>Spark subscribe Example</em></p>
+<p>The example above places a subscription on the <em>chaos</em> topic with a filter
+that will only return results for messages where <code class="docutils literal"><span class="pre">/name</span> <span class="pre">=</span> <span class="pre">'cup'</span></code>.
+If we place this subscription before executing the <code class="docutils literal"><span class="pre">publish</span></code> command in  the
+<a class="reference internal" href="#spark-publish-file"><span class="std std-ref">publish records from a file</span></a> example,
+we will get the results listed above.</p>
+</div>
+</div>
+<div class="section" id="sow-and-subscribe">
+<h3>sow_and_subscribe<a class="headerlink" href="#sow-and-subscribe" title="Permalink to this headline">¶</a></h3>
+<p id="index-4">The <code class="docutils literal"><span class="pre">sow_and_subscribe</span></code> command is a combination of the <code class="docutils literal"><span class="pre">sow</span></code>
+command and the <code class="docutils literal"><span class="pre">subscribe</span></code> command. When a <code class="docutils literal"><span class="pre">sow_and_subscribe</span></code> is
+requested, AMPS will first return all messages which match the query and
+are stored in the SOW. Once this has completed, all messages which match
+the subscription query will then be sent to the client.</p>
+<p>The <code class="docutils literal"><span class="pre">sow_and_subscribe</span></code> command is a powerful tool to use when it is necessary
+to examine both the contents of the SOW, and the live subscription stream.</p>
+<div class="section" id="common-options-spark-sow-and-subscribe">
+<h4>Common Options - Spark sow_and_subscribe<a class="headerlink" href="#common-options-spark-sow-and-subscribe" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils" id="id9">
+<caption><span class="caption-text"><em>Spark sow_and_subscribe options</em></span><a class="headerlink" href="#id9" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Option</strong></th>
+<th class="head"><strong>Definition</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">server</span>
+</pre></div>
+</div>
+</td>
+<td>AMPS server to connect to.</td>
+</tr>
+<tr class="row-odd"><td><p class="first">.code</p>
+<div class="last highlight-default"><div class="highlight"><pre><span></span><span class="n">topic</span>
+</pre></div>
+</div>
+</td>
+<td>Topic to query and subscribe to.</td>
+</tr>
+<tr class="row-even"><td>batchsize</td>
+<td>Batch Size to use during query.</td>
+</tr>
+<tr class="row-odd"><td>delta</td>
+<td>Request delta for subscriptions (sends a
+<code class="docutils literal"><span class="pre">sow_and_delta_subscribe</span></code> command to AMPS).</td>
+</tr>
+<tr class="row-even"><td>filter</td>
+<td>Content filter to use.</td>
+</tr>
+<tr class="row-odd"><td>proto</td>
+<td><p class="first">Protocol to use. In this release, <code class="docutils literal"><span class="pre">spark</span></code> supports
+<code class="docutils literal"><span class="pre">amps</span></code>, <code class="docutils literal"><span class="pre">fix</span></code>, <code class="docutils literal"><span class="pre">nvfix</span></code> and <code class="docutils literal"><span class="pre">xml</span></code>. Defaults to
+<code class="docutils literal"><span class="pre">amps</span></code>.</p>
+<p class="last"><code class="docutils literal"><span class="pre">spark</span></code> also supports <code class="docutils literal"><span class="pre">json</span></code> as a synonym for <code class="docutils literal"><span class="pre">amps</span></code>
+in this release.</p>
+</td>
+</tr>
+<tr class="row-even"><td>orderby</td>
+<td>An expression that AMPS will use to order the SOW query
+results.</td>
+</tr>
+<tr class="row-odd"><td>topn</td>
+<td>Request AMPS to limit the SOW query results to the first N
+records returned.</td>
+</tr>
+<tr class="row-even"><td>type</td>
+<td>For protocols and transports that accept multiple message
+types on a given transport, this specifies the message type
+to use.</td>
+</tr>
+<tr class="row-odd"><td>format</td>
+<td><p class="first">Optional format used for displaying messages. May contain
+literal separator characters mixed with format tags. Allowed
+tags are: <code class="docutils literal"><span class="pre">{bookmark}</span></code>, <code class="docutils literal"><span class="pre">{command}</span></code>,
+<code class="docutils literal"><span class="pre">{correlation_id}</span></code>, <code class="docutils literal"><span class="pre">{data}</span></code>, <code class="docutils literal"><span class="pre">{expiration}</span></code>,
+<code class="docutils literal"><span class="pre">{lease_period}</span></code>, <code class="docutils literal"><span class="pre">{length}</span></code>, <code class="docutils literal"><span class="pre">{sowkey}</span></code>,
+<code class="docutils literal"><span class="pre">{user_id}</span></code>, <code class="docutils literal"><span class="pre">{timestamp}</span></code>, <code class="docutils literal"><span class="pre">{topic}</span></code></p>
+<p>Notice that not all headers may be available on every
+request, depending on the options provided to the request.
+See the AMPS Command Reference for details.</p>
+<p class="last">Example: <code class="docutils literal"><span class="pre">-format</span> <span class="pre">&quot;{command}:{data}&quot;</span></code></p>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="id4">
+<h4>Examples<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<div class="code bash highlight-default" id="spark-sow-and-subscribe"><div class="highlight"><pre><span></span><span class="o">%&gt;</span> <span class="o">./</span><span class="n">spark</span> <span class="n">sow_and_subscribe</span> <span class="o">-</span><span class="n">server</span> <span class="n">localhost</span><span class="p">:</span><span class="mi">9007</span> <span class="o">-</span><span class="nb">type</span> <span class="n">json</span> \
+                               <span class="o">-</span><span class="n">topic</span> <span class="n">chaos</span> <span class="o">-</span><span class="nb">filter</span> <span class="s2">&quot;/name = &#39;cup&#39;&quot;</span>
+<span class="p">{</span> <span class="s2">&quot;name&quot;</span> <span class="p">:</span> <span class="s2">&quot;cup&quot;</span><span class="p">,</span> <span class="s2">&quot;place&quot;</span> <span class="p">:</span> <span class="s2">&quot;cupboard&quot;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p><em>Spark SOW and subscribe example</em></p>
+<p>In the example above, the same topic and filter are being used as in the <code class="docutils literal"><span class="pre">subscribe</span></code>
+example in the <a class="reference internal" href="#spark-subscribe"><span class="std std-ref">spark subscribe</span></a> example.
+The results of this query initially are similar also, since only the messages which are
+stored in the SOW are returned. If a publisher were started that published data to the
+topic that matched the content filter, those messages would then be printed out to the
+screen in the same manner as a <code class="docutils literal"><span class="pre">subscription</span></code>.</p>
+</div>
+</div>
+<div class="section" id="sow-delete">
+<h3>sow_delete<a class="headerlink" href="#sow-delete" title="Permalink to this headline">¶</a></h3>
+<p id="index-5">The <code class="docutils literal"><span class="pre">sow_delete</span></code> command is used to remove records from the SOW topic
+in AMPS. If a filter is specified, only messages which match the filter
+will be removed. If a file is provided, the command reads messages from
+the file and sends those messages to AMPS. AMPS will delete the matching
+messages from the SOW. If no filter or file is specified, the command
+reads messages from standard input (one per line) and sends those
+messages to AMPS for deletion.</p>
+<p>It can be useful to test a filter by first using the desired filter in a
+<code class="docutils literal"><span class="pre">sow</span></code> command and making sure the records returned match what is
+expected. If that is successful, then it is safe to use the filter for a
+<code class="docutils literal"><span class="pre">sow_delete</span></code>. Once records are deleted from the SOW, they are not
+recoverable.</p>
+<div class="section" id="common-options-sow-delete">
+<h4>Common Options - sow_delete<a class="headerlink" href="#common-options-sow-delete" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils" id="id10">
+<caption><span class="caption-text"><em>Spark sow_delete options</em></span><a class="headerlink" href="#id10" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Option</strong></th>
+<th class="head"><strong>Definition</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">server</span>
+</pre></div>
+</div>
+</td>
+<td>AMPS server to connect to.</td>
+</tr>
+<tr class="row-odd"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">topic</span>
+</pre></div>
+</div>
+</td>
+<td>Topic to delete records from.</td>
+</tr>
+<tr class="row-even"><td>filter</td>
+<td>Content filter to use. Notice that a filter of <code class="docutils literal"><span class="pre">1=1</span></code> is
+true for every message and will delete the entire set of
+records in the SOW.</td>
+</tr>
+<tr class="row-odd"><td>file</td>
+<td>File from which to read messages to be deleted.</td>
+</tr>
+<tr class="row-even"><td>proto</td>
+<td><p class="first">Protocol to use. In this release, <code class="docutils literal"><span class="pre">spark</span></code> supports
+<code class="docutils literal"><span class="pre">amps</span></code>, <code class="docutils literal"><span class="pre">fix</span></code>, <code class="docutils literal"><span class="pre">nvfix</span></code> and <code class="docutils literal"><span class="pre">xml</span></code>. Defaults to
+<code class="docutils literal"><span class="pre">amps</span></code>.</p>
+<p class="last"><code class="docutils literal"><span class="pre">spark</span></code> also supports <code class="docutils literal"><span class="pre">json</span></code> as a synonym for <code class="docutils literal"><span class="pre">amps</span></code>
+in this release.</p>
+</td>
+</tr>
+<tr class="row-odd"><td>type</td>
+<td>For protocols and transports that accept multiple message
+types on a given transport, this specifies the message type
+to use.</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="id5">
+<h4>Examples<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-bash" id="spark-sow-delete"><div class="highlight"><pre><span></span>%&gt; ./spark sow_delete -server localhost:9007 <span class="se">\</span>
+   -topic chaos -type json -filter <span class="s2">&quot;/name = &#39;cup&#39;&quot;</span>
+   Deleted <span class="m">1</span> records <span class="k">in</span> 10ms.
+</pre></div>
+</div>
+<p><em>Spark SOW delete example</em></p>
+<p>With the <code class="docutils literal"><span class="pre">spark</span></code> command in the example above, we are asking for AMPS
+to delete records in the topic <em>chaos</em> which match the filter
+<code class="docutils literal"><span class="pre">/name</span> <span class="pre">=</span> <span class="pre">'cup'</span></code>. In this example, we delete the record we published
+and queried previously in the <code class="docutils literal"><span class="pre">publish</span></code> and <code class="docutils literal"><span class="pre">sow_and_subscribe</span></code> examples.
+<code class="docutils literal"><span class="pre">spark</span></code> reports that one matching message was removed from the SOW topic.</p>
+</div>
+</div>
+<div class="section" id="ping">
+<h3>Ping<a class="headerlink" href="#ping" title="Permalink to this headline">¶</a></h3>
+<p id="index-6">The spark <code class="docutils literal"><span class="pre">ping</span></code> command is used to connect to the amps instance and
+attempt to logon. This tool is useful to determine if an AMPS instance
+is running and responsive.</p>
+<div class="section" id="common-options-spark-ping">
+<h4>Common Options - Spark Ping<a class="headerlink" href="#common-options-spark-ping" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils" id="id11">
+<caption><span class="caption-text"><em>Spark ping options</em></span><a class="headerlink" href="#id11" title="Permalink to this table">¶</a></caption>
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Option</strong></th>
+<th class="head"><strong>Definition</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><div class="code first last highlight-default"><div class="highlight"><pre><span></span><span class="n">server</span>
+</pre></div>
+</div>
+</td>
+<td>AMPS server to connect to.</td>
+</tr>
+<tr class="row-odd"><td>proto</td>
+<td><p class="first">Protocol to use. In this release, <code class="docutils literal"><span class="pre">spark</span></code> supports
+<code class="docutils literal"><span class="pre">amps</span></code>, <code class="docutils literal"><span class="pre">fix</span></code>, <code class="docutils literal"><span class="pre">nvfix</span></code> and <code class="docutils literal"><span class="pre">xml</span></code>. Defaults to
+<code class="docutils literal"><span class="pre">amps</span></code>.</p>
+<p class="last"><code class="docutils literal"><span class="pre">spark</span></code> also supports <code class="docutils literal"><span class="pre">json</span></code> as a synonym for <code class="docutils literal"><span class="pre">amps</span></code>
+in this release.</p>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="id6">
+<h4>Examples<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-bash" id="spark-ping"><div class="highlight"><pre><span></span>%&gt; ./spark ping -server localhost:9007 -type json
+Successfully connected to tcp://user@localhost:9007/amps/json
+</pre></div>
+</div>
+<p><em>Successful ping using Spark</em></p>
+<p>In the example above, <code class="docutils literal"><span class="pre">spark</span></code> was able to successfully log onto
+the AMPS instance that was located on port <code class="docutils literal"><span class="pre">9007</span></code>.</p>
+<div class="highlight-bash" id="spark-ping-error"><div class="highlight"><pre><span></span>%&gt; ./spark ping -server localhost:9119
+Unable to connect to AMPS
+<span class="o">(</span>com.crankuptheamps.client.exception.ConnectionRefusedException: Unable to
+connect to AMPS at localhost:9119<span class="o">)</span>.
+</pre></div>
+</div>
+<p><em>Unsuccessful ping using spark</em></p>
+<p>In the example above, <code class="docutils literal"><span class="pre">spark</span></code> was not able to successfully log onto
+the AMPS instance that was located on port <code class="docutils literal"><span class="pre">9119</span></code>. The error shows
+the exception thrown by <code class="docutils literal"><span class="pre">spark</span></code>, which in this case was a
+<code class="docutils literal"><span class="pre">ConnectionRefusedException</span></code> from Java.</p>
+</div>
+</div>
+</div>
+<div class="section" id="spark-authentication">
+<h2>Spark Authentication<a class="headerlink" href="#spark-authentication" title="Permalink to this headline">¶</a></h2>
+<p><code class="docutils literal"><span class="pre">spark</span></code> includes a way to provide credentials to AMPS for use with
+instances that are configured to require authentication. For example, to
+use a specific user ID and password to authenticate to AMPS, simply
+provide them in the URI in the format <code class="docutils literal"><span class="pre">user:password&#64;host:port</span></code>.</p>
+<p>The command below shows how to use spark to subscribe to a server,
+providing the specified username and password to AMPS.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></span><span class="nv">$AMPS_HOME</span>/bin/spark subscribe -type json <span class="se">\</span>
+                               -server username:password@localhost:9007
+</pre></div>
+</div>
+<p>AMPS also provides the ability to implement custom authentication, and
+many production deployments use customized authentication methods. To
+support this, the <code class="docutils literal"><span class="pre">spark</span></code> authentication scheme is customizable. By
+default, the authentication scheme used by <code class="docutils literal"><span class="pre">spark</span></code> simply provides the
+username and password from the <code class="docutils literal"><span class="pre">-server</span></code> parameter, as described
+above.</p>
+<p>Authentication schemes for <code class="docutils literal"><span class="pre">spark</span></code> are implemented in Java, as classes
+that implement <code class="docutils literal"><span class="pre">Authenticator</span></code> &#8211; the same method used by the AMPS
+Java client. To use a different authentication scheme with <code class="docutils literal"><span class="pre">spark</span></code>,
+you implement the <code class="docutils literal"><span class="pre">AuthenticatorFactory</span></code> interface in <code class="docutils literal"><span class="pre">spark</span></code> to
+return your custom authenticator, adjust the CLASSPATH to include the
+<code class="docutils literal"><span class="pre">.jar</span></code> file that contains the authenticator, and then provide the name
+of your <code class="docutils literal"><span class="pre">AuthenticatorFactory</span></code> on the command line. See the <em>AMPS Java
+Client</em> API documentation for details on implementing a custom
+<code class="docutils literal"><span class="pre">Authenticator</span></code>.</p>
+<p>The command below explicitly loads the default factory, found in the
+<code class="docutils literal"><span class="pre">spark</span></code> package, without adjusting the CLASSPATH.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span></span><span class="nv">$AMPS_HOME</span>/bin/spark subscribe –server username:password@localhost:9007 <span class="se">\</span>
+                               -type json -topic foo <span class="se">\</span>
+      -authenticator com.crankuptheamps.spark.DefaultAuthenticatorFactory
+</pre></div>
+</div>
+</div>
+</div>
+          </div>
+        </div>
+      </div>
+    <div class="clearer"></div>
+  </div>
+    <div class="footer">
+      &copy;2024 60East Technologies, Inc. (version 5.3.4).
+      |
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.5.3</a>
+      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
+    </div>
+  </body>
+</html>

amps-python-client 5.3.4.1__zip → 5.3.4.3__zip

amps-python-client 5.3.4.1zip → 5.3.4.3zip