[MOBY-guts] biomoby commit

Paul Gordon gordonp at pub.open-bio.org
Fri Jul 22 05:00:58 UTC 2005

Fri Jul 22 01:00:58 EDT 2005
Update of /home/repository/moby/moby-live/Java/docs
In directory pub.open-bio.org:/tmp/cvs-serv30675

Modified Files:
Log Message:
Finally got around to creating the jMOBY data instance documentation

moby-live/Java/docs SimpleClient.html,1.2,1.3
RCS file: /home/repository/moby/moby-live/Java/docs/SimpleClient.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- /home/repository/moby/moby-live/Java/docs/SimpleClient.html	2005/05/19 10:56:06	1.2
+++ /home/repository/moby/moby-live/Java/docs/SimpleClient.html	2005/07/22 05:00:58	1.3
@@ -1,24 +1,263 @@
-<html> <head>
-<title>Simple Client</title>
-<link rel="stylesheet" href="images/stylesheet.css" type="text/css">
-<link rel="shortcut icon" href="images/whale.gif">
-<h1>Simple Client</h1>
-Coming soon... (or later)
-<div align=right class="address">
-<address><A HREF="mailto:gordonp at cbr.nrc.ca">Paul Gordon</A><BR></address>
+  <head>
+    <link rel="stylesheet" href="images/stylesheet.css" type="text/css">
+    <link rel="shortcut icon" href="images/whale.gif">
+    <title>jMOBY Client/Server Quickstart</title>
+  </head>
+  <body>
+    <h1>jMOBY Client/Server Quickstart</h1>
+    <h2>Motivation</h2>
+    <p>
+      This document is intended to get you up and running using the client-server service communication
+      code (i.e. calling or providing remote Web Services) in the Java implementation 
+      (<a href="http://www.biomoby.org/moby-live/Java/docs/index.html">jMOBY</a>) of 
+      <a href="http://www.biomoby.org">MOBY</a>-S "Web Services for Molecular Biology".  If you are looking 
+      for more detailed information on how to query MOBY Central's yellow pages about what services are 
+      available, please see <a href="http://www.biomoby.org/moby-live/Java/docs/CmdLineClients.html">this 
+      document</a>.  This document assumes that you are familiar with <a href="http://java.sun.com">Java</a> and
+      <a href="http://www.w3.org/TR/2004/REC-xml-20040204/"><acronym title="eXtensible Markup Language">XML</acronym></a>.
+    </p>
+    <h2>Syntax Notes</h2>
+    <p>
+    <ul>
+      <li><code>jMOBY class, member and method names are display in this font face</code></li>
+      <li><blockquote><code>System.out.println("Example code is treated like 
+	    a block quote (indented paragraph)");</code></blockquote></li>
+      <li><em>MOBY-S XML elements and attributes are displayed in this font face</em></li>
+      <!--<li><blockquote><em>&lt;moby:String&gt;MOBY-S XML example markup is treated like 
+	    a block quote (indented paragraph)&lt;/moby:String&gt;</em></blockquote></li>-->
+   </ul>
+    </p>
+    <h2>Sections</h2>
+    <p>
+    <ul>
+      <li><a href="#APIAnatomy">API Anatomy</a></li>
+      <li><a href="#helloWorld">Hello World</a></li>
+      <li><a href="#creatingjMOBYData">Creating jMOBY Data</a></li>
+      <li><a href="#manipulatingjMOBYData">Manipulating jMOBY Data</a></li>
+      <li><a href="#creatingMOBYXML">Creating MOBY XML</a></li>
+      <li><a href="#parsingMOBYXML">Parsing MOBY XML</a></li>
+    </ul>
+    </p>
+    <hr/>
+  <a name="APIAnatomy"/>
+    <h2>Basic Anatomy of the Java API</h2>
+    <p>
+    Three main classes form the core of the API: 
+    <ol>
+	<li><code>org.biomoby.shared.data.MobyDataObject</code> - 
+	<a href="http://mobycentral.icapture.ubc.ca:8090/types/Objects">any valid</a> 
+	<a href="http://www.biomoby.org/twiki/bin/view/Moby/MobySAPI#ObjectStructure">data object</a> 
+	you want to transmit will be encoded using methods in this class or its subclasses. You never 
+	need to handcode any XML (but of course you can if you really want to).</li>
+	<li><code>org.biomoby.shared.data.MobyDataObjectSet</code> - for grouping <code>MobyDataObject</code>s together, 
+	implements the Java <code><a href="http://www.javadocs.org/Collection">Collection</a></code> interface,
+	and is the equivalent of the 
+	<em><a href="http://www.biomoby.org/twiki/bin/view/Moby/MobySAPI#Procedure_Call_Parameters">Collection</a></em> 
+	container 
+	<a href="http://www.w3.org/TR/2004/REC-xml-20040204/#dt-element">element</a> in the current MOBY-S API.</li>
+	<li><code>org.biomoby.shared.MobyRequest</code> - this class handles all of the network communication 
+	(<a href="http://www.w3.org/2000/xp/Group/"><acronym title="Simple Object Access Protocol">SOAP</acronym></a> 
+	messaging) required between client and server.</li>
+    </ol>
+    </p>
+    <p>
+      Be sure to include the following statements in the header for any class in which you plan to use jMOBY
+      service communication:
+      <blockquote><code>import org.biomoby.client.*;<br/>import org.biomoby.shared.*;<br/>import org.biomoby.shared.data.*;</code></blockquote>
+    </p>
+    <hr/>
+    <a name="helloWorld"/>
+    <h2>Hello World (or its bioinformatics equivalent)</h2>
+      <p>
+	The following code has two parts.  First, a service called "MOBYSHoundGetGenBankff" is found via MOBY Central.  
+	This service fetches sequences based on keys such as GenBank gi identifiers.  Second, the service
+	is called using <code>MobyRequest</code> with a sample input <code>MobyDataObject</code>.  The result of the 
+	service invocation (a DNA sequence in XML) is printed.
+      <blockquote><code>
+import org.biomoby.client.*;
+import org.biomoby.shared.*;
+import org.biomoby.shared.data.*;
+public class HelloMOBY {
+    public static void main(String[] args) throws Exception{
+        Central worker = new CentralImpl();
+        MobyService templateService = new MobyService("MOBYSHoundGetGenBankff");
+        MobyService[] validServices = worker.findService(templateService);
+	MobyRequest mr = new MobyRequest(worker);
+	mr.setService(validServices[0]);
+	mr.setInput(new MobyDataObject("NCBI_gi", "111076"));
+	System.out.println(mr.invokeService().toString());
+    }
+	  </pre></code></blockquote>
+	A version of this code with comments and error checking is available in the 
+	<a href="http://www.biomoby.org/GettingTheCode.html">MOBY CVS</a> as Java/src/Clients/TestRequest.java
+<a name="creatingjMOBYData"/>
+  <h2>Creating jMOBY Data</h2>
+  <p>
+    The Java API is designed so that all of the MOBY-S XML concepts can be "get" or "set" using Java primitives 
+    (<code>String</code>s, <code>Number</code>s, etc.) as parameters to class methods.  You do not need to 
+    write or parse XML. There are several key features of jMOBY that minimize the number of classes you need to 
+    familiarize yourself with:
+    <ul>
+      <li>MOBY service requests and MOBY service responses are essentially identical in format according 
+	to the MOBY-S specification, therefore all jMOBY classes are common to both 
+	service providers and consumers.</li>
+      <li>Any MOBY object can be easily decomposed into a few primitive object types and a grouping data type</li> 
+      <li>jMOBY data objects can be used both for service discovery (asking MOBY Central: what Web services accept this 
+	object as input?) and service invocation (submitting data to a server providing the service)</li>
+      <li>jMOBY data objects in the <code>org.biomoby.share.data</code> package are all mutable, and use standard Java
+        interfaces and objects.  For a further description of the object hierarchy, please see <a href="moby_java_api.jpg">this document</a>.</li>
+      </ul>
+  </p>
+  <p>Because of the input/output symmetry of service data, MOBY objects are highly reusable when you are trying to chain 
+    together multiple service discoveries and invocations.  If you are interested in creating
+    reusable workflows (MOBY macros of sorts), you may wish to look at <a href="http://taverna.sourceforge.net/">Taverna</a>.
+  </p>
+  <h3>Creating a database identifier object</h3>
+   <p>Database identifiers are often the starting point for workflows, as they can be used to retrieve sequence data, 
+  which is then visualized or submitted to other services.  All MOBY objects have 
+<a href="http://www.biomoby.org/twiki/bin//view/Moby/MobySAPI#The_root_Object_Class_Minimal_St">a namespace and an ID</a>, 
+therefore a database identifier is the simplest form of a object.  A <code>MobyDataObject</code> constructor is available
+to easily build database identifiers (<code>MobyDataObject(String namespace, String id)</code>):
+<blockquote><code>MobyDataObject dbid = new MobyDataObject("NCBI_gi", "111076");</code></blockquote>
+   </p>
+  <h3>Creating a "primitive" data object</h3>
+The following data are considered irreducible, atomic, or "primitive" in MOBY:
+<table border="1">
+<tr><th><a href="http://www.biomoby.org/twiki/bin//view/Moby/MobySAPI#The_MOBY_Data_Class_Ontology">MOBY Specification</a></th><th>jMOBY class in <code>org.biomoby.shared.data</code></th><th>underlying Java implementation</th><th>Can be instantiated using any one of</th></tr>
+  <tr><td><em>Object</em></td><td><code>MobyDataObject</code></td><td>implements <code><a href="http://www.javadocs.org/Comparable">Comparable</a></code></td><td><ul><li>"namespace", "id"</li><li>MOBYDataObject (cloning)</li></ul></tr>
+  <tr><td><em>String</em></td><td><code>MobyDataString</code></td><td><code><a href="http://www.javadocs.org/StringBuffer">java.lang.StringBuffer</a></code></td><td><ul><li><a href="http://www.javadocs.org/CharSequence/">java.lang.CharSequence</a> (i.e. CharBuffer, String, StringBuffer, StringBuilder)</li></ul></td></tr>
+  <tr><td><em>Integer</em></td><td><code>MobyDataInt</code></td><td><code><a href="http://www.javadocs.org/BigInteger">java.math.BigInteger</a></code></td><td><ul><li>int</li><li><a href="http://www.javadocs.org/Number">java.lang.Number</a> (i.e. Byte, Double, Float, Integer, Long, Short, BigInteger, BigDecimal)</li><li>Strings like "2005"</li></ul></tr>
+  <tr><td><em>Float</em></td><td><code>MobyDataFloat</code></td><td><code><a href="http://www.javadocs.org/BigDecimal">java.math.BigDecimal</a></code></td><td><ul><li>double</li><li>java.lang.Number</li><li>Strings like "2.0-e4" or "0.0002"</li></ul></tr>
+  <tr><td><em>DateTime</em></td><td><code>MobyDataDateTime</code></td><td><code><a href="http://www.javadocs.org/GregorianCalendar">java.util.GregorianCalendar</a></code></td><td><ul><li>java.util.GregorianCalendar</li><li>Strings like "2005-07-21" (a <a href="http://www.w3.org/TR/NOTE-datetime">W3C profile version of an ISO 8601 date-time string</a>)</a></ul></tr>
+Any object can also be instantiated using the corresponding XML data as an <code><a href="http://www.javadocs.org/Element">org.w3c.dom.Element</a></code>.
+ </p>
+  <p>Below are some (hopefully) self-explanatory primitive object creation examples:
+<blockquote><code>MobyDataString sequenceString = new MobyDataString("MPGGFILAIDEGTTSARAIIYNQDLEVLGIGQYDFPQHYPSPGYVEHNPDEIWNAQMLAI");</code></blockquote>
+<blockquote><code>MobyDataInt sequenceLength = new MobyDataInt(60);</code></blockquote>
+<blockquote><code>MobyDataFloat sequence<a href="http://www.expasy.org/tools/pi_tool-doc.html">PI</a> = new MobyDataFloat(3.67);</code></blockquote>
+<blockquote><code>MobyDataFloat sequence<a href="http://www.ncbi.nlm.nih.gov/Education/BLASTinfo/information3.html"><acronym title="Blasic LocalAlignment Search Tool">Blast</acronym></a><a href="http://www.ncbi.nlm.nih.gov/BLAST/tutorial/Altschul-1.html#head2">EValue</a> = new MobyDataFloat("1e-29");</code></blockquote>
+<blockquote><code>MobyDataDateTime <a href="ftp://ftp.ncbi.nih.gov/blast/db/blastdb.txt">blastDB</a>Updated = new MobyDataDateTime("2005-03-24");</code></blockquote>
+<h3>Creating composite objects</h3>
+<p>Many times, you will want to send a piece of data that is more complex than a primitive. These can be built using
+<code>MobyDataComposite</code>, which implements the <code><a href="http://www.javadocs.org/Map">java.util.Map</a></code> interface.  For example, if a <a href="http://mobycentral.icapture.ubc.ca/cgi-bin/list.services.cgi?feeds=MOBYSHoundGetGenBankWhateverSequence:AminoAcidSequence">service requires</a> an 
+<em><a href="http://mobycentral.icapture.ubc.ca/cgi-bin/MOBY_display_object_xml.cgi?obj=AminoAcidSequence&art=example">AminoAcidSequence</a></em> as input,
+its two members, <em>SequenceString</em> and <em>Length</em> can be set like so:
+MobyDataComposite aaSequenceObject = new MobyDataComposite("AminoAcidSequence");
+aaSequence.put("SequenceString", new MobyDataString(aaSequence));
+aaSequence.put("Length", new MobyDataInt(aaSequence.length()));
+<a name="manipulatingjMOBYData"/>
+<h2>Manipulating jMOBY data</h2>
+Coming soon.
+<h3>Dissecting queries and responses</h3>
+<h3>Changing data objects</h3>
+    <hr/>
+    <a name="creatingMOBYXML"/>
+    <h2>Creating MOBY XML (responses and queries)</h2>
+      <p>
+      It may at times be necessary to explicitly create a 
+      <a href="http://www.biomoby.org/twiki/bin/view/Moby/MobySAPI#INPUT"/>full MOBY
+	XML document</a> (i.e. serialize jMOBY objects). For example to store a response on disk for later usage, or
+      just so you can create your own SOAP response as a service provider.  The 
+      <code>org.biomoby.shared.data.MobyDataUtils</code> class provides the ability to output 
+      XML documents, by specifiying an <code>java.io.OutputStream</code> and the contents.
+      </p>
+    <h3>Create a blank MOBY XML response</h3>
+    <p>
+      Use the one-object convenience constructor for <code>org.biomoby.shared.data.MobyContentInstance</code>.  
+      It will automatically create the content envelope.  Since the object (first arg) is null, the <em>mobyData</em> 
+      will be blank.  This data envelope is then made into a proper XML file, with declarations and all, by
+      <code>MobyDataUtils</code>.
+    <blockquote><code>MobyDataUtils.toXMLDocument(System.out, new MobyContentInstance(null, null));</code></blockquote>
+    </p>
+    <h3>Create a MOBY XML response or query with a single data object</h3>
+    <p>
+      Use the one-object convenience constructor for <code>MobyContentInstance</code>.  It will automatically 
+      create the full content envelope and embed the XML for your object.  The object must be or inherit from 
+      <code>MobyDataObject</code> (<em>Simples</em>), or <code>MobyDataObjectSet</code> (<em>Collections</em>)
+      to form a valid content envelope.
+    <blockquote><code>MobyDataUtils.toXMLDocument(System.out, new MobyContentInstance(new 
+	                                              MobyDataObject("gi", "100089"), null));</code></blockquote>
+    </p>
+    <h3>Create a MOBY XML response or query envelope with multiple invocations</h3>
+    <p>
+      Use the default constructor for <code>MobyContentInstance</code>, then add at least one <code>MobyDataInstance</code>
+to it using the <code>java.lang.Map</code> interface or the convenient one-arg <code>put</code> method.
+MobyContentInstance queries = new MobyContentInstance();
+data.put(new MobyDataObject("gi", "100089"));
+data.put(new MobyDataObject("gi", "324442"));
+MobyDataUtils.toXMLDocument(System.out, queries);
+<a name="parsingMOBYXML"/>
+<h2>Parsing MOBY XML</h2>
+<p>As a counterpart to the utility above, jMOBY provides a method to deserialize a response/request envelope:
+MobyContentInstance queries = MobyDataUtils.fromXMLDocument(System.in);
+System.out.println("The document contained " + ((queries.size() == 1) ? "1 query" : (query.size() + " queries")));
+    <hr>
+    <address><a href="mailto:gordonp at ucalgary.ca">Paul Gordon</a></address>
+<!-- Created: Wed Jul 20 11:44:30 MDT 2005 -->
 <!-- hhmts start -->
-Last modified: Tue May 17 15:34:15 2005
+Last modified: Thu Jul 21 23:45:59 MDT 2005
 <!-- hhmts end -->
-</body> </html>
+  </body>

More information about the MOBY-guts mailing list