[MOBY-guts] biomoby commit
Paul Gordon
gordonp at pub.open-bio.org
Fri Jul 22 05:00:58 UTC 2005
gordonp
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:
SimpleClient.html
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">
-</head>
-
-<body>
-
-<center>
-<h1>Simple Client</h1>
-</center>
-
-<blockquote><em>
-Coming soon... (or later)
-</em></blockquote>
-
-<hr>
-<div align=right class="address">
-<address><A HREF="mailto:gordonp at cbr.nrc.ca">Paul Gordon</A><BR></address>
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+ <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><moby:String>MOBY-S XML example markup is treated like
+ a block quote (indented paragraph)</moby:String></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>
+<pre>
+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
+<hr/>
+<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>
+<p>
+The following data are considered irreducible, atomic, or "primitive" in MOBY:
+<table border="1">
+<thead>
+<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>
+</thead>
+<tbody>
+ <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>
+</tbody>
+</table>
+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>
+<blockquote><code></code></blockquote>
+</p>
+
+<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:
+
+<blockquote><code><pre>
+String aaSequence = "MPGGFILAIDEGTTSARAIIYNQDLEVLGIGQYDFPQHYPSPGYVEHNPDEIWNAQMLAI";
+MobyDataComposite aaSequenceObject = new MobyDataComposite("AminoAcidSequence");
+aaSequence.put("SequenceString", new MobyDataString(aaSequence));
+aaSequence.put("Length", new MobyDataInt(aaSequence.length()));
+</pre></code></blockquote>
+
+</p>
+<hr/>
+
+<a name="manipulatingjMOBYData"/>
+<h2>Manipulating jMOBY data</h2>
+<p>
+Coming soon.
+</p>
+
+<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.
+<blockquote><code><pre>
+MobyContentInstance queries = new MobyContentInstance();
+data.put(new MobyDataObject("gi", "100089"));
+data.put(new MobyDataObject("gi", "324442"));
+MobyDataUtils.toXMLDocument(System.out, queries);
+</pre></code></blockquote>
+<hr/>
+<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:
+<blockquote><code><pre>
+MobyContentInstance queries = MobyDataUtils.fromXMLDocument(System.in);
+System.out.println("The document contained " + ((queries.size() == 1) ? "1 query" : (query.size() + " queries")));
+</pre></code></blockquote>
+</p>
+
+
+ <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 -->
-</div>
-</body> </html>
+ </body>
+</html>
More information about the MOBY-guts
mailing list