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 /*
  23  * 2022-07-20 bsoares
  24  * See https://issues.jalview.org/browse/JAL-4036
  25  * The new Uniprot API is not dissimilar to the old one, but has some important changes.
  26  * Some group names have changed slightly, some old groups have gone and there are quite a few new groups.
  27  *
  28  * Most changes are mappings of old column ids to new field ids. There are a handful of old
  29  * columns not mapped to new fields, and new fields without an old column.
  30  * [aside: not all possible columns were listed in the resources/fts/uniprot_data_columns.txt file.
  31  * These were presumably additions after the file was created]
  32  * For existing/mapped fields, the same preferences found in the resource file have been migrated to
  33  * the new file with the new field name, id and group.
  34  *
  35  * The new mapped groups and files are stored and read from resources/fts/uniprot_data_columns-2022.txt.
  36  *
  37  * There is now no "sort" query string parameter.
  38  *
  39  * See https://www.uniprot.org/help/api_queries
  40  *
  41  * SIGNIFICANT CHANGE: Pagination is no longer performed using a record offset, but with a "cursor"
  42  * query string parameter that is not really a cursor.  The value is an opaque string that is passed (or
  43  * rather a whole URL is passed) in the "Link" header of the HTTP response of the previous page.
  44  * Where such a link is passed it is put into the cursors ArrayList.
  45  * There are @Overridden methods in UniprotFTSPanel.
  46  */
  47
  48 package jalview.fts.service.uniprot;
  49
  50 import java.lang.invoke.MethodHandles;
  51 import java.net.MalformedURLException;
  52 import java.net.URL;
  53 import java.util.ArrayList;
  54 import java.util.Collection;
  55 import java.util.List;
  56 import java.util.Objects;
  57
  58 import javax.ws.rs.core.MediaType;
  59
  60 import com.sun.jersey.api.client.Client;
  61 import com.sun.jersey.api.client.ClientResponse;
  62 import com.sun.jersey.api.client.WebResource;
  63 import com.sun.jersey.api.client.config.DefaultClientConfig;
  64
  65 import jalview.bin.Cache;
  66 import jalview.bin.Console;
  67 import jalview.fts.api.FTSData;
  68 import jalview.fts.api.FTSDataColumnI;
  69 import jalview.fts.core.FTSRestClient;
  70 import jalview.fts.core.FTSRestRequest;
  71 import jalview.fts.core.FTSRestResponse;
  72 import jalview.util.ChannelProperties;
  73 import jalview.util.MessageManager;
  74 import jalview.util.Platform;
  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_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.debug("Exception caught from response", 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         // System.out.println(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             System.out.println("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       // TODO Auto-generated catch block
 549       e.printStackTrace();
 550     }
 551     return null;
 552   }
 553 }