Command-line clients

There is a growing number of the command-line clients in jMoby. They serve two purposes: first, they are useful per-se, and second, their source code can be used as templates for writing your own clients.

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:

That's why the examples given below do not use any path.

Clients exploring BioMoby registry
Clients accessing BioMoby services

Clients exploring BioMoby registry



This client is the most complex one allowing to use all possible features of a BioMoby registry. By default, it goes to the Mark Wilkinson's BioMoby registry in Canada but it can be overwritten using options -e (with an endpoint) and -uri (with a namespace).

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.

Getting things from the registry

The simplest are the list functions to get various entities:
   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 types
In 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, type (note that comma there):
   run-cmdline-client -fn ,
At the moment of writing this document, the (quite impressive) result is:
In 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_Blast
returns three services:
If we limit it also by authority
   run-cmdline-client -fs-type NCBI_Blast -fs-auth
we get just one service:
All 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:

Last but not least, you can explore the ontology trees - the relationships between service and data types. Print all parents names of given service type:
   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> HAS
For example, after invoking:
   run-cmdline-client -ot NCBI_Blast
you get back:
   Service type 'NCBI_Blast' is-a:
Or, by invoking:
   run-cmdline-client -od DNASequence
you get back:
   Relationships of data type 'DNASequence':

Giving things to the registry

The MobyCmdLineClient also allows to register various entities in a BioMoby registry. The registration of complex entities (such as a service) may be quite cumbersome - and the command-line syntax would be so complex that MobyCmdLineClient uses some additional files. As said above, for such cases you may consider to use some web-based, form-oriented tool.

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:

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 \
      -uri \
      -rd-name ColouredString \
      -rd-desc 'A string representing a colour' \
      -rd-auth \
      -rd-email \
      -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 \
      -uri \
      -data ColouredString
you get back:
   Data type 'ColouredString':
   Desc:    A string representing a colour
   Children (only those registered here):
      R (HASA) =>
      G (HASA) =>
      B (HASA) =>
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/   (3)
   file.2 = data/   (4)
   file.3 = 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/

   name = simple 1 in collection
   datatype = TestingDataType4
   namespaces.1 = TestingNamespace
File data/
   name = simple 2 in collection
   datatype = TestingDataType2
   namespaces = TestingNamespace2
File data/
   name = simple 3 in collection
   datatype = TestingDataType3
   namespaces = TestingNamespace
If 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):
     <Service authURI='' serviceName='getAlleleFreq'>
         <Simple articleName='snpLSID'>
         <Simple articleName='panelLSID'>
         <Simple articleName=''>
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:

   name = snpLSID
   datatype = Object
   namespaces.1 = Haplotyping_Study
File in-allele-2 has this:
   name = panelLSID
   datatype = Object
   namespaces.1 = Haplotyping_Study
Then the command line (going again to a testing registry, not to a production one) looks like this:
   run-cmdline-client \   
      -e  \
      -uri                 \
      -rs-name Testing_getAlleleFreq                                       \
      -rs-type Retrieval                                                   \
      -rs-categ moby                                                       \
      -rs-desc  'a testing get allele frequency'                           \
      -rs-auth                                    \
      -rs-email                                           \
      -rs-url http://chimay/cgi-bin/work_in_progress/hapmap_dispatcher.cgi \
      -rs-main 0                                                           \
      -rs-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  \
      -uri                 \
      -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.

Removing things from the registry

Sometimes things need to be unregister. Use the following options:
   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 name
For 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 \
      -uri                \
      -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

And the rest

The (almost) last thing the MobyCmdLineClient does is to call any method with any input data. It is done with an option -call that has up to two parameters. The first one is a method name to be called, the (optional) second one is input data. If the second parameter is an existing file name then the contents of that file is sent as input data.

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 retrieveServiceNames
And you get back a raw XML output:
      <serviceName name='ASA' authURI=''/>
      <serviceName name='Automat' authURI=''/>
      <serviceName name='BasicBuilder' authURI=''/>
      <serviceName name='BlastFastaVsArabiProteincoding' authURI=''/>
Here is an another example taking an input directly on the command line:
   run-cmdline-client \
      -call retrieveObjectDefinition \
It returns a raw data type definition of a DNASequence:
      <Description><![CDATA[Lightweight representation a DNA sequence]]></Description>
      <Relationship relationshipType=''>
         <objectType articleName=''></objectType>
Note that it does the same (except that both input and output are directly in XML) as:
   run-cmdline-client -data DNASequence
As 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.xml
One 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.sql
Another 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)


The BioMoby API does not directly support access to more entities in one request.
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 types
All 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 -details
   Desc:    Plaintext Blast report from NCBI Blast software
   Children (only those registered here):

   Desc:    Pubmed article in MEDLINE display format
   Children (only those registered here):

   ... (and many more)
Note that there are inconsistencies what is considered a name. For services:
   run-digest-client -s
returns simple names:
and for data types:
   run-digest-client -d
returns names encoded as LSIDs:
The inconsistency is in the current implementation of the BioMoby registry.


The users that want to explore all entities from a BioMoby registry (e.g. the programs showing relationships between data type or between services) may benefit, especially in the time of writing and testing their software, from having all BioMoby entities cached in a local file-system. They can use the command-line CacheRegistryClient to create and/or remove such cache.

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.


This is a one-purpose client accessing a BioMoby registry and calling most of its methods in order to test their availability. Start it by:
and 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              OK
If 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 \

Clients accessing BioMoby services

Well, they do not exist yet. See plans in the To Do document.
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):

  1. It calls the default BioMoby registry to find a URL of the wanted service.

  2. It uses URI - a mandatory namespace for BioMoby services.

  3. It uses a raw SOAP invocation using a -call option. Therefore, once you have a service URL and XML input data (more about it below), you can achieve the same as -scall yourself by calling (backslashes are just for easy reading):
           run-cmdline-client \
              -e <URL-of-the-wanted-service> \
              -uri \
              -call <service-name> <file-with-an-XML-input-data>
In order to invoke any service (using either -scall or -call) you need to have an input data in an XML format. The MobyCmdLineClient does not help you here. You simply must know how to code your data into a BioMoby XML envelope. This is, of course, the main limitation of this way to invoke a BioMoby service (and several people are working to rectify this).

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="">
       <moby:mobyData moby:queryID="a1">
         <moby:Simple moby:articleName="input">
           <moby:Object moby:namespace="DragonDB_Allele" moby:id="cho" />
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="">
       <moby:mobyData moby:queryID="a1">
         <moby:Simple moby:articleName="identifier">
           <moby:Object moby:namespace="NCBI_gi" moby:id="431260" />
   run-cmdline-client -q -scall MOBYSHoundGetGenBankff input.xml > result.xml
and 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, input.xml

Martin Senger
Last modified: Tue May 17 15:38:07 2005