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