forester/java/src/org/forester/ws/wabi/TxSearch.java

   1 // $Id:
   2 // forester -- software libraries and applications
   3 // for genomics and evolutionary biology research.
   4 //
   5 // Copyright (C) 2010 Christian M Zmasek
   6 // Copyright (C) 2010 Sanford-Burnham Medical Research Institute
   7 // All rights reserved
   8 //
   9 // This library is free software; you can redistribute it and/or
  10 // modify it under the terms of the GNU Lesser General Public
  11 // License as published by the Free Software Foundation; either
  12 // version 2.1 of the License, or (at your option) any later version.
  13 //
  14 // This library is distributed in the hope that it will be useful,
  15 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17 // Lesser General Public License for more details.
  18 //
  19 // You should have received a copy of the GNU Lesser General Public
  20 // License along with this library; if not, write to the Free Software
  21 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  22 //
  23 // Contact: phylosoft @ gmail . com
  24 // WWW: https://sites.google.com/site/cmzmasek/home/software/forester
  25
  26 package org.forester.ws.wabi;
  27
  28 import java.io.IOException;
  29 import java.io.UnsupportedEncodingException;
  30 import java.util.ArrayList;
  31 import java.util.List;
  32
  33 /**
  34  *
  35  * This is to access the Web API for Biology (WABI) at DDBJ.
  36  * See: http://xml.nig.ac.jp/
  37  *
  38  * Service Description:
  39  * TXSearch is a retrieval system for a Taxonomy Database which
  40  * was unified by DDBJ, GenBank and EMBL, which is developed by DDBJ.
  41  * See: http://xml.nig.ac.jp/wabi/Method?serviceName=TxSearch&mode=methodList
  42  *
  43  */
  44 public final class TxSearch {
  45
  46     private static final String TAXONOMIC_RANK                         = "Taxonomic rank: ";
  47     private static final String FULL_LINEAGE                           = "Full lineage: ";
  48     private static final String SEARCH_LINEAGE_QUERY_PARAM_NAME        = "query";
  49     private static final String SEARCH_LINEAGE_RANKS_PARAM_NAME        = "ranks";
  50     private static final String SEARCH_LINEAGE_SUPERKINGDOM_PARAM_NAME = "superkingdom";
  51     private final static String GET_TX_ID_METHOD_NAME                  = "getTxId";
  52     private final static String GET_TX_NAME_METHOD_NAME                = "getTxName";
  53     private final static String SEARCH_SIMPLE_METHOD_NAME              = "searchSimple";
  54     private final static String TX_SEARCH_SERVICE_NAME                 = "TxSearch";
  55     private final static String TX_NAME_PARAM_NAME                     = "tx_Name";
  56     private final static String TX_ID_PARAM_NAME                       = "tx_Id";
  57     private final static String SEARCH_LINEAGE_NAME_METHOD_NAME        = "searchLineage";
  58     private final static String SEARCH_PARAM_METHOD_NAME               = "searchParam";
  59
  60     public static String[] getLineage( final String result ) throws IOException {
  61         String[] lineage = null;
  62         for( String line : result.split( RestUtil.LINE_SEPARATOR ) ) {
  63             line = line.trim();
  64             if ( line.startsWith( FULL_LINEAGE ) ) {
  65                 if ( lineage != null ) {
  66                     throw new IOException( "search result is not unique" );
  67                 }
  68                 lineage = line.substring( FULL_LINEAGE.length() ).split( ";" );
  69             }
  70         }
  71         return lineage;
  72     }
  73
  74     public static String getTaxonomicRank( final String result ) throws IOException {
  75         String rank = null;
  76         for( String line : result.split( RestUtil.LINE_SEPARATOR ) ) {
  77             line = line.trim();
  78             if ( line.startsWith( TAXONOMIC_RANK ) ) {
  79                 if ( rank != null ) {
  80                     throw new IOException( "search result is not unique" );
  81                 }
  82                 rank = line.substring( TAXONOMIC_RANK.length() ).trim();
  83             }
  84         }
  85         return rank;
  86     }
  87
  88     public static String getTxId( final String tx_name ) throws IOException {
  89         return RestUtil.getResult( TX_SEARCH_SERVICE_NAME,
  90                                    GET_TX_ID_METHOD_NAME,
  91                                    TX_NAME_PARAM_NAME + "=" + RestUtil.encode( tx_name ) ).trim();
  92     }
  93
  94     public static String getTxName( final String tx_id ) throws IOException {
  95         return RestUtil.getResult( TX_SEARCH_SERVICE_NAME,
  96                                    GET_TX_NAME_METHOD_NAME,
  97                                    TX_ID_PARAM_NAME + "=" + RestUtil.encode( tx_id ) ).trim();
  98     }
  99
 100     public static void main( final String[] args ) throws IOException {
 101         String result = "";
 102         try {
 103             result = searchSimple( "SAMSA" );
 104         }
 105         catch ( final IOException e ) {
 106             e.printStackTrace();
 107         }
 108         System.out.println( result );
 109         System.out.println( "---------------" );
 110         try {
 111             result = searchSimple( "nematostella" );
 112         }
 113         catch ( final IOException e ) {
 114             e.printStackTrace();
 115         }
 116         System.out.println( result );
 117         final String[] lineage = getLineage( result );
 118         for( final String element : lineage ) {
 119             System.out.println( element );
 120         }
 121         System.out.println( getTaxonomicRank( result ) );
 122         System.out.println( "---------------" );
 123         try {
 124             result = getTxId( "nematostella" );
 125         }
 126         catch ( final IOException e ) {
 127             e.printStackTrace();
 128         }
 129         System.out.println( result );
 130         System.out.println( "---------------" );
 131         try {
 132             result = getTxName( "45350" );
 133         }
 134         catch ( final IOException e ) {
 135             e.printStackTrace();
 136         }
 137         System.out.println( result );
 138         System.out.println( "---------------" );
 139         final List<String> queries = new ArrayList<String>();
 140         queries.add( "Campylobacter coli" );
 141         queries.add( "Escherichia coli" );
 142         queries.add( "Arabidopsis" );
 143         queries.add( "Trichoplax" );
 144         queries.add( "Samanea saman" );
 145         queries.add( "Kluyveromyces marxianus" );
 146         queries.add( "Bacillus subtilis subsp. subtilis str. N170" );
 147         queries.add( "Bornavirus parrot/PDD/2008" );
 148         final List<RANKS> ranks = new ArrayList<RANKS>();
 149         //        ranks.add( RANKS.SUPERKINGDOM );
 150         //        ranks.add( RANKS.KINGDOM );
 151         //        ranks.add( RANKS.FAMILY );
 152         //        ranks.add( RANKS.GENUS );
 153         ranks.add( RANKS.ALL );
 154         try {
 155             result = searchLineage( queries, ranks );
 156         }
 157         catch ( final IOException e ) {
 158             e.printStackTrace();
 159         }
 160         System.out.println( result );
 161         System.out.println( "---------------" );
 162         try {
 163             result = searchParam( "Homo sapiens", TAX_NAME_CLASS.ALL, TAX_RANK.SPECIES, 10, true );
 164         }
 165         catch ( final IOException e ) {
 166             e.printStackTrace();
 167         }
 168         System.out.println( result );
 169         System.out.println( "---------------" );
 170         try {
 171             result = searchParam( "Samanea saman", TAX_NAME_CLASS.SCIENTIFIC_NAME, TAX_RANK.ALL, 10, true );
 172         }
 173         catch ( final IOException e ) {
 174             e.printStackTrace();
 175         }
 176         System.out.println( result );
 177         System.out.println( "---------------" );
 178         try {
 179             result = searchParam( "cow", TAX_NAME_CLASS.COMMON_NAME, TAX_RANK.ALL, 10, true );
 180         }
 181         catch ( final IOException e ) {
 182             e.printStackTrace();
 183         }
 184         System.out.println( result );
 185         System.out.println( "---------------" );
 186         try {
 187             result = searchParam( "Helicogloea lagerheimii", TAX_NAME_CLASS.SCIENTIFIC_NAME, TAX_RANK.ALL, 10, true );
 188         }
 189         catch ( final IOException e ) {
 190             e.printStackTrace();
 191         }
 192         System.out.println( result );
 193         System.out.println( "---------------" );
 194         try {
 195             result = searchParam( "Cronartium ribicola", TAX_NAME_CLASS.SCIENTIFIC_NAME, TAX_RANK.ALL, 10, true );
 196         }
 197         catch ( final IOException e ) {
 198             e.printStackTrace();
 199         }
 200         System.out.println( result );
 201         System.out.println( "---------------" );
 202         try {
 203             result = searchParam( "Peridermium harknessii", TAX_NAME_CLASS.SCIENTIFIC_NAME, TAX_RANK.ALL, 10, true );
 204         }
 205         catch ( final IOException e ) {
 206             e.printStackTrace();
 207         }
 208         System.out.println( result );
 209         System.out.println( "---------------" );
 210         try {
 211             result = searchParam( "Eukaryota", TAX_NAME_CLASS.SCIENTIFIC_NAME, TAX_RANK.ALL, 10, true );
 212         }
 213         catch ( final IOException e ) {
 214             e.printStackTrace();
 215         }
 216         System.out.println( result );
 217     }
 218
 219     private static String ranksAsString( final List<RANKS> l ) throws UnsupportedEncodingException {
 220         final StringBuffer sb = new StringBuffer();
 221         for( final RANKS r : l ) {
 222             if ( sb.length() > 0 ) {
 223                 sb.append( RestUtil.LIST_SEPARATOR );
 224             }
 225             sb.append( RestUtil.encode( r.toString() ) );
 226         }
 227         return sb.toString();
 228     }
 229
 230     public static String searchLineage( final List<String> queries, final List<RANKS> ranks ) throws IOException {
 231         return searchLineage( queries, ranks, "" );
 232     }
 233
 234     public static String searchLineage( final List<String> queries, final List<RANKS> ranks, final String superkingdom )
 235             throws IOException {
 236         return RestUtil.getResult( TX_SEARCH_SERVICE_NAME,
 237                                    SEARCH_LINEAGE_NAME_METHOD_NAME,
 238                                    SEARCH_LINEAGE_QUERY_PARAM_NAME + "=" + RestUtil.listAsString( queries ) + "&"
 239                                            + SEARCH_LINEAGE_RANKS_PARAM_NAME + "=" + ranksAsString( ranks ) + "&"
 240                                            + SEARCH_LINEAGE_SUPERKINGDOM_PARAM_NAME + "="
 241                                            + RestUtil.encode( superkingdom ) ).trim();
 242     }
 243
 244     public static String searchParam( final String tx_name,
 245                                       final TAX_NAME_CLASS tx_name_class,
 246                                       final TAX_RANK tx_rank,
 247                                       int tx_rmax,
 248                                       final boolean as_scientific_name ) throws IOException {
 249         String as_scientific_name_str = "no";
 250         if ( as_scientific_name ) {
 251             as_scientific_name_str = "yes";
 252         }
 253         if ( tx_rmax < 1 ) {
 254             tx_rmax = 1;
 255         }
 256         return RestUtil.getResult( TX_SEARCH_SERVICE_NAME,
 257                                    SEARCH_PARAM_METHOD_NAME,
 258                                    TX_NAME_PARAM_NAME + "=" + RestUtil.encode( tx_name ) + "&tx_Clas="
 259                                            + RestUtil.encode( tx_name_class.toString() ) + "&tx_Rank="
 260                                            + RestUtil.encode( tx_rank.toString() ) + "&tx_Rmax=" + tx_rmax
 261                                            + "&tx_Dcls=" + as_scientific_name_str ).trim();
 262     }
 263
 264     public static String searchSimple( final String tx_name ) throws IOException {
 265         return RestUtil.getResult( TX_SEARCH_SERVICE_NAME,
 266                                    SEARCH_SIMPLE_METHOD_NAME,
 267                                    TX_NAME_PARAM_NAME + "=" + RestUtil.encode( tx_name ) ).trim();
 268     }
 269
 270     public enum RANKS {
 271         ALL( "all" ),
 272         SUPERKINGDOM( "superkingdom" ),
 273         KINGDOM( "kingdom" ),
 274         SUBKINGDOM( "subkingdom" ),
 275         SUPERPHYLUM( "superphylum" ),
 276         PHYLUM( "phylum" ),
 277         SUBPHYLUM( "subphylum" ),
 278         SUPERCLASS( "superclass" ),
 279         CLASS( "class" ),
 280         SUBCLASS( "subclass" ),
 281         INFRACLASS( "infraclass" ),
 282         SUPERORDER( "superorder" ),
 283         ORDER( "order" ),
 284         SUBORDER( "suborder" ),
 285         INFRAORDER( "infraorder" ),
 286         PARVORDER( "parvorder" ),
 287         SUPERFAMILY( "superfamily" ),
 288         FAMILY( "family" ),
 289         SUBFAMILY( "subfamily" ),
 290         TRIBE( "tribe" ),
 291         SUBTRIBE( "subtribe" ),
 292         GENUS( "genus" ),
 293         SPECIES( "species" );
 294
 295         private final String _str;
 296
 297         private RANKS( final String name ) {
 298             _str = name;
 299         }
 300
 301         @Override
 302         public String toString() {
 303             return _str;
 304         }
 305     }
 306
 307     public enum TAX_NAME_CLASS {
 308         ALL( "all" ),
 309         SCIENTIFIC_NAME( "scientific name" ),
 310         PREFFERED_COMMON_NAME( "preferred common name" ),
 311         COMMON_NAME( "common name" ),
 312         SYNONYM( "synonym" );
 313
 314         private final String _str;
 315
 316         private TAX_NAME_CLASS( final String name ) {
 317             _str = name;
 318         }
 319
 320         @Override
 321         public String toString() {
 322             return _str;
 323         }
 324     }
 325
 326     public enum TAX_RANK {
 327         ALL( "All" ),
 328         NO_RANK( "no rank" ),
 329         SUPERKINGDOM( "superkingdom" ),
 330         KINGDOM( "kingdom" ),
 331         SUBKINGDOM( "subkingdom" ),
 332         SUPERPHYLUM( "superphylum" ),
 333         PHYLUM( "phylum" ),
 334         SUBPHYLUM( "subphylum" ),
 335         SUPERCLASS( "superclass" ),
 336         CLASS( "class" ),
 337         SUBCLASS( "subclass" ),
 338         INFRACLASS( "infraclass" ),
 339         SUPERORDER( "superorder" ),
 340         ORDER( "order" ),
 341         SUBORDER( "suborder" ),
 342         INFRAORDER( "infraorder" ),
 343         PARVORDER( "parvorder" ),
 344         SUPERFAMILY( "superfamily" ),
 345         FAMILY( "family" ),
 346         SUBFAMILY( "subfamily" ),
 347         TRIBE( "tribe" ),
 348         SUBTRIBE( "subtribe" ),
 349         GENUS( "genus" ),
 350         SUBGENUS( "subgenus" ),
 351         SPECIES_GROUP( "species group" ),
 352         SPECIES_SUBGROUP( "species subgroup" ),
 353         SPECIES( "species" ),
 354         SUBSPECIES( "subspecies" ),
 355         VARIETAS( "varietas" ),
 356         FORMA( "forma" );
 357
 358         private final String _str;
 359
 360         private TAX_RANK( final String name ) {
 361             _str = name;
 362         }
 363
 364         @Override
 365         public String toString() {
 366             return _str;
 367         }
 368     }
 369 }