knight/datahub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
datahub/docs/backend/base.html

189 lines
12 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>base.js</title>
<link rel="stylesheet" href="pycco.css">
</head>
<body>
<div id='container'>
<div id="background"></div>
<div class='section'>
<div class='docs'><h1>base.js</h1></div>
</div>
<div class='clearall'>
<div class='section' id='section-0'>
<div class='docs'>
<div class='octowrap'>
<a class='octothorpe' href='#section-0'>#</a>
</div>
<h1>Recline Backends</h1>
<p>Backends are connectors to backend data sources and stores</p>
<p>This is just the base module containing a template Base class and convenience methods.</p>
</div>
<div class='code'>
<div class="highlight"><pre><span class="k">this</span><span class="p">.</span><span class="nx">recline</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">recline</span> <span class="o">||</span> <span class="p">{};</span>
<span class="k">this</span><span class="p">.</span><span class="nx">recline</span><span class="p">.</span><span class="nx">Backend</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">recline</span><span class="p">.</span><span class="nx">Backend</span> <span class="o">||</span> <span class="p">{};</span>
<span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">$</span><span class="p">,</span> <span class="nx">my</span><span class="p">)</span> <span class="p">{</span></pre></div>
</div>
</div>
<div class='clearall'></div>
<div class='section' id='section-1'>
<div class='docs'>
<div class='octowrap'>
<a class='octothorpe' href='#section-1'>#</a>
</div>
<h2>Backbone.sync</h2>
<p>Override Backbone.sync to hand off to sync function in relevant backend</p>
</div>
<div class='code'>
<div class="highlight"><pre> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">sync</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">method</span><span class="p">,</span> <span class="nx">model</span><span class="p">,</span> <span class="nx">options</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="nx">model</span><span class="p">.</span><span class="nx">backend</span><span class="p">.</span><span class="nx">sync</span><span class="p">(</span><span class="nx">method</span><span class="p">,</span> <span class="nx">model</span><span class="p">,</span> <span class="nx">options</span><span class="p">);</span>
<span class="p">};</span></pre></div>
</div>
</div>
<div class='clearall'></div>
<div class='section' id='section-2'>
<div class='docs'>
<div class='octowrap'>
<a class='octothorpe' href='#section-2'>#</a>
</div>
<h2>recline.Backend.Base</h2>
<p>Base class for backends providing a template and convenience functions.
You do not have to inherit from this class but even when not it does provide guidance on the functions you must implement.</p>
<p>Note also that while this (and other Backends) are implemented as Backbone models this is just a convenience.</p>
</div>
<div class='code'>
<div class="highlight"><pre> <span class="nx">my</span><span class="p">.</span><span class="nx">Base</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Model</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span></pre></div>
</div>
</div>
<div class='clearall'></div>
<div class='section' id='section-3'>
<div class='docs'>
<div class='octowrap'>
<a class='octothorpe' href='#section-3'>#</a>
</div>
<h3>sync</h3>
<p>An implementation of Backbone.sync that will be used to override
Backbone.sync on operations for Datasets and Documents which are using this backend.</p>
<p>For read-only implementations you will need only to implement read method
for Dataset models (and even this can be a null operation). The read method
should return relevant metadata for the Dataset. We do not require read support
for Documents because they are loaded in bulk by the query method.</p>
<p>For backends supporting write operations you must implement update and delete support for Document objects.</p>
<p>All code paths should return an object conforming to the jquery promise API.</p>
</div>
<div class='code'>
<div class="highlight"><pre> <span class="nx">sync</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">method</span><span class="p">,</span> <span class="nx">model</span><span class="p">,</span> <span class="nx">options</span><span class="p">)</span> <span class="p">{</span>
<span class="p">},</span></pre></div>
</div>
</div>
<div class='clearall'></div>
<div class='section' id='section-4'>
<div class='docs'>
<div class='octowrap'>
<a class='octothorpe' href='#section-4'>#</a>
</div>
<h3>query</h3>
<p>Query the backend for documents returning them in bulk. This method will
be used by the Dataset.query method to search the backend for documents,
retrieving the results in bulk.</p>
<p>@param {recline.model.Dataset} model: Dataset model.</p>
<p>@param {Object} queryObj: object describing a query (usually produced by
using recline.Model.Query and calling toJSON on it).</p>
<p>The structure of data in the Query object or
Hash should follow that defined in <a
href="http://github.com/okfn/recline/issues/34">issue 34</a>.
(Of course, if you are writing your own backend, and hence
have control over the interpretation of the query object, you
can use whatever structure you like).</p>
<p>@returns {Promise} promise API object. The promise resolve method will
be called on query completion with a QueryResult object.</p>
<p>A QueryResult has the following structure (modelled closely on
ElasticSearch - see <a
href="https://github.com/okfn/recline/issues/57">this issue for more
details</a>):</p>
<pre>
{
total: // (required) total number of results (can be null)
hits: [ // (required) one entry for each result document
{
_score: // (optional) match score for document
_type: // (optional) document type
_source: // (required) document/row object
}
],
facets: { // (optional)
// facet results (as per <http://www.elasticsearch.org/guide/reference/api/search/facets/>)
}
}
</pre>
</div>
<div class='code'>
<div class="highlight"><pre> <span class="nx">query</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">model</span><span class="p">,</span> <span class="nx">queryObj</span><span class="p">)</span> <span class="p">{</span>
<span class="p">},</span></pre></div>
</div>
</div>
<div class='clearall'></div>
<div class='section' id='section-5'>
<div class='docs'>
<div class='octowrap'>
<a class='octothorpe' href='#section-5'>#</a>
</div>
<p>convenience method to convert simple set of documents / rows to a QueryResult</p>
</div>
<div class='code'>
<div class="highlight"><pre> <span class="nx">_docsToQueryResult</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">rows</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">hits</span> <span class="o">=</span> <span class="nx">_</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">rows</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">row</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="p">{</span> <span class="nx">_source</span><span class="o">:</span> <span class="nx">row</span> <span class="p">};</span>
<span class="p">});</span>
<span class="k">return</span> <span class="p">{</span>
<span class="nx">total</span><span class="o">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nx">hits</span><span class="o">:</span> <span class="nx">hits</span>
<span class="p">};</span>
<span class="p">},</span></pre></div>
</div>
</div>
<div class='clearall'></div>
<div class='section' id='section-6'>
<div class='docs'>
<div class='octowrap'>
<a class='octothorpe' href='#section-6'>#</a>
</div>
<h2>_wrapInTimeout</h2>
<p>Convenience method providing a crude way to catch backend errors on JSONP calls.
Many of backends use JSONP and so will not get error messages and this is
a crude way to catch those errors.</p>
</div>
<div class='code'>
<div class="highlight"><pre> <span class="nx">_wrapInTimeout</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">ourFunction</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">dfd</span> <span class="o">=</span> <span class="nx">$</span><span class="p">.</span><span class="nx">Deferred</span><span class="p">();</span>
<span class="kd">var</span> <span class="nx">timeout</span> <span class="o">=</span> <span class="mi">5000</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">timer</span> <span class="o">=</span> <span class="nx">setTimeout</span><span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">dfd</span><span class="p">.</span><span class="nx">reject</span><span class="p">({</span>
<span class="nx">message</span><span class="o">:</span> <span class="s1">&#39;Request Error: Backend did not respond after &#39;</span> <span class="o">+</span> <span class="p">(</span><span class="nx">timeout</span> <span class="o">/</span> <span class="mi">1000</span><span class="p">)</span> <span class="o">+</span> <span class="s1">&#39; seconds&#39;</span>
<span class="p">});</span>
<span class="p">},</span> <span class="nx">timeout</span><span class="p">);</span>
<span class="nx">ourFunction</span><span class="p">.</span><span class="nx">done</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">arguments</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">clearTimeout</span><span class="p">(</span><span class="nx">timer</span><span class="p">);</span>
<span class="nx">dfd</span><span class="p">.</span><span class="nx">resolve</span><span class="p">(</span><span class="nx">arguments</span><span class="p">);</span>
<span class="p">})</span>
<span class="p">.</span><span class="nx">fail</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">arguments</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">clearTimeout</span><span class="p">(</span><span class="nx">timer</span><span class="p">);</span>
<span class="nx">dfd</span><span class="p">.</span><span class="nx">reject</span><span class="p">(</span><span class="nx">arguments</span><span class="p">);</span>
<span class="p">})</span>
<span class="p">;</span>
<span class="k">return</span> <span class="nx">dfd</span><span class="p">.</span><span class="nx">promise</span><span class="p">();</span>
<span class="p">}</span>
<span class="p">});</span>
<span class="p">}(</span><span class="nx">jQuery</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">recline</span><span class="p">.</span><span class="nx">Backend</span><span class="p">));</span>
</pre></div>
</div>
</div>
<div class='clearall'></div>
</div>
</body>
Reference in New Issue View Git Blame Copy Permalink