summaryrefslogtreecommitdiffstatsabout
diff options
context:
space:
mode:
authorChristophe Augier2012-07-22 16:18:39 (EDT)
committer Eugene Tarassov2012-07-25 01:13:55 (EDT)
commit3d64302225781ad126d9b6a75273009bb6846ac7 (patch)
tree419a106b768a45afe5871f515b4069198e5a2dc7
parentb089ed580637f6a807206411ba25d86d3d1d91ae (diff)
downloadorg.eclipse.tcf-3d64302225781ad126d9b6a75273009bb6846ac7.zip
org.eclipse.tcf-3d64302225781ad126d9b6a75273009bb6846ac7.tar.gz
org.eclipse.tcf-3d64302225781ad126d9b6a75273009bb6846ac7.tar.bz2
Documentation: add Path Map service specification
-rw-r--r--docs/TCF Service - Path Map.html285
1 files changed, 285 insertions, 0 deletions
diff --git a/docs/TCF Service - Path Map.html b/docs/TCF Service - Path Map.html
new file mode 100644
index 0000000..6338eba
--- /dev/null
+++ b/docs/TCF Service - Path Map.html
@@ -0,0 +1,285 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Target Communication Framework Services - PathMap</title>
+</head>
+
+<body lang='EN-US'>
+
+<h1>Target Communication Framework Services - PathMap</h1>
+
+<ul>
+ <li><a href='#VersionHistory'>Version History</a>
+ <li><a href='#Overview'>Overview</a>
+ <li><a href='#Cmds'>Commands</a>
+ <ul>
+ <li><a href='#CmdGet'>Get</a>
+ <li><a href='#CmdSet'>Set</a>
+ </ul>
+ <li><a href='#Events'>Events</a>
+ <li><a href='#API'>API</a>
+</ul>
+
+<h1>Memory Service</h1>
+
+<h2><a name='VersionHistory'>Version History</a></h2>
+
+<table border=1 cellpadding=8>
+ <tr>
+ <th>Version
+ <th>Date
+ <th>Change
+ <tr>
+ <td>0.0
+ <td>2012-07-22
+ <td>Initial documentation based on source code
+</table>
+
+<h2><a name='Overview'>Overview</a></h2>
+
+<p>The service manages file path translation across systems. Command and event
+parameters are encoded as zero terminated <a
+href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+
+<p>The service uses standard format for error reports,
+see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+
+<h2><a name='Cmds'>Commands</a></h2>
+
+<h3><a name='CmdGet'>Get</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C &bull; <i>&lt;token&gt;</i> &bull; PathMap &bull; get &bull;
+</font></b></pre>
+
+<p>The command retrieves file path mapping rules.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull; <i>&lt;array of path map rules&gt;</i> &bull;
+
+<i>&lt;array of path map rules&gt;</i>
+ &rArr; null
+ &rArr; [ <i>&lt;path map rules list&gt;</i> ]
+
+<i>&lt;path map rules list&gt;</i>
+ &rArr; <i>&lt;object: path map rule&gt;</i>
+ &rArr; <i>&lt;path map rules list&gt;</i> , <i>&lt;object: path map rule&gt;</i>
+</font></b></pre>
+
+<p>Predefined path map rule properties are:</p>
+<ul>
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b></code>
+ - ID of the rule.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Source" : <i>&lt;string&gt;</i></font></b></code>
+ - source or compile time file path.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Destination" : <i>&lt;string&gt;</i></font></b></code>
+ - destination or run-time file path.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Context" : <i>&lt;string&gt;</i></font></b></code>
+ - symbols context group ID or name, deprecated - use ContextQuery.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ContextQuery" : <i>&lt;string&gt;</i></font></b></code>
+ - context query.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Host" : <i>&lt;string&gt;</i></font></b></code>
+ - host.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Protocol" : <i>&lt;string&gt;</i></font></b></code>
+ - file access protocol, see predefined protocol values.
+
+ <p>Predefined protocol values are:</p>
+ <ul>
+ <li><code><b><font face="Courier New" size=2 color=#333399>"file"</font></b></code>
+ - Regular file access using system calls.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"host"</font></b></code>
+ - File should be accessed using File System service on host.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"target"</font></b></code>
+ - File should be accessed using File System service on target.
+ </ul>
+</ul>
+
+<h3><a name='CmdSet'>Set</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C &bull; <i>&lt;token&gt;</i> &bull; PathMap &bull; set &bull; [ <i>&lt;path map rules list&gt;</i> ] &bull;
+
+<i>&lt;path map rules list&gt;</i>
+ &rArr; <i>&lt;object: path map rule&gt;</i>
+ &rArr; <i>&lt;path map rules list&gt;</i> , <i>&lt;object: path map rule&gt;</i>
+</font></b></pre>
+
+<p>The command set file path mapping rules.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull;
+</font></b></pre>
+
+<h2><a name='Events'>Events</a></h2>
+
+<p>PathMap service broadcasts notification events when path mappings are changed.</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+E &bull; PathMap &bull; changed &bull;
+</font></b></pre>
+
+<h2><a name='API'>API</a></h2>
+
+<pre>
+<font color=#3F5FBF>/**
+ * IPathMap service manages file path translation across systems.
+ */</font>
+<font color=#7F0055>public interface</font> IPathMap extends IService {
+
+ <font color=#7F0055>static final</font> String NAME = "PathMap";
+
+ <font color=#3F5FBF>/**
+ * Path mapping rule property names.
+ */</font>
+ <font color=#7F0055>static final</font> String
+ PROP_ID = "ID", <font color=#3F5FBF>/** String, rule ID */</font>
+ PROP_SOURCE = "Source", <font color=#3F5FBF>/** String, source, or compile-time file path */</font>
+ PROP_DESTINATION = "Destination", <font color=#3F5FBF>/** String, destination, or run-time file path */</font>
+ PROP_CONTEXT = "Context", <font color=#3F5FBF>/** String, symbols context group ID or name, deprecated - use ContextQuery */</font>
+ PROP_CONTEXT_QUERY = "ContextQuery", <font color=#3F5FBF>/** String, contexts query, see IContextQuery */</font>
+ PROP_HOST = "Host", <font color=#3F5FBF>/** String, */</font>
+ PROP_PROTOCOL = "Protocol"; <font color=#3F5FBF>/** String, file access protocol, see PROTOCOL_*, default is regular file */</font>
+
+ <font color=#3F5FBF>/**
+ * PROP_PROTOCOL values.
+ */</font>
+ <font color=#7F0055>static final</font> String
+ PROTOCOL_FILE = "file", <font color=#3F5FBF>/** Regular file access using system calls */</font>
+ PROTOCOL_HOST = "host", <font color=#3F5FBF>/** File should be accessed using File System service on host */</font>
+ PROTOCOL_TARGET = "target"; <font color=#3F5FBF>/** File should be accessed using File System service on target */</font>
+
+ <font color=#3F5FBF>/**
+ * PathMapRule interface represents a single file path mapping rule.
+ */</font>
+ <font color=#7F0055>interface</font> PathMapRule {
+
+ <font color=#3F5FBF>/**
+ * Get rule properties. See PROP_* definitions for property names.
+ * Properties are read only, clients should not try to modify them.
+ * @return Map of rule properties.
+ */</font>
+ Map<String,Object> getProperties();
+
+ <font color=#3F5FBF>/**
+ * Get rule unique ID.
+ * Same as getProperties().get(PROP_ID)
+ * @return rule ID.
+ */</font>
+ String getID();
+
+ <font color=#3F5FBF>/**
+ * Get compile-time file path.
+ * Same as getProperties().get(PROP_SOURCE)
+ * @return compile-time file path.
+ */</font>
+ String getSource();
+
+ <font color=#3F5FBF>/**
+ * Get run-time file path.
+ * Same as getProperties().get(PROP_DESTINATION)
+ * @return run-time file path.
+ */</font>
+ String getDestination();
+
+ <font color=#3F5FBF>/**
+ * Get host name of this rule.
+ * Same as getProperties().get(PROP_HOST)
+ * @return host name.
+ */</font>
+ String getHost();
+
+ <font color=#3F5FBF>/**
+ * Get file access protocol name.
+ * Same as getProperties().get(PROP_PROTOCOL)
+ * @return protocol name.
+ */</font>
+ String getProtocol();
+
+ <font color=#3F5FBF>/**
+ * Get context query that defines scope of the mapping rule, see also IContextQuery.
+ * Same as getProperties().get(PROP_CONTEXT_QUERY)
+ * @return context query expression, or null.
+ */</font>
+ String getContextQuery();
+ }
+
+ <font color=#3F5FBF>/**
+ * Retrieve file path mapping rules.
+ *
+ * <font color=#7F9FBF>@param</font> done &ndash; call back interface called when operation is completed.
+ * @return &ndash; pending command handle.
+ */</font>
+ IToken get(DoneGet done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for get().
+ */</font>
+ <font color=#7F0055>interface</font> DoneGet {
+ <font color=#3F5FBF>/**
+ * Called when file path mapping retrieval is done.
+ * <font color=#7F9FBF>@param</font> error &ndash; error description if operation failed, null if succeeded.
+ * <font color=#7F9FBF>@param</font> map &ndash; file path mapping data.
+ */</font>
+ <font color=#7F0055>void</font> doneGet(IToken token, Exception error, PathMapRule[] map);
+ }
+
+ <font color=#3F5FBF>/**
+ * Set file path mapping rules.
+ *
+ * <font color=#7F9FBF>@param</font> map &ndash; file path mapping rules.
+ * <font color=#7F9FBF>@param</font> done &ndash; call back interface called when operation is completed.
+ * @return &ndash; pending command handle.
+ */</font>
+ IToken set(PathMapRule[] map, DoneSet done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for set().
+ */</font>
+ <font color=#7F0055>interface</font> DoneSet {
+ <font color=#3F5FBF>/**
+ * Called when file path mapping transmission is done.
+ * <font color=#7F9FBF>@param</font> error &ndash; error description if operation failed, null if succeeded.
+ * <font color=#7F9FBF>@param</font> map &ndash; memory map data.
+ */</font>
+ <font color=#7F0055>void</font> doneSet(IToken token, Exception error);
+ }
+
+ <font color=#3F5FBF>/**
+ * Add path map event listener.
+ * <font color=#7F9FBF>@param</font> listener &ndash; path map event listener to add.
+ */</font>
+ <font color=#7F0055>void</font> addListener(PathMapListener listener);
+
+ <font color=#3F5FBF>/**
+ * Remove path map event listener.
+ * <font color=#7F9FBF>@param</font> listener &ndash; path map event listener to remove.
+ */</font>
+ <font color=#7F0055>void</font> removeListener(PathMapListener listener);
+
+ <font color=#3F5FBF>/**
+ * Service events listener interface.
+ */</font>
+ <font color=#7F0055>interface</font> PathMapListener {
+
+ <font color=#3F5FBF>/**
+ * Called when path map changes.
+ */</font>
+ <font color=#7F0055>void</font> changed();
+ }
+}
+</pre>
+
+</body>
+</html>