src/jalview/fts/service/uniprot/UniProtFTSRestClient.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21
  22 package jalview.fts.service.uniprot;
  23
  24 import java.net.MalformedURLException;
  25 import java.net.URL;
  26 import java.util.ArrayList;
  27 import java.util.Collection;
  28 import java.util.List;
  29 import java.util.Objects;
  30
  31 import javax.ws.rs.core.MediaType;
  32
  33 import com.sun.jersey.api.client.Client;
  34 import com.sun.jersey.api.client.ClientResponse;
  35 import com.sun.jersey.api.client.WebResource;
  36 import com.sun.jersey.api.client.config.DefaultClientConfig;
  37
  38 import jalview.bin.Cache;
  39 import jalview.bin.Console;
  40 import jalview.fts.api.FTSData;
  41 import jalview.fts.api.FTSDataColumnI;
  42 import jalview.fts.core.FTSRestClient;
  43 import jalview.fts.core.FTSRestRequest;
  44 import jalview.fts.core.FTSRestResponse;
  45 import jalview.util.ChannelProperties;
  46 import jalview.util.MessageManager;
  47 import jalview.util.Platform;
  48
  49 /*
  50  * 2022-07-20 bsoares
  51  * See https://issues.jalview.org/browse/JAL-4036
  52  * The new Uniprot API is not dissimilar to the old one, but has some important changes.
  53  * Some group names have changed slightly, some old groups have gone and there are quite a few new groups.
  54  *
  55  * Most changes are mappings of old column ids to new field ids. There are a handful of old
  56  * columns not mapped to new fields, and new fields without an old column.
  57  * [aside: not all possible columns were listed in the resources/fts/uniprot_data_columns.txt file.
  58  * These were presumably additions after the file was created]
  59  * For existing/mapped fields, the same preferences found in the resource file have been migrated to
  60  * the new file with the new field name, id and group.
  61  *
  62  * The new mapped groups and files are stored and read from resources/fts/uniprot_data_columns-2022.txt.
  63  *
  64  * There is now no "sort" query string parameter.
  65  *
  66  * See https://www.uniprot.org/help/api_queries
  67  *
  68  * SIGNIFICANT CHANGE: Pagination is no longer performed using a record offset, but with a "cursor"
  69  * query string parameter that is not really a cursor.  The value is an opaque string that is passed (or
  70  * rather a whole URL is passed) in the "Link" header of the HTTP response of the previous page.
  71  * Where such a link is passed it is put into the cursors ArrayList.
  72  * There are @Overridden methods in UniprotFTSPanel.
  73  */
  74
  75 public class UniProtFTSRestClient extends FTSRestClient
  76 {
  77   private static final String DEFAULT_UNIPROT_DOMAIN = "https://rest.uniprot.org";
  78
  79   private static final String USER_AGENT = ChannelProperties
  80           .getProperty("app_name", "Jalview") + " "
  81           + Cache.getDefault("VERSION", "Unknown") + " "
  82           + UniProtFTSRestClient.class.toString() + " help@jalview.org";
  83
  84   static
  85   {
  86     Platform.addJ2SDirectDatabaseCall(DEFAULT_UNIPROT_DOMAIN);
  87   }
  88
  89   private static UniProtFTSRestClient instance = null;
  90
  91   public final String uniprotSearchEndpoint;
  92
  93   public UniProtFTSRestClient()
  94   {
  95     super();
  96     this.clearCursors();
  97     uniprotSearchEndpoint = Cache.getDefault("UNIPROT_2022_DOMAIN",
  98             DEFAULT_UNIPROT_DOMAIN) + "/uniprotkb/search";
  99   }
 100
 101   @SuppressWarnings("unchecked")
 102   @Override
 103   public FTSRestResponse executeRequest(FTSRestRequest uniprotRestRequest)
 104           throws Exception
 105   {
 106     return executeRequest(uniprotRestRequest, null);
 107   }
 108
 109   public FTSRestResponse executeRequest(FTSRestRequest uniprotRestRequest,
 110           String cursor) throws Exception
 111   {
 112     try
 113     {
 114       String wantedFields = getDataColumnsFieldsAsCommaDelimitedString(
 115               uniprotRestRequest.getWantedFields());
 116       int responseSize = (uniprotRestRequest.getResponseSize() == 0)
 117               ? getDefaultResponsePageSize()
 118               : uniprotRestRequest.getResponseSize();
 119
 120       int offSet = uniprotRestRequest.getOffSet();
 121       String query;
 122       if (isAdvancedQuery(uniprotRestRequest.getSearchTerm()))
 123       {
 124         query = uniprotRestRequest.getSearchTerm();
 125       }
 126       else
 127       {
 128         query = uniprotRestRequest.getFieldToSearchBy().equalsIgnoreCase(
 129                 "Search All") ? uniprotRestRequest.getSearchTerm()
 130                         // + " or mnemonic:"
 131                         // + uniprotRestRequest.getSearchTerm()
 132                         : uniprotRestRequest.getFieldToSearchBy() + ":"
 133                                 + uniprotRestRequest.getSearchTerm();
 134       }
 135
 136       // BH 2018 the trick here is to coerce the classes in Javascript to be
 137       // different from the ones in Java yet still allow this to be correct for
 138       // Java
 139       Client client;
 140       Class<ClientResponse> clientResponseClass;
 141       if (Platform.isJS())
 142       {
 143         // JavaScript only -- coerce types to Java types for Java
 144         client = (Client) (Object) new jalview.javascript.web.Client();
 145         clientResponseClass = (Class<ClientResponse>) (Object) jalview.javascript.web.ClientResponse.class;
 146       }
 147       else
 148       /**
 149        * Java only
 150        *
 151        * @j2sIgnore
 152        */
 153       {
 154         // Java only
 155         client = Client.create(new DefaultClientConfig());
 156         clientResponseClass = ClientResponse.class;
 157       }
 158
 159       WebResource webResource = null;
 160       webResource = client.resource(uniprotSearchEndpoint)
 161               .queryParam("format", "tsv")
 162               .queryParam("fields", wantedFields)
 163               .queryParam("size", String.valueOf(responseSize))
 164               /* 2022 new api has no "sort"
 165                * .queryParam("sort", "score")
 166                */
 167               .queryParam("query", query);
 168       if (offSet != 0 && cursor != null && cursor.length() > 0)
 169       // 2022 new api does not do pagination with an offset, it requires a
 170       // "cursor" parameter with a key (given for the next page).
 171       // (see https://www.uniprot.org/help/pagination)
 172       {
 173         webResource = webResource.queryParam("cursor", cursor);
 174       }
 175       Console.debug(
 176               "Uniprot FTS Request: " + webResource.getURI().toString());
 177       // Execute the REST request
 178       WebResource.Builder wrBuilder = webResource
 179               .accept(MediaType.TEXT_PLAIN);
 180       if (!Platform.isJS())
 181       /**
 182        * Java only
 183        *
 184        * @j2sIgnore
 185        */
 186       {
 187         wrBuilder.header("User-Agent", USER_AGENT);
 188       }
 189       ClientResponse clientResponse = wrBuilder.get(clientResponseClass);
 190
 191       if (!Platform.isJS())
 192       /**
 193        * Java only
 194        *
 195        * @j2sIgnore
 196        */
 197       {
 198         if (clientResponse.getHeaders().containsKey("Link"))
 199         {
 200           // extract the URL from the 'Link: <URL>; ref="stuff"' header
 201           String linkHeader = clientResponse.getHeaders().get("Link")
 202                   .get(0);
 203           if (linkHeader.indexOf("<") > -1)
 204           {
 205             String temp = linkHeader.substring(linkHeader.indexOf("<") + 1);
 206             if (temp.indexOf(">") > -1)
 207             {
 208               String nextUrl = temp.substring(0, temp.indexOf(">"));
 209               // then get the cursor value from the query string parameters
 210               String nextCursor = getQueryParam("cursor", nextUrl);
 211               setCursor(cursorPage + 1, nextCursor);
 212             }
 213           }
 214         }
 215       }
 216
 217       String uniProtTabDelimittedResponseString = clientResponse
 218               .getEntity(String.class);
 219       // Make redundant objects eligible for garbage collection to conserve
 220       // memory
 221       // jalview.bin.Console.outPrintln(">>>>> response : "
 222       // + uniProtTabDelimittedResponseString);
 223       if (clientResponse.getStatus() != 200)
 224       {
 225         String errorMessage = getMessageByHTTPStatusCode(
 226                 clientResponse.getStatus(), "Uniprot");
 227         throw new Exception(errorMessage);
 228
 229       }
 230       // new Uniprot API is not including a "X-Total-Results" header when there
 231       // are 0 results
 232       List<String> resultsHeaders = clientResponse.getHeaders()
 233               .get("X-Total-Results");
 234       int xTotalResults = 0;
 235       if (Platform.isJS())
 236       {
 237         xTotalResults = 1;
 238       }
 239       else if (resultsHeaders != null && resultsHeaders.size() >= 1)
 240       {
 241         xTotalResults = Integer.valueOf(resultsHeaders.get(0));
 242       }
 243       clientResponse = null;
 244       client = null;
 245       return parseUniprotResponse(uniProtTabDelimittedResponseString,
 246               uniprotRestRequest, xTotalResults);
 247     } catch (Exception e)
 248     {
 249       Console.warn("Problem with the query: " + e.getMessage());
 250       Console.debug("Exception stacktrace:", e);
 251       String exceptionMsg = e.getMessage();
 252       if (exceptionMsg.contains("SocketException"))
 253       {
 254         // No internet connection
 255         throw new Exception(MessageManager.getString(
 256                 "exception.unable_to_detect_internet_connection"));
 257       }
 258       else if (exceptionMsg.contains("UnknownHostException"))
 259       {
 260         // The server 'http://www.uniprot.org' is unreachable
 261         throw new Exception(MessageManager.formatMessage(
 262                 "exception.fts_server_unreachable", "Uniprot"));
 263       }
 264       else
 265       {
 266         throw e;
 267       }
 268     }
 269   }
 270
 271   public boolean isAdvancedQuery(String query)
 272   {
 273     if (query.contains(" AND ") || query.contains(" OR ")
 274             || query.contains(" NOT ") || query.contains(" ! ")
 275             || query.contains(" || ") || query.contains(" && ")
 276             || query.contains(":") || query.contains("-"))
 277     {
 278       return true;
 279     }
 280     return false;
 281   }
 282
 283   public FTSRestResponse parseUniprotResponse(
 284           String uniProtTabDelimittedResponseString,
 285           FTSRestRequest uniprotRestRequest, int xTotalResults)
 286   {
 287     FTSRestResponse searchResult = new FTSRestResponse();
 288     List<FTSData> result = null;
 289     if (uniProtTabDelimittedResponseString == null
 290             || uniProtTabDelimittedResponseString.trim().isEmpty())
 291     {
 292       searchResult.setNumberOfItemsFound(0);
 293       return searchResult;
 294     }
 295     String[] foundDataRow = uniProtTabDelimittedResponseString.split("\n");
 296     if (foundDataRow != null && foundDataRow.length > 0)
 297     {
 298       result = new ArrayList<>();
 299       boolean firstRow = true;
 300       for (String dataRow : foundDataRow)
 301       {
 302         // The first data row is usually the header data. This should be
 303         // filtered out from the rest of the data See: JAL-2485
 304         if (firstRow)
 305         {
 306           firstRow = false;
 307           continue;
 308         }
 309         // jalview.bin.Console.outPrintln(dataRow);
 310         result.add(getFTSData(dataRow, uniprotRestRequest));
 311       }
 312       searchResult.setNumberOfItemsFound(xTotalResults);
 313       searchResult.setSearchSummary(result);
 314     }
 315     return searchResult;
 316   }
 317
 318   // /**
 319   // * Takes a collection of FTSDataColumnI and converts its 'code' values into
 320   // a
 321   // * tab delimited string.
 322   // *
 323   // * @param dataColumnFields
 324   // * the collection of FTSDataColumnI to process
 325   // * @return the generated comma delimited string from the supplied
 326   // * FTSDataColumnI collection
 327   // */
 328   // private String getDataColumnsFieldsAsTabDelimitedString(
 329   // Collection<FTSDataColumnI> dataColumnFields)
 330   // {
 331   // String result = "";
 332   // if (dataColumnFields != null && !dataColumnFields.isEmpty())
 333   // {
 334   // StringBuilder returnedFields = new StringBuilder();
 335   // for (FTSDataColumnI field : dataColumnFields)
 336   // {
 337   // if (field.getName().equalsIgnoreCase("Uniprot Id"))
 338   // {
 339   // returnedFields.append("\t").append("Entry");
 340   // }
 341   // else
 342   // {
 343   // returnedFields.append("\t").append(field.getName());
 344   // }
 345   // }
 346   // returnedFields.deleteCharAt(0);
 347   // result = returnedFields.toString();
 348   // }
 349   // return result;
 350   // }
 351
 352   public static FTSData getFTSData(String tabDelimittedDataStr,
 353           FTSRestRequest request)
 354   {
 355     String primaryKey = null;
 356
 357     Object[] summaryRowData;
 358
 359     Collection<FTSDataColumnI> diplayFields = request.getWantedFields();
 360     int colCounter = 0;
 361     summaryRowData = new Object[diplayFields.size()];
 362     String[] columns = tabDelimittedDataStr.split("\t");
 363     for (FTSDataColumnI field : diplayFields)
 364     {
 365       try
 366       {
 367         String fieldData = columns[colCounter];
 368         if (field.isPrimaryKeyColumn())
 369         {
 370           primaryKey = fieldData;
 371           summaryRowData[colCounter++] = primaryKey;
 372         }
 373         else if (fieldData == null || fieldData.isEmpty())
 374         {
 375           summaryRowData[colCounter++] = null;
 376         }
 377         else
 378         {
 379           try
 380           {
 381             summaryRowData[colCounter++] = (field.getDataType()
 382                     .getDataTypeClass() == Integer.class)
 383                             ? Integer.valueOf(fieldData.replace(",", ""))
 384                             : (field.getDataType()
 385                                     .getDataTypeClass() == Double.class)
 386                                             ? Double.valueOf(fieldData)
 387                                             : fieldData;
 388           } catch (Exception e)
 389           {
 390             e.printStackTrace();
 391             jalview.bin.Console.outPrintln("offending value:" + fieldData);
 392           }
 393         }
 394       } catch (Exception e)
 395       {
 396         // e.printStackTrace();
 397       }
 398     }
 399
 400     final String primaryKey1 = primaryKey;
 401
 402     final Object[] summaryRowData1 = summaryRowData;
 403     return new FTSData()
 404     {
 405       @Override
 406       public Object[] getSummaryData()
 407       {
 408         return summaryRowData1;
 409       }
 410
 411       @Override
 412       public Object getPrimaryKey()
 413       {
 414         return primaryKey1;
 415       }
 416
 417       /**
 418        * Returns a string representation of this object;
 419        */
 420       @Override
 421       public String toString()
 422       {
 423         StringBuilder summaryFieldValues = new StringBuilder();
 424         for (Object summaryField : summaryRowData1)
 425         {
 426           summaryFieldValues.append(
 427                   summaryField == null ? " " : summaryField.toString())
 428                   .append("\t");
 429         }
 430         return summaryFieldValues.toString();
 431       }
 432
 433       /**
 434        * Returns hash code value for this object
 435        */
 436       @Override
 437       public int hashCode()
 438       {
 439         return Objects.hash(primaryKey1, this.toString());
 440       }
 441
 442       @Override
 443       public boolean equals(Object that)
 444       {
 445         return this.toString().equals(that.toString());
 446       }
 447     };
 448   }
 449
 450   public static UniProtFTSRestClient getInstance()
 451   {
 452     if (instance == null)
 453     {
 454       instance = new UniProtFTSRestClient();
 455     }
 456     return instance;
 457   }
 458
 459   @Override
 460   public String getColumnDataConfigFileName()
 461   {
 462     return "/fts/uniprot_data_columns-2022.txt";
 463   }
 464
 465   /* 2022-07-20 bsoares
 466    * used for the new API "cursor" pagination. See https://www.uniprot.org/help/pagination
 467    */
 468   private ArrayList<String> cursors;
 469
 470   private int cursorPage = 0;
 471
 472   protected int getCursorPage()
 473   {
 474     return cursorPage;
 475   }
 476
 477   protected void setCursorPage(int i)
 478   {
 479     cursorPage = i;
 480   }
 481
 482   protected void setPrevCursorPage()
 483   {
 484     if (cursorPage > 0)
 485       cursorPage--;
 486   }
 487
 488   protected void setNextCursorPage()
 489   {
 490     cursorPage++;
 491   }
 492
 493   protected void clearCursors()
 494   {
 495     cursors = new ArrayList(10);
 496   }
 497
 498   protected String getCursor(int i)
 499   {
 500     return cursors.get(i);
 501   }
 502
 503   protected String getNextCursor()
 504   {
 505     if (cursors.size() < cursorPage + 2)
 506       return null;
 507     return cursors.get(cursorPage + 1);
 508   }
 509
 510   protected String getPrevCursor()
 511   {
 512     if (cursorPage == 0)
 513       return null;
 514     return cursors.get(cursorPage - 1);
 515   }
 516
 517   protected void setCursor(int i, String c)
 518   {
 519     cursors.ensureCapacity(i + 1);
 520     while (cursors.size() <= i)
 521     {
 522       cursors.add(null);
 523     }
 524     cursors.set(i, c);
 525     Console.debug(
 526             "Set UniprotFRSRestClient cursors[" + i + "] to '" + c + "'");
 527     // cursors.add(c);
 528   }
 529
 530   public static String getQueryParam(String param, String u)
 531   {
 532     if (param == null || u == null)
 533       return null;
 534     try
 535     {
 536       URL url = new URL(u);
 537       String[] kevs = url.getQuery().split("&");
 538       for (int j = 0; j < kevs.length; j++)
 539       {
 540         String[] kev = kevs[j].split("=", 2);
 541         if (param.equals(kev[0]))
 542         {
 543           return kev[1];
 544         }
 545       }
 546     } catch (MalformedURLException e)
 547     {
 548       Console.warn("Could not obtain next page 'cursor' value from 'u");
 549     }
 550     return null;
 551   }
 552 }