Most of the clients listed in this document have their own detailed help. Just start them with an -h or -help option on the command line. The help may not give too verbose explanation but it usually is much more up-to-date regarding all available options.
The examples below use run-time scripts for invoking the clients. The scripts do nothing more than setting the variable CLASSPATH and invoking Java with an appropriate class. The location of the scripts depends on how you got jMoby:
Clients exploring BioMoby registry
Clients accessing BioMoby services
MobyCmdLineClient
MobyGraphs
MobyDigestClient
CacheRegistryClient
TestingCentral
If you wish to get a less verbose output, use the -q. On the contrary, if you wish to see all XML messages going back and forth, use the -debug option.
run-cmdline-client -ls ... list names of all available services run-cmdline-client -lp ... list names of all available service providers run-cmdline-client -lt ... list names and descriptions of all service types run-cmdline-client -ln ... list names and descriptions of all namespaces run-cmdline-client -ld ... list names and descriptions of all data typesIn order to get entities by their names, use -wsdl for WSDL of service instances and -data for data types:
run-cmdline-client -wsdl <service-name> run-cmdline-client -wsdl <service-name,authority-name> run-cmdline-client -data <data-type-name>In order to get all details about a service instance, use -fn:
run-cmdline-client -fn <service-name> run-cmdline-client -fn <service-name,authority-name>The same format as above, but without the service name, can be used to get all services from the given authority (but see also -fs-auth for similar purpose later on). For example to get all services from the famous Mark's authority www.illuminae.com, type (note that comma there):
run-cmdline-client -fn ,www.illuminae.comAt the moment of writing this document, the (quite impressive) result is:
getTaxNameFromTaxID MOBYSHoundGetGenBankff getTaxChildNodes getGoTerm getSHoundProteinFromOrganism getSHoundNeighboursFromGi RetrieveGOFromKeywords MOBYSHoundGetGenBankVirtSequence MOBYSHoundGetGenBankWhateverSequence getSHoundProteinsFromTaxID test_SMTP getSHoundGODBGetParentOf getDragonLocusAlleles MarkTestingSecondaries getSHoundDNAFromOrganism getSHound3DNeighboursFromGi PBI_Cluster_Blast MOBYSHoundGetGenBankFasta getTaxParent getGoTermAssociations getSHoundGODBGetChildrenOf getSHoundDNAFromTaxIDIn order to find services given by their attributes, use -ft for finding services of the given service type and -f for finding services by keyword (for keywords, use a comma-delimited lists of keywords):
run-cmdline-client -ft <service-type> run-cmdline-client -f <keywords>You can also find services combining their attributes, and perhaps adding also their input and/or output data types (note that this works only for simple data, not for collections). Use one or more options on the same command line:
run-cmdline-client \
-fs-type <service-type> \
-fs-auth <authority> \
-fs-in <inputs> \
-fs-out <outputs>
The inputs are comma-delimited names of inputs; each of them
is a pair of an input type and a namespace separated by an equal
sign. The outputs are comma-delimited names of output types.
Here you already see that the command-line syntax can become quite complex (and it will be even worse for registering services). It is still good that you can do everything from the command line (especially because you can automate things) - but the casual users may consider some Web-based, and form-driven, clients that are coming soon.It is time for some examples. Let's find all services of type NCBI_Blast. The request:
run-cmdline-client -fs-type NCBI_Blastreturns three services:
plantspBlastProtein run_ntBlast PBI_Cluster_BlastIf we limit it also by authority www.sdsc.edu:
run-cmdline-client -fs-type NCBI_Blast -fs-auth www.sdsc.eduwe get just one service:
plantspBlastProteinAll just described options return a list of found services with all details. Often you wish to get only their names - for that use -on option.
Because services do not exist only on their own but they have relationships to other services you discover also related services. By default, the list of returned services contains also more specific services (i.e. services that are child types of the service type you requested), and also services that operate not only on the data type you have requested but also on any parent data type. You can, however, limit this behavior by using options:
run-cmdline-client -ot <service-type-name>Or print all relationships of given data type:
run-cmdline-client -od <data-type-name>Or print all relantionships of given type for given data type:
run-cmdline-client -od2 <data-type-name> ISA run-cmdline-client -od2 <data-type-name> HASA run-cmdline-client -od2 <data-type-name> HASFor example, after invoking:
run-cmdline-client -ot NCBI_Blastyou get back:
Service type 'NCBI_Blast' is-a: ------------ urn:lsid:biomoby.org:servicetype:Analysis urn:lsid:biomoby.org:servicetype:ServiceOr, by invoking:
run-cmdline-client -od DNASequenceyou get back:
Relationships of data type 'DNASequence':
--------------------------
urn:lsid:biomoby.org:objectrelation:hasa
urn:lsid:biomoby.org:objectclass:String
urn:lsid:biomoby.org:objectclass:Integer
urn:lsid:biomoby.org:objectrelation:isa
urn:lsid:biomoby.org:objectclass:NucleotideSequence
urn:lsid:biomoby.org:objectclass:GenericSequence
urn:lsid:biomoby.org:objectclass:VirtualSequence
urn:lsid:biomoby.org:objectclass:Object
urn:lsid:biomoby.org:objectclass:Object
Note that you have always register first those entities on which other entities are dependent. For example, you need first to register all data types and service types before registering a service using them.
In order to register a service type use the following options (they all together define one new service type):
run-cmdline-client \
-rt-name <service-type-name> \
-rt-desc <service-type-description> \
-rt-email <service-type-contact> \
-rt-auth <service-type-authority> \
-rt-isa <service-type-parents>
The <service-type-parents> is a comma-delimited list of names of
the parent service types.
Well, at the moment, the service ontology supports only single inheritance, so the list should be always a one-element list - but it may change in the future.In order to register a namespace use the following options (they all together define one new namespace):
run-cmdline-client \
-rn-name <namespace-name> \
-rn-desc <namespace-description> \
-rn-auth <namespace-authority> \
-rn-email <namespace-contact>
In order to register a data type use the following options (again,
they all together define one new data type):
run-cmdline-client \
-rd-name <data-type-name> \
-rd-desc <data-type-description> \
-rd-auth <data-type-authority> \
-rd-email <data-type-contact> \
-rd-isa <data-type-parents> \
-rd-hasa <data-type-attributes> \
-rd-has <data-type-attributes>
The <data-type-parents> is a comma-delimited list of
names of the parent data types (again, at the moment, BioMoby registry
accepts only one parent). The <data-type-attributes> define other data types that are attributes of the data type that is being registered. Their relationship is either HAS or HASA depending on the option used. In both cases, it is a comma-delimited list (or just one element) where each element may have two parts separated by a colon:
<article-name>:<data-type-name>This requires an example. Let's register a data type with the following relationships:
A ColouredString ISA String and HASA three Integers (named R, B and G)Note that it has three integers but each of them only once (under a different article name) - therefore we use the HASA relationship (and not the HAS one). Here is how we register this new data type (see that we are using a testing registry in order not to pollute the real one):
run-cmdline-client \
-e http://mobytest.biordf.net/MOBY-Central.pl \
-uri http://mobytest.biordf.net/MOBY/Central \
-rd-name ColouredString \
-rd-desc 'A string representing a colour' \
-rd-auth uk.ac.ebi.martin.senger \
-rd-email senger@ebi.ac.uk \
-rd-isa String \
-rd-hasa R:Integer,G:Integer,B:Integer
And, indeed, it worked - as you can see by typing:
run-cmdline-client \
-e http://mobytest.biordf.net/MOBY-Central.pl \
-uri http://mobycentral.cbr.nrc.ca:8080/MOBY/Central \
-data ColouredString
you get back:
Data type 'ColouredString':
---------
Name: urn:lsid:biomoby.org:objectclass:ColouredString
Auth: uk.ac.ebi.martin.senger
Desc: A string representing a colour
Contact: senger@ebi.ac.uk
Parents:
urn:lsid:biomoby.org:objectclass:String
Children (only those registered here):
R (HASA) => urn:lsid:biomoby.org:objectclass:Integer
G (HASA) => urn:lsid:biomoby.org:objectclass:Integer
B (HASA) => urn:lsid:biomoby.org:objectclass:Integer
The remaining, but the most complex, is a service registration. Use
the following options (again, they all together define one new
service):
run-cmdline-client \
-rs-name <service-name> \
-rs-type <service-type-name> \
-rs-categ <service-category> \
-rs-desc <service-description> \
-rs-auth <service-authority> \
-rs-email <service-contact> \
-rs-url <service-URL> \
-rs-main <service-authoritative> \
-rs-rdf <service-signature-URL> \
-rs-rdfpath <path-to-RDF-file> \
-rs-in <inputs> \
-rs-ifile <files-with-inputs> \
-rs-out <outputs> \
-rs-ofile <files-with-outputs>
For <service-authoritative> use value 1 or 0 (see
explanation what authoritative service means at BioMoby
API page. The <service-signature-URL> and <path-to-RDF-file> deal with a new way how to keep service registered (or in other words: how to de-register it). The idea is that when you register a service you send along a URL pointing to a place where will be (or where it is already) an RDF document describing this service. This URL should point to a space that you control (the RDF document will sit at your computer somewhere, not in the BioMoby registry). Such URL is specified by the option -rs-rdf.
But how can you get such RDF document? Should you study how to write RDF files? No. When you ask BioMoby registry to register your new service it will return back such RDF document (if the registration request was successful). The MobyCmdLineClient creates a temporary file and saves there the returned RDF description. It also tells you what is the name of this temporary file so you can copy the file to the location where the <service-signature-URL> points to. However, you can make this more automated if you use option -rs-rdfpath - then MobyCmdLineClient puts the returned RDF document directly to this place (overwriting possibly existing document there).
The service registration includes also the input data types that this service is able to deal with. You have two options how to say what data types are expected - and you can combine both. One is an option -rs-in that takes a comma-delimited elements - each of them is a pair of a data type name and a namespace separated by an equal sign (it is easier to follow this obscure syntactical rules in a example below). The second is the option -rs-ifile that takes a comma-separated list of file names defining input data. The files should have a format of Java properties files. The second option is the only one to use if you wish to have more than one namespace attached to a particular data type. Here is an example of such file (note that the numbers at each line should not be there, they are here just to help with explanation what individual lines mean):
simple (1) name = first simple input (2) datatype = TestingDataType (3) namespaces.1 = TestingNamespace (4) namespaces.2 = TestingNamespace2 (5)Line (1) says that this is a simple data type (an opposite would be a collection - see below). Line (2) defines an article name for this data type. Line (3) defines a data type name (remember that such data type has to be registered in advance - see above). And lines (4) and (5) define all namespaces required by this service for this data type (again the namespaces have to be registered in advance).
Here is another example for an input of a collection type:
collection (1) name = nice collection (2) file.1 = data/simple1.data (3) file.2 = data/simple2.data (4) file.3 = data/simple3.data (5)Line (1) says that we have a collection here. Line (2) defines an article name for such collection. And lines (3), (4) and (5) point to other files defining simple elements of this collection. The files are here:
File data/simple1.data:
simple name = simple 1 in collection datatype = TestingDataType4 namespaces.1 = TestingNamespaceFile data/simple2.data:
simple name = simple 2 in collection datatype = TestingDataType2 namespaces = TestingNamespace2File data/simple3.data:
simple name = simple 3 in collection datatype = TestingDataType3 namespaces = TestingNamespaceIf you think it is enough, it is not. A service can also have a secondary input. Here is a file for it:
secondary (1) name = favourite secondary article (2) datatype = Integer (3) default = 123 (4) max = 23 (5) min = 234 (6) enum.1 = 30 (7) enum.2 = 40 (8) enum.3 = 50 (9)As you see the secondary input may have some constrains defined: a default value - line (4), minimum and maximum values - lines (5) and (6), and a list of allowed values - lines (7), (8) and (9).
For the service outputs, use options -rs-out and/or -rs-ofile in the same way as for inputs (the only difference is that a service cannot have a secondary output).
From the explanation above, it is obvious that a service registration is quite complex - especially with richer inputs and/or outputs. Therefore, in many cases, it would be faster to create a required XML input manually (see again documentation in BioMoby API page) and to send it directly to the registerService method. The MobyCmdLineClient supports it - see below the option -call.Now, the promised example. Let's register a service Testing_getAlleleFreq which will be the same service as an existing one - getAlleFreq (so we do not need to register involved data types, service type and namespaces). In XML, the service has the following attributes and input/output data types (unscrupulously stolen from an existing getAlleFreq service):
<Services>
<Service authURI='www.hapmap.org' serviceName='getAlleleFreq'>
<serviceType>Retrieval</serviceType>
<authoritative>0</authoritative>
<Category>moby</Category>
<Description>
getAlleleFreq
</Description>
<contactEmail>hapmap@hapmap.edu</contactEmail>
<signatureURL></signatureURL>
<URL>http://chimay/cgi-bin/work_in_progress/hapmap_dispatcher.cgi</URL>
<Input>
<Simple articleName='snpLSID'>
<objectType>Object</objectType>
<Namespace>Haplotyping_Study</Namespace>
</Simple>
<Simple articleName='panelLSID'>
<objectType>Object</objectType>
<Namespace>Haplotyping_Study</Namespace>
</Simple>
</Input>
<Output>
<Simple articleName=''>
<objectType>allele_freq</objectType>
<Namespace>Haplotyping_Study</Namespace>
</Simple>
</Output>
<secondaryArticles>
</secondaryArticles>
</Service>
</Services>
The command line for registration will use two additional files for
defining inputs (because there is no way to define an article name
just on the command line). They are here:File in-allele-1 has this:
simple name = snpLSID datatype = Object namespaces.1 = Haplotyping_StudyFile in-allele-2 has this:
simple name = panelLSID datatype = Object namespaces.1 = Haplotyping_StudyThen the command line (going again to a testing registry, not to a production one) looks like this:
run-cmdline-client \
-e http://mobytest.biordf.net/MOBY-Central.pl \
-uri http://mobycentral.cbr.nrc.ca:8080/MOBY/Central \
-rs-name Testing_getAlleleFreq \
-rs-type Retrieval \
-rs-categ moby \
-rs-desc 'a testing get allele frequency' \
-rs-auth uk.ac.ebi.martin.senger \
-rs-email senger@ebi.ac.uk \
-rs-url http://chimay/cgi-bin/work_in_progress/hapmap_dispatcher.cgi \
-rs-main 0 \
-rs-rdf http://my.url.space/services/Testing_getAlleleFreq.rdf \
-rs-rdfpath /tmp/Testing_getAlleleFreq.rdf \
-rs-ifile in-allele-1,in-allele-2 \
-rs-out allele_freq=Haplotyping_Study
And, indeed, by typing:
run-cmdline-client \
-e http://mobytest.biordf.net/MOBY-Central.pl \
-uri http://mobycentral.cbr.nrc.ca:8080/MOBY/Central \
-fn Testing_getAlleleFreq
you get back a definition of a new service. And, a file
/tmp/Testing_getAlleleFreq.rdf was created with an RDF definition of our new service.
run-cmdline-client -ud <name> ... unregister data type known under this name run-cmdline-client -ut <name> ... unregister service type known under this name run-cmdline-client -un <name> ... unregister namespace known under this nameFor unregistering service, you can use a similar option:
run-cmdline-client -us <name,authority>but it has been deprecated. The new way to unregister your service is to remove its RDF definition (remember that it sits on your computer, in your HTTP space, so only you have access to it which is AGD - A Good Thing) and wait for a BioMoby agent to unregister your service automatically (when it does not find your RDF file when it visits you next time).
Here is an example that unregisters what we had done in the previous section: it unregister our ColouredString data type and our Testing_getAlleleFreq from the testing registry:
run-cmdline-client \
-e http://mobytest.biordf.net/MOBY-Central.pl \
-uri http://mobycentral.cbr.nrc.ca:8080/MOBY/Central \
-us Testing_getAlleleFreq \
-ud ColouredString
It correctly unregisters our ColouredString but for our
testing service it reports that "it is illegal to deregister a
service that has a signatureURL. Such services must be deregistered by
deleting the RDF at the location identified by the
signatureURL". Well, so cannot do anything, we need just to wait
when a BioMoby agent visits the testing registry (because the agent surely
will not find any file at our, invented and never filled, URL
http://my.url.space/services/Testing_getAlleleFreq.rdf).
Regarding a BioMoby registry, you can ask, for example, for all service names using this raw call (it does not take any input data):
run-cmdline-client -call retrieveServiceNamesAnd you get back a raw XML output:
<serviceNames>
<serviceName name='ASA' authURI='bioserv.rpbs.jussieu.fr'/>
<serviceName name='Automat' authURI='bioserv.rpbs.jussieu.fr'/>
<serviceName name='BasicBuilder' authURI='bioserv.rpbs.jussieu.fr'/>
<serviceName name='BlastFastaVsArabiProteincoding' authURI='mips.gsf.de'/>
...
</serviceNames>
Here is an another example taking an input directly on the command
line:
run-cmdline-client \
-call retrieveObjectDefinition \
'<retrieveObjectDefinition><objectType>DNASequence</objectType></retrieveObjectDefinition>'
It returns a raw data type definition of a DNASequence:
<retrieveObjectDefinition>
<objectType>urn:lsid:biomoby.org:objectclass:DNASequence</objectType>
<Description><![CDATA[Lightweight representation a DNA sequence]]></Description>
<authURI>www.illuminae.com</authURI>
<contactEmail>markw@illuminae.com</contactEmail>
<Relationship relationshipType='urn:lsid:biomoby.org:objectrelation:isa'>
<objectType articleName=''>urn:lsid:biomoby.org:objectclass:NucleotideSequence</objectType>
</Relationship>
</retrieveObjectDefinition>
Note that it does the same (except that both input and output are directly in XML) as:
run-cmdline-client -data DNASequenceAs already said, the input data can be put into a file and the file name is put on the command line:
run-cmdline-client -call retrieveObjectDefinition input.xmlOne interesting usage of the -call option is to call methods that are not directly supported by MobyCmdLineClient. There is a (slightly undocumented) method returning back the full BioMoby registry in SQL:
run-cmdline-client -q -call DUMP > registry.sqlAnother interesting usage of this option is to call BioMoby services. Because it requires to know a URL of a service, and to use a different -uri parameter than for Biomoby registry, there is a convenient wrapper, an option -scall. It is described in details in the next section of this document.
And that's all what MobyCmdLineClient can do. Ufff...
Coming soon... (or later)
Well, not yet. But BioMoby API will be soon (or later) extended by calls returning RDF documents with all registered data types and service instances. When this happens this client will be optimized by using such RDF documents.You can ask BioMoby registry for individual entities, such as services or data types definitions, or you can ask for a complete list of their names. The latter usually contains also entity's description or some other attribute but not all attributes. Which is fine for most uses.
However, for programs that want to explore the entire registry, it is good to have an extended API that gives back a complete set of entities (like when you get all emails from a mailing list once a day, as a digest - therefore the name for such API).
The MobyDigestClient uses such extended API. This client does not have much use on its own - the main reason for this client is to test if the implementation of the extended API works.
It has the same options -e and -uri for defining which BioMoby registry to contact (as in MobyCmdLineClient - see details there). Or, it can take data from a local cache defined by an option -cachedir (see more about this option in CacheRegistryClient).
Otherwise, it has three options defining what to get from a registry:
run-digest-client -t ... gets all service types run-digest-client -s ... gets all services run-digest-client -d ... gets all data typesAll these options can take some time to finish (except when you help with -cachedir, of course).
The options above returns just the names of wanted entities. For details use option -details. For example, the command line:
run-digest-client -d -detailsreturns:
Name: urn:lsid:biomoby.org:objectclass:NCBI_BLAST_Text
Auth: www.illuminae.com
Desc: Plaintext Blast report from NCBI Blast software
Contact: markw@illuminae.com
Parents:
urn:lsid:biomoby.org:objectclass:text-formatted
Children (only those registered here):
---
Name: urn:lsid:biomoby.org:objectclass:PubMed-MEDLINE
Auth: http://prometheus.brc.mcw.edu/MOBY/Central
Desc: Pubmed article in MEDLINE display format
Contact: vnarayan@mcw.edu
Parents:
urn:lsid:biomoby.org:objectclass:text-formatted
Children (only those registered here):
---
... (and many more)
Note that there are inconsistencies what is considered a name. For services:
run-digest-client -sreturns simple names:
getSHoundDNAFromTaxID Melting getSHoundNeighboursFromGi getEmblAccession Clustalw ...and for data types:
run-digest-client -dreturns names encoded as LSIDs:
urn:lsid:biomoby.org:objectclass:Global_Keyword urn:lsid:biomoby.org:objectclass:CommentedDNASequence urn:lsid:biomoby.org:objectclass:WU_BLAST_Text urn:lsid:biomoby.org:objectclass:TargetP_result urn:lsid:biomoby.org:objectclass:b64_encoded_PDB ...The inconsistency is in the current implementation of the BioMoby registry.
Note that the same cache can be also created by some other clients (e.g. MobyDigestClient) if they use an option -cachedir pointing to an empty or a non-existent directory. But these other clients cannot tell you how old the cache is, and they cannot remove it.
The CacheRegistryClient has one mandatory argument:
-cachedir <directory>that specifies a directory where to create a cache, or where is an existing cache. The same <directory> can be used for several different BioMoby registries. Each of them actually fills a subdirectory in the cache directory with a name created from the usual options -e (a BioMoby registry endpoint) and -uri (a BioMoby registry namespace). For example, you can use the same -cachedir <directory> for a default registry and for a testing registry.
The other arguments are:
Well, not all BioMoby entities are cached - just the service and data types definitions. but these are the main ones.
run-testing-centraland you should get a similar output to this one:
retrieveServiceNames OK retrieveServiceProviders OK retrieveServiceTypes OK retrieveNamespaces OK retrieveObjectNames OK registerServiceType OK registerNamespace - 1 OK registerNamespace - 2 OK registerDataType - 1 OK registerDataType - 3 OK registerDataType - 2 OK getDataTypeDefinition - 2 OK registerService OK deregisterService OK deregisterDataType - 2 OK deregisterDataType - 3 OK deregisterDataType - 1 OK deregisterNamespace - 2 OK deregisterNamespace - 1 OK deregisterServiceType OKIf you wish to get much more (and less formatted) call it with a -debug option.
You can also specify a non-default BioMoby registry using an -e (and, if needed, also a -uri option for namespace). For example, to test an official testing registry type (all as one line, without the backslashes):
run-testing-central \
-e http://mobytest.biordf.net/MOBY-Central.pl \
-uri http://mobycentral.cbr.nrc.ca:8080/MOBY/Central
Do not forget, however, that this document is only about command-line clients. Elsewhere you can find other clients: explore the Simple client from Paul Gordon, or Taverna from Tom Oinn (et al).Although it was never meant to be used for accessing BioMoby services you can use MobyCmdLineClient (described above) also. Here is how:
The MobyCmdLineClient has an option -scall that allows to call a BioMoby service. Internally, it does the following (skip this if you are not interested in internals):
run-cmdline-client \
-e <URL-of-the-wanted-service> \
-uri http://biomoby.org/ \
-call <service-name> <file-with-an-XML-input-data>
An example of such input data (for the service getDragonSimpleAnnotatedImages) is shown here (for more, go to BioMoby API page):
<?xml version="1.0" encoding="UTF-8"?>
<moby:MOBY xmlns:moby="http://www.biomoby.org/moby">
<moby:mobyContent>
<moby:mobyData moby:queryID="a1">
<moby:Simple moby:articleName="input">
<moby:Object moby:namespace="DragonDB_Allele" moby:id="cho" />
</moby:Simple>
</moby:mobyData>
</moby:mobyContent>
</moby:MOBY>
Having an XML-lize input data, you can finally use
this client to call the service, using the -scall option:
run-cmdline-client -scall <service-name> <file-with-input-XML>You can also use a -q option to remove verbose messages (especially if you wish to redirect results to a file). Another example uses the following input data (stored in a file input.xml):
<?xml version="1.0" encoding="UTF-8"?>
<moby:MOBY xmlns:moby="http://www.biomoby.org/moby">
<moby:mobyContent>
<moby:mobyData moby:queryID="a1">
<moby:Simple moby:articleName="identifier">
<moby:Object moby:namespace="NCBI_gi" moby:id="431260" />
</moby:Simple>
</moby:mobyData>
</moby:mobyContent>
</moby:MOBY>
Type
run-cmdline-client -q -scall MOBYSHoundGetGenBankff input.xml > result.xmland you will get a result (again wrapped in a BioMoby XML envelope).
Note, that the service name can be qualified by its authority name, separated by comma (useful if there are services with the same names but served by different authorities). For example, you can call the same service as above, using:
run-cmdline-client -scall MOBYSHoundGetGenBankff,www.illuminae.com input.xml