jonathanvdc
/
modelverse
forked from yentl/modelverse


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267
							<!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>Interface description &#8212; Modelverse 0.4.0 documentation</title>
    
    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '0.4.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </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="top" title="Modelverse 0.4.0 documentation" href="index.html" />
    <link rel="next" title="Communication models" href="communication_models.html" />
    <link rel="prev" title="Internal workings" href="internal.html" /> 
  </head>
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="communication_models.html" title="Communication models"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="internal.html" title="Internal workings"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Modelverse 0.4.0 documentation</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="interface-description">
<h1>Interface description<a class="headerlink" href="#interface-description" title="Permalink to this headline">¶</a></h1>
<p>All Modelverse components communicate with each other through the use of sockets.
On these sockets, XML/HTTP Requests are used for communication.
In this brief section, we describe the form of these requests.</p>
<div class="section" id="mvs-server">
<h2>MvS server<a class="headerlink" href="#mvs-server" title="Permalink to this headline">¶</a></h2>
<p>The MvS server listens to a fixed set of commands.
All commands have a fully defined signature and result.
Note that commands are encoded: a decoding table is presented below.</p>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="85%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Code</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>CN</td>
<td>create_node</td>
</tr>
<tr class="row-odd"><td>CE</td>
<td>create_edge</td>
</tr>
<tr class="row-even"><td>CNV</td>
<td>create_nodevalue</td>
</tr>
<tr class="row-odd"><td>CD</td>
<td>create_dict</td>
</tr>
<tr class="row-even"><td>RV</td>
<td>read_value</td>
</tr>
<tr class="row-odd"><td>RO</td>
<td>read_outgoing</td>
</tr>
<tr class="row-even"><td>RI</td>
<td>read_incoming</td>
</tr>
<tr class="row-odd"><td>RE</td>
<td>read_edge</td>
</tr>
<tr class="row-even"><td>RD</td>
<td>read_dict</td>
</tr>
<tr class="row-odd"><td>RDN</td>
<td>read_dict_node</td>
</tr>
<tr class="row-even"><td>RDNE</td>
<td>read_dict_node_edge</td>
</tr>
<tr class="row-odd"><td>RDE</td>
<td>read_dict_edge</td>
</tr>
<tr class="row-even"><td>RRD</td>
<td>read_reverse_dict</td>
</tr>
<tr class="row-odd"><td>RR</td>
<td>read_root</td>
</tr>
<tr class="row-even"><td>RDK</td>
<td>read_dict_keys</td>
</tr>
<tr class="row-odd"><td>DE</td>
<td>delete_edge</td>
</tr>
<tr class="row-even"><td>DN</td>
<td>delete_node</td>
</tr>
</tbody>
</table>
<p>Requests are sent as POST requests (<em>i.e.</em>, in the data of a HTTP request).
They have the following form:</p>
<div class="highlight-default"><div class="highlight"><pre><span class="n">op</span><span class="o">=</span><span class="n">CODE</span><span class="o">&amp;</span><span class="n">params</span><span class="o">=</span><span class="n">PARAMS</span>
</pre></div>
</div>
<p>In this case, <em>CODE</em> is one of the codes mentioned above, and the value of <em>PARAMS</em> is a JSON encoded list of Modelverse identifiers.
The choice of what is a Modelverse identifier is left to the MvS itself.</p>
<p>The result will be a JSON serialized list containing as first element the response to the request, and as second element the statuscode.
If the statuscode is 200, the first element will be correct.
Otherwise, the statuscode indicates the error, and the first element is set to <em>null</em>.</p>
</div>
<div class="section" id="mvk-server">
<h2>MvK server<a class="headerlink" href="#mvk-server" title="Permalink to this headline">¶</a></h2>
<p>The communication with the MvK is a lot easier, as there is only a very minimal interface: the actual interface needs to be explicitly modelled in action language.
Requests have the following form:</p>
<div class="highlight-default"><div class="highlight"><pre><span class="n">op</span><span class="o">=</span><span class="n">OPERATION</span><span class="o">&amp;</span><span class="n">username</span><span class="o">=</span><span class="n">USERNAME</span><span class="o">&amp;</span><span class="n">value</span><span class="o">=</span><span class="n">VALUE</span>
</pre></div>
</div>
<p>Here, <em>OPERATION</em> defines the operation to execute, of which only two exist:</p>
<ol class="arabic simple">
<li><em>set_input</em>, which adds the sent value to the input queue of the user;</li>
<li><em>get_output</em>, which blocks until there is a value in the output queue of the user.</li>
</ol>
<p>Obviously, <em>USERNAME</em> specifies the name of the user for which the operation needs to happen.</p>
<p>The <em>VALUE</em> is just a JSON encoded value which will be added to the input queue of the Modelverse.
This is ignored when the <em>get_output</em> operation is used.
Note that there are some minor differences between our encoding and JSON encoding.</p>
<p>The supported types are shown below.</p>
<table border="1" class="docutils">
<colgroup>
<col width="27%" />
<col width="73%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Type</th>
<th class="head">Example</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>Integer</td>
<td>1</td>
</tr>
<tr class="row-odd"><td>Float</td>
<td>1.0</td>
</tr>
<tr class="row-even"><td>Boolean</td>
<td>true</td>
</tr>
<tr class="row-odd"><td>String</td>
<td>&#8220;abc&#8221;</td>
</tr>
<tr class="row-even"><td>Action</td>
<td>if</td>
</tr>
</tbody>
</table>
<p>While this list mostly resembles JSON, there are some important differences:</p>
<ul class="simple">
<li>Lists and objects are not supported;</li>
<li>Null object is not supported;</li>
<li>Action type is new, and contains a string representation (without quotes!) of the action language construct to add</li>
</ul>
<p>As response, the <em>set_input</em> will always receive the same reply if the message was correctly deserialized.
Receiving a reply does <em>NOT</em> mean that a message was consumed by the user, it only means that the message was correctly added to the input queue of that user.</p>
<p>A <em>get_output</em> request blocks until a value is available in the users output queue.
The reply to this message will then contain a JSON serialized (with identical remarks as for <em>set_input</em>) containing the value that was output.
Note that now the <em>null</em> message is possible, in case the node that is being outputted does not contain a value (or is an edge).</p>
<div class="section" id="performance-notes">
<h3>Performance notes<a class="headerlink" href="#performance-notes" title="Permalink to this headline">¶</a></h3>
<p>For performance reasons, sending a huge amount of data to the Modelverse (<em>e.g.</em>, a compiled program), should not happen with individual requests for each line.
To allow for packed messages, users can ignore the <em>value</em> parameter, and use the <em>data</em> parameter instead.
The content of this parameter should be a JSON encoded list of all individual values to be inserted.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Interface description</a><ul>
<li><a class="reference internal" href="#mvs-server">MvS server</a></li>
<li><a class="reference internal" href="#mvk-server">MvK server</a><ul>
<li><a class="reference internal" href="#performance-notes">Performance notes</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="internal.html"
                        title="previous chapter">Internal workings</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="communication_models.html"
                        title="next chapter">Communication models</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/interface.txt"
            rel="nofollow">Show Source</a></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="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="communication_models.html" title="Communication models"
             >next</a> |</li>
        <li class="right" >
          <a href="internal.html" title="Internal workings"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Modelverse 0.4.0 documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2016, Yentl Van Tendeloo.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.6.
    </div>
  </body>
</html>