[MOBY-guts] biomoby commit
Martin Senger
senger at pub.open-bio.org
Mon Aug 29 13:21:59 UTC 2005
senger
Mon Aug 29 09:21:59 EDT 2005
Update of /home/repository/moby/moby-live/Java/docs
In directory pub.open-bio.org:/tmp/cvs-serv13506/docs
Modified Files:
ChangeLog Moses-generators.html Moses-parser.html Moses.html
Added Files:
Moses-clients.html
Log Message:
moby-live/Java/docs Moses-clients.html,NONE,1.1 ChangeLog,1.36,1.37 Moses-generators.html,1.2,1.3 Moses-parser.html,1.1,1.2 Moses.html,1.4,1.5
===================================================================
RCS file: /home/repository/moby/moby-live/Java/docs/ChangeLog,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -r1.36 -r1.37
--- /home/repository/moby/moby-live/Java/docs/ChangeLog 2005/08/26 06:27:02 1.36
+++ /home/repository/moby/moby-live/Java/docs/ChangeLog 2005/08/29 13:21:59 1.37
@@ -1,3 +1,7 @@
+2005-08-29 Martin Senger <martin.senger at gmail.com>
+
+ * Added project Moses for generating code for service providers.
+
2005-08-25 Martin Senger <martin.senger at gmail.com>
* Clean-up build.xml generally, added there new targets for
===================================================================
RCS file: /home/repository/moby/moby-live/Java/docs/Moses-generators.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- /home/repository/moby/moby-live/Java/docs/Moses-generators.html 2005/08/28 10:43:27 1.2
+++ /home/repository/moby/moby-live/Java/docs/Moses-generators.html 2005/08/29 13:21:59 1.3
@@ -673,13 +673,107 @@
but here are few basic rules that can make your investigation more
efficient: <p>
-... (pending)...
+There are always two ways to get/set data. You can use methods of a
+general object <tt><a
+href="API/org/biomoby/shared/parser/MobyJob.html">MobyJob</a></tt>, or
+you can use methods from generated sketeltons. <p>
+
+The methods in <tt>MobyJob</tt> either get data by name (meaning by an
+article name, and only if it does not exist the data type name is
+used), or they get data from the first Simple Biomoby type - which
+often is the only one. For example:
+
+<blockquote>
+<pre class=code>
+public void processIt (MobyJob request,
+ MobyJob response,
+ MobyPackage outputContext)
+ throws MobyException {
+
+ // get the first Simple data
+ System.out.println (request.getData());
+
+ // get the Simple data that have article name "Sequence"
+ System.out.println (request.getData ("Sequence"));
+
+ // get the Simple data that have an article name "abc" or none at all,
+ // AND it is of the type "Regex"
+ System.out.println (request.getData ("abc", "Regex"));
+
+ // get the first Simple that matches the data type "Regex"
+ System.out.println (request.getData ("", "Regex"));
+
+ // get the first Collection
+ System.out.println (printCol (response.getDataSet()));
+
+ // get the Collection data that have article name "Sequences"
+ System.out.println (printCol (response.getDataSet ("Sequences")));
+
+ // get the Collection data that have an article name "abc" or none at all,
+ // AND its elements are of the type "Regex"
+ System.out.println (printCol (response.getDataSet ("abc", "Regex")));
+
+ // get the first Collection whose elements match the data type "Regex"
+ System.out.println (printCol (response.getDataSet ("", "Regex")));
+}
+
+private String printCol (MobyObject[] col) {
+ if (col == null) return "null";
+ if (col.length == 0) return "empty";
+ return col[0].toString();
+}
+</pre>
+</blockquote>
+
+The <tt>MobyJob</tt>'s <tt>getMethod(article-name,
+data-type-name)</tt> has the following built-in behaviour:
+
+<ol>
+ <li class=tiny> Try to find a Simple element matching both the
+article name and a data type name.
+ <li class=tiny> If it fails, try to find an unnamed Simple data
+element matching just the data type.
+ <li class=tiny> If it fails, and if here given article name is
+empty, try to find any Simple data element matching the data type.
+<li class=tiny> Return <tt>null</tt>.
+</ol>
+<p>
+
+The generated skeletons allows to work directly with the generated
+data types. They have methids that have already in their names
+corresponding article names and data types names. For example:
+
+<blockquote>
+<pre class=code>
+public void processIt (MobyJob request,
+ MobyJob response,
+ MobyPackage outputContext)
+ throws MobyException {
+ Regex input = get_language (request);
+ if (input == null) return;
+
+ simple_key_value_pair[] output = doBusiness (input);
+ set_helloSet (response, output) ;
+}
+</pre>
+</blockquote>
+
+Note that in the example above the <em>language</em> is an article
+name of a Biomoby Simple, <em>Regex</em> is its data type, Also the
+<em>simple_key_value_pair</em> is a data type name. The <em>hello</em>
+is an article name of an output collection. <p>
+
+The full examples of some Bimoby services are in jMoby in
+<tt>src/samples</tt> directory. <p>
+
+
+
<hr>
<div align=right class="address">
<address><A HREF="mailto:martin.senger at gmail.com">Martin Senger</A><BR></address>
<!-- hhmts start -->
-Last modified: Sun Aug 28 19:17:38 2005
+Last modified: Mon Aug 29 11:52:14 2005
<!-- hhmts end -->
</div>
===================================================================
RCS file: /home/repository/moby/moby-live/Java/docs/Moses-parser.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- /home/repository/moby/moby-live/Java/docs/Moses-parser.html 2005/08/28 10:19:08 1.1
+++ /home/repository/moby/moby-live/Java/docs/Moses-parser.html 2005/08/29 13:21:59 1.2
@@ -11,14 +11,219 @@
</center>
-Documentation is in progress... <img src="images/arbeiter.gif" border=0/> <p>
+The Biomoby XML parser has an obvious task: to read a Biomoby XML
+stream and convert it into Java objects that can be easily
+handled. Its job is usually hidden, a Biomoby service developer rarely
+calls the parser directly. But here is an example how to get parsed
+Biomoby XML data into a <tt>MobyPackage</tt> (note that the input XML
+- the parameter <tt>data</tt> in the example - can be given as a
+String, byte[], or a File which conveniently corresponds with the
+requirement from the Biomoby API):
+
+<blockquote>
+<pre class=code>
+try {
+ MobyPackage mobyInput = MobyPackage.createFromXML (data);
+
+ // here do something with 'mobyInput'
+
+} catch (MobyException e) {
+ System.out.println (e.getMessage());
+}
+</pre>
+</blockquote>
+
+To bring data back into XML is again simple:
+
+<blockquote>
+<pre class=code>
+try {
+ // fill response data into a mobyOutput...
+ MobyPackage mobyOutput = new MobyPackage();
+ ...
+
+ // and convert it into XML
+ String xml = mobyOutput.toXML();
+
+} catch (MobyException e) {
+ System.out.println (e.getMessage());
+}
+</pre>
+</blockquote>
+
+On the other hand, what <em>is</em> visible to the service developers,
+and what they are working with often, are the Java objects created by
+the parser. This is a high-level overview of them, and how they
+correspond to the Biomoby XML tags:
+<p>
+
+<blockquote>
+<table cellpadding=5 border=1>
+
+<tr><th class=options>Biomoby XML tag</th> <th class=options>Java object</th></tr>
+
+<tr><td class=options>MOBY, mobyContent</td><td class=options>
+<tt><a href="API/org/biomoby/shared/parser/MobyPackage.html">org.biomoby.shared.parser.MobyPackage</a></tt>
+</td></tr>
+<tr><td class=options>mobyData</td><td class=options>
+<tt><a href="API/org/biomoby/shared/parser/MobyJob.html">org.biomoby.shared.parser.MobyJob</a></tt>
+</td></tr>
+<tr><td class=options>Simple</td><td class=options>
+<tt><a href="API/org/biomoby/shared/parser/MobySimple.html">org.biomoby.shared.parser.MobySimple</a></tt>
+</td></tr>
+<tr><td class=options>Collection</td><td class=options>
+<tt><a href="API/org/biomoby/shared/parser/MobyCollection.html">org.biomoby.shared.parser.MobyCollection</a></tt>
+</td></tr>
+<tr><td class=options>Parameter</td><td class=options>
+<tt><a href="API/org/biomoby/shared/parser/MobyParameter.html">org.biomoby.shared.parser.MobyParameter</a></tt>
+</td></tr>
+
+<tr><td class=options>Object and its children</td><td class=options>
+<tt>
+<a href="API/org/biomoby/shared/datatypes/MobyObject.html">org.biomoby.shared.datatypes.MobyObject</a><br>
+<a href="API/org/biomoby/shared/datatypes/MobyString.html">org.biomoby.shared.datatypes.MobyString</a><br>
+<a href="API/org/biomoby/shared/datatypes/MobyInteger.html">org.biomoby.shared.datatypes.MobyInteger</a><br>
+<a href="API/org/biomoby/shared/datatypes/MobyFloat.html">org.biomoby.shared.datatypes.MobyFloat</a><br>
+<a href="API/org/biomoby/shared/datatypes/MobyBoolean.html">org.biomoby.shared.datatypes.MobyBoolean</a><br>
+<a href="API/org/biomoby/shared/datatypes/MobyDateTime.html">org.biomoby.shared.datatypes.MobyDateTime</a><br>
+</tt>and all generated data types in <tt>org.biomoby.shared.datatypes.*</tt>
+</td></tr>
+
+<tr><td class=options>CrossReference</td><td class=options>
+<tt><a href="API/org/biomoby/shared/datatypes/MobyXref.html">org.biomoby.shared.datatypes.MobyXref</a></tt>
+</td></tr>
+<tr><td class=options>ProvisionInformation</td><td class=options>
+<tt><a href="API/org/biomoby/shared/data/MobyProvisionInfo.html">org.biomoby.shared.data.MobyProvisionInfo</a></tt>
+</td></tr>
+
+</table>
+</blockquote>
+
+A <tt>MobyPackage</tt> contains one or more <tt>MobyJob</tt>s each of
+them containing one "execution" (or a "query" in a Biomoby
+speak). Note that a Biomoby service must be able to accept more
+invocations (jobs, queries) from one network request. A
+<tt>MobyJob</tt> also carries a response from a service. <p>
+
+A <tt>MobyJob</tt> has the data themselves - they are either stored in
+<tt>MobySimple</tt>s or in <tt>MobyCollection</tt>s. The number and
+types of these <tt>MobyDataElement</tt>s are defined for each Biomoby
+service in a Biomoby registry. <p>
+
+The <tt>MobySimple</tt>s have data stored in various data objects -
+their classes are in the package
+<tt>org.biomoby.shared.datatypes</tt>. The primitive data types are
+there available directly, the other types are to be generated - see
+details in a <a href="Moses-generators.html">separate
+document</a>. <p>
+
+Here is a picture showing how the entities are relates: <p>
+
+<blockquote>
+<img src="images/data-containers.png" border=0/> <p>
+</blockquote>
+<p>
+
+
+
+
+<a name="howtoparser"></a>
+<h3>Command-line client for the parser</h3>
+
+As said above, a developer rarely needs to invoke the parser
+directly. But because the life is not perfect (yet, but with Biomoby
+growing it will be, of course), there are moments when we need to test
+either parser itself or check some XML data the users are claiming
+that they do not work for them. For these moments, there is a
+command-line client <tt>TestingMobyParser</tt>. <p>
-For the time being, look directly in the <a
-href="http://biomoby.org/moby-live/Java/docs/API/org/biomoby/shared/parser/package-summary.html">API
-documentation</a>.
+The program can be invoked using a script:
-</ul>
+<blockquote>
+<pre class=script>
+build/run/run-moby-parser [<options>] <filename>
+</pre>
+</blockquote>
+
+At the moment, there is no Ant's target to invoke this program. <p>
+
+The program takes the following options, specific for generating data
+types: <p>
+
+<blockquote>
+<table cellpadding=5 border=1>
+<tr class=options><th>Option/Parameter</th> <th>Ant's property</th> <th>Meaning</th></tr>
+
+<tr class=options><td valign="top"><tt><<em>filename</em>></tt></td>
+<td valign="top"><tt> </tt></td>
+
+<td>XML file to be parsed (a mandatory parameter)</td> </tr>
+
+<tr class=options><td valign="top"><tt>-n</tt></td>
+<td valign="top"><tt> </tt></td>
+<td>it does not print the parsed result (by default it does)</td>
+</tr>
+
+<tr class=options><td valign="top"><tt>-r</tt></td>
+<td valign="top"><tt> </tt></td>
+
+<td>convert back (reverse) the parsed result into XML and print it</td> </tr>
+
+</table>
+</blockquote>
+<p>
+The reverse converting (with the <tt>-r</tt> option) has an interesting
+usage. The resulting XML is not usually identical with the original -
+it may have different formatting, it probably has more XML namespace
+prefixes (they are everywhere), but more importantly, it may not
+reflect all data that was in the original input. This is because the
+parser ignores all values that are not carried by (and only by) the
+Biomoby primitives types (as it was allowed before big change in
+summer 2005). So you can use this option to see if your XML data are
+up-to-date with the Biomoby API. <p>
+
+Here is a typical examples of invoking the script - the input file
+contains an example taken from the Biomoby API documentation: <p>
+
+<blockquote>
+<pre class=script>
+build/run/run-moby-parser -r example.xml
+</pre>
+</blockquote>
+
+<blockquote>
+<pre class=script>
+Authority: http://www.tempcalculator.org/meltyman
+Jobs (invocations):
+(1) Query ID: a1
+ Data elements:
+ (Simple) Article name:
+ MobyFloat, Id: 163483, Namespace: NCBI_gi
+ Value: 69.8
+(2) Query ID: a2
+ Data elements:
+ (Simple) Article name:
+ MobyFloat, Id: 635543, Namespace: NCBI_gi
+ Value: 72.1
+
+<?xml version="1.0" encoding="UTF-8"?>
+<moby:MOBY xmlns:moby="http://www.biomoby.org/moby">
+ <moby:mobyContent moby:authority="http://www.tempcalculator.org/meltyman">
+ <moby:mobyData moby:queryID="a1">
+ <moby:Simple>
+ <moby:Float moby:id="163483" moby:namespace="NCBI_gi">69.8</moby:Float>
+ </moby:Simple>
+ </moby:mobyData>
+ <moby:mobyData moby:queryID="a2">
+ <moby:Simple>
+ <moby:Float moby:id="635543" moby:namespace="NCBI_gi">72.1</moby:Float>
+ </moby:Simple>
+ </moby:mobyData>
+ </moby:mobyContent>
+</moby:MOBY>
+</pre>
+</blockquote>
<p>
@@ -26,7 +231,7 @@
<div align=right class="address">
<address><A HREF="mailto:martin.senger at gmail.com">Martin Senger</A><BR></address>
<!-- hhmts start -->
-Last modified: Sun Aug 28 18:39:46 2005
+Last modified: Mon Aug 29 10:43:33 2005
<!-- hhmts end -->
</div>
===================================================================
RCS file: /home/repository/moby/moby-live/Java/docs/Moses.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- /home/repository/moby/moby-live/Java/docs/Moses.html 2005/08/28 10:19:08 1.4
+++ /home/repository/moby/moby-live/Java/docs/Moses.html 2005/08/29 13:21:59 1.5
@@ -20,6 +20,43 @@
Moses can produce also code in Perl (if you think that it would be
useful let me know). <p>
+<a name="components"></a>
+<h2>MoSeS Components</h2>
+
+The documents listed below explain in details the whole Moses
+project. Because the main purpose of Moses is to support service
+providers, sometimes documentation focuses more on development ("how
+to write a code", "how it is done") rather on a randomly walking-in
+end-users ("how to use it"). If you are the latter you may find most
+in the sections describing various supporting command-line
+clients. <p>
+
+
+The Moses consists of four major parts: <p>
+
+<ul>
+ <li> <a href="Moses-generators.html">Code Generators</a>
+ <ul>
+ <li class=tiny> <a href="Moses-generators.html#datatypes">Data types generator</a>
+ <li class=tiny> <a href="Moses-generators.html#skeletons">Service skeletons generator</a>
+ </ul>
+ <p>
+
+ <li> <a href="Moses-parser.html">Biomoby XML Parser</a> and
+associated general data types for storage <p>
+
+ <li> <a href="Moses-clients.html">Support on the client side</a>, and
+ <ul>
+ <li class=tiny> <a href="Moses-clients.html#baseclient">Base client</a>
+ <li class=tiny> <a href="Moses-clients.html#basecmdlineclient">Base command-line client</a>
+ </ul>
+ <p>
+
+ <li> Support for service deployment (<em>not yet fully implemented</em>)
+
+</ul><p>
+
+
<a name="overview"></a>
<h2>Overview</h2>
@@ -264,38 +301,6 @@
<p>
-<a name="components"></a>
-<h2>MoSeS Components</h2>
-
-The documents listed below explain in details the whole Moses
-project. Because the main purpose of Moses is to support service
-providers, sometimes documentation focuses more on development ("how
-to write a code", "how it is done") rather on a randomly walking-in
-end-users ("how to use it"). If you are the latter you may find most
-in the sections describing various supporting command-line
-clients. <p>
-
-
-The Moses consists of four major parts: <p>
-
-<ul>
- <li> <a href="Moses-generators.html">Code Generators</a>
- <ul>
- <li class=tiny> <a href="Moses-generators.html#datatypes">Data types generator</a>
- <li class=tiny> <a href="Moses-generators.html#skeletons">Service skeletons generator</a>
- </ul>
- <p>
-
- <li> <a href="Moses-parser.html">Biomoby XML Parser</a> and
-associated general data types for storage <p>
-
- <li> Support on the client side (<em>not yet documented</em>), and
-
- <li> Support for service deployment (<em>not yet fully implemented</em>)
-
-</ul><p>
-
-
<hr>
<p>
@@ -311,7 +316,7 @@
<div align=right class="address">
<address><A HREF="mailto:martin.senger at gmail.com">Martin Senger</A><BR></address>
<!-- hhmts start -->
-Last modified: Sun Aug 28 19:03:43 2005
+Last modified: Mon Aug 29 16:07:55 2005
<!-- hhmts end -->
</div>
More information about the MOBY-guts
mailing list