src/jalview/ws/dbsources/PDBRestClient.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 package jalview.ws.dbsources;
  22
  23 import jalview.util.MessageManager;
  24 import jalview.ws.uimodel.PDBRestRequest;
  25 import jalview.ws.uimodel.PDBRestResponse;
  26 import jalview.ws.uimodel.PDBRestResponse.PDBResponseSummary;
  27
  28 import java.util.ArrayList;
  29 import java.util.Collection;
  30 import java.util.Iterator;
  31 import java.util.List;
  32
  33 import javax.ws.rs.core.MediaType;
  34
  35 import org.json.simple.JSONArray;
  36 import org.json.simple.JSONObject;
  37 import org.json.simple.parser.JSONParser;
  38 import org.json.simple.parser.ParseException;
  39
  40 import com.sun.jersey.api.client.Client;
  41 import com.sun.jersey.api.client.ClientResponse;
  42 import com.sun.jersey.api.client.WebResource;
  43 import com.sun.jersey.api.client.config.ClientConfig;
  44 import com.sun.jersey.api.client.config.DefaultClientConfig;
  45
  46 /**
  47  * A rest client for querying the Search endpoing of the PDB REST API
  48  *
  49  * @author tcnofoegbu
  50  *
  51  */
  52 public class PDBRestClient
  53 {
  54   public static final String PDB_SEARCH_ENDPOINT = "http://www.ebi.ac.uk/pdbe/search/pdb/select?";
  55
  56   private static int DEFAULT_RESPONSE_SIZE = 200;
  57
  58   /**
  59    * Takes a PDBRestRequest object and returns a response upon execution
  60    *
  61    * @param pdbRestRequest
  62    *          the PDBRestRequest instance to be processed
  63    * @return the pdbResponse object for the given request
  64    * @throws Exception
  65    */
  66   public PDBRestResponse executeRequest(PDBRestRequest pdbRestRequest)
  67           throws Exception
  68   {
  69     try
  70     {
  71       ClientConfig clientConfig = new DefaultClientConfig();
  72       Client client = Client.create(clientConfig);
  73
  74       String wantedFields = getPDBDocFieldsAsCommaDelimitedString(pdbRestRequest
  75               .getWantedFields());
  76       int responseSize = (pdbRestRequest.getResponseSize() == 0) ? DEFAULT_RESPONSE_SIZE
  77               : pdbRestRequest.getResponseSize();
  78       String sortParam = (pdbRestRequest.getFieldToSortBy() == null || pdbRestRequest
  79               .getFieldToSortBy().trim().isEmpty()) ? "" : (pdbRestRequest
  80               .getFieldToSortBy() + (pdbRestRequest.isAscending() ? " asc"
  81               : " desc"));
  82       String facetPivot = (pdbRestRequest.getFacetPivot() == null || pdbRestRequest
  83               .getFacetPivot().isEmpty()) ? "" : pdbRestRequest
  84               .getFacetPivot();
  85       String facetPivotMinCount = String.valueOf(pdbRestRequest
  86               .getFacetPivotMinCount());
  87
  88       // Build request parameters for the REST Request
  89       WebResource webResource = null;
  90       if (pdbRestRequest.isFacet())
  91       {
  92         webResource = client.resource(PDB_SEARCH_ENDPOINT)
  93                 .queryParam("wt", "json").queryParam("fl", wantedFields)
  94                 .queryParam("rows", String.valueOf(responseSize))
  95                 .queryParam("q", pdbRestRequest.getQuery())
  96                 .queryParam("sort", sortParam).queryParam("facet", "true")
  97                 .queryParam("facet.pivot", facetPivot)
  98                 .queryParam("facet.pivot.mincount", facetPivotMinCount);
  99       }
 100       else
 101       {
 102         webResource = client.resource(PDB_SEARCH_ENDPOINT)
 103                 .queryParam("wt", "json").queryParam("fl", wantedFields)
 104                 .queryParam("rows", String.valueOf(responseSize))
 105                 .queryParam("q", pdbRestRequest.getQuery())
 106                 .queryParam("sort", sortParam);
 107       }
 108       // Execute the REST request
 109       ClientResponse clientResponse = webResource.accept(
 110               MediaType.APPLICATION_JSON).get(ClientResponse.class);
 111
 112       // Get the JSON string from the response object
 113       String responseString = clientResponse.getEntity(String.class);
 114       System.out.println("query >>>>>>> " + pdbRestRequest.toString());
 115
 116       // Check the response status and report exception if one occurs
 117       if (clientResponse.getStatus() != 200)
 118       {
 119         String errorMessage = "";
 120         if (clientResponse.getStatus() == 400)
 121         {
 122           errorMessage = parseJsonExceptionString(responseString);
 123           throw new Exception(errorMessage);
 124         }
 125         else
 126         {
 127           errorMessage = getMessageByHTTPStatusCode(clientResponse
 128                   .getStatus());
 129           throw new Exception(errorMessage);
 130         }
 131       }
 132
 133       // Make redundant objects eligible for garbage collection to conserve
 134       // memory
 135       clientResponse = null;
 136       client = null;
 137
 138       // Process the response and return the result to the caller.
 139       return parsePDBJsonResponse(responseString, pdbRestRequest);
 140     } catch (Exception e)
 141     {
 142       String exceptionMsg = e.getMessage();
 143       if (exceptionMsg.contains("SocketException"))
 144       {
 145         // No internet connection
 146         throw new Exception(
 147                 MessageManager
 148                         .getString("exception.unable_to_detect_internet_connection"));
 149       }
 150       else if (exceptionMsg.contains("UnknownHostException"))
 151       {
 152         // The server 'www.ebi.ac.uk' is unreachable
 153         throw new Exception(
 154                 MessageManager
 155                         .getString("exception.pdb_server_unreachable"));
 156       }
 157       else
 158       {
 159         throw e;
 160       }
 161     }
 162   }
 163
 164   public String getMessageByHTTPStatusCode(int code)
 165   {
 166     String message = "";
 167     switch (code)
 168     {
 169     case 410:
 170       message = MessageManager
 171               .getString("exception.pdb_rest_service_no_longer_available");
 172       break;
 173     case 403:
 174     case 404:
 175       message = MessageManager.getString("exception.resource_not_be_found");
 176       break;
 177     case 408:
 178     case 409:
 179     case 500:
 180     case 501:
 181     case 502:
 182     case 503:
 183     case 504:
 184     case 505:
 185       message = MessageManager.getString("exception.pdb_server_error");
 186       break;
 187
 188     default:
 189       break;
 190     }
 191     return message;
 192   }
 193
 194   /**
 195    * Process error response from PDB server if/when one occurs.
 196    *
 197    * @param jsonResponse
 198    *          the JSON string containing error message from the server
 199    * @return the processed error message from the JSON string
 200    */
 201   public static String parseJsonExceptionString(String jsonErrorResponse)
 202   {
 203     StringBuilder errorMessage = new StringBuilder(
 204             "\n============= PDB Rest Client RunTime error =============\n");
 205
 206     try
 207     {
 208       JSONParser jsonParser = new JSONParser();
 209       JSONObject jsonObj = (JSONObject) jsonParser.parse(jsonErrorResponse);
 210       JSONObject errorResponse = (JSONObject) jsonObj.get("error");
 211
 212       JSONObject responseHeader = (JSONObject) jsonObj
 213               .get("responseHeader");
 214       JSONObject paramsObj = (JSONObject) responseHeader.get("params");
 215       String status = responseHeader.get("status").toString();
 216       String message = errorResponse.get("msg").toString();
 217       String query = paramsObj.get("q").toString();
 218       String fl = paramsObj.get("fl").toString();
 219
 220       errorMessage.append("Status: ").append(status).append("\n");
 221       errorMessage.append("Message: ").append(message).append("\n");
 222       errorMessage.append("query: ").append(query).append("\n");
 223       errorMessage.append("fl: ").append(fl).append("\n");
 224
 225     } catch (ParseException e)
 226     {
 227       e.printStackTrace();
 228     }
 229     return errorMessage.toString();
 230   }
 231
 232   /**
 233    * Parses the JSON response string from PDB REST API. The response is dynamic
 234    * hence, only fields specifically requested for in the 'wantedFields'
 235    * parameter is fetched/processed
 236    *
 237    * @param pdbJsonResponseString
 238    *          the JSON string to be parsed
 239    * @param pdbRestRequest
 240    *          the request object which contains parameters used to process the
 241    *          JSON string
 242    * @return
 243    */
 244   @SuppressWarnings("unchecked")
 245   public static PDBRestResponse parsePDBJsonResponse(
 246           String pdbJsonResponseString, PDBRestRequest pdbRestRequest)
 247   {
 248     PDBRestResponse searchResult = new PDBRestResponse();
 249     List<PDBResponseSummary> result = null;
 250     try
 251     {
 252       JSONParser jsonParser = new JSONParser();
 253       JSONObject jsonObj = (JSONObject) jsonParser
 254               .parse(pdbJsonResponseString);
 255
 256       JSONObject pdbResponse = (JSONObject) jsonObj.get("response");
 257       String queryTime = ((JSONObject) jsonObj.get("responseHeader")).get(
 258               "QTime").toString();
 259       int numFound = Integer
 260               .valueOf(pdbResponse.get("numFound").toString());
 261       if (numFound > 0)
 262       {
 263         result = new ArrayList<PDBResponseSummary>();
 264         JSONArray docs = (JSONArray) pdbResponse.get("docs");
 265         for (Iterator<JSONObject> docIter = docs.iterator(); docIter
 266                 .hasNext();)
 267         {
 268           JSONObject doc = docIter.next();
 269           result.add(searchResult.new PDBResponseSummary(doc,
 270                   pdbRestRequest));
 271         }
 272         searchResult.setNumberOfItemsFound(numFound);
 273         searchResult.setResponseTime(queryTime);
 274         searchResult.setSearchSummary(result);
 275       }
 276     } catch (ParseException e)
 277     {
 278       e.printStackTrace();
 279     }
 280     return searchResult;
 281   }
 282
 283   /**
 284    * Takes a collection of PDBDocField and converts its 'code' Field values into
 285    * a comma delimited string.
 286    *
 287    * @param pdbDocfields
 288    *          the collection of PDBDocField to process
 289    * @return the comma delimited string from the pdbDocFields collection
 290    */
 291   public static String getPDBDocFieldsAsCommaDelimitedString(
 292           Collection<PDBDocField> pdbDocfields)
 293   {
 294     String result = "";
 295     if (pdbDocfields != null && !pdbDocfields.isEmpty())
 296     {
 297       StringBuilder returnedFields = new StringBuilder();
 298       for (PDBDocField field : pdbDocfields)
 299       {
 300         returnedFields.append(",").append(field.getCode());
 301       }
 302       returnedFields.deleteCharAt(0);
 303       result = returnedFields.toString();
 304     }
 305     return result;
 306   }
 307
 308   /**
 309    * Determines the column index for 'PDB Id' Fields in the dynamic summary
 310    * table. The PDB Id serves as a unique identifier for a given row in the
 311    * summary table
 312    *
 313    * @param wantedFields
 314    *          the available table columns in no particular order
 315    * @return the pdb id field column index
 316    */
 317   public static int getPDBIdColumIndex(
 318           Collection<PDBDocField> wantedFields, boolean hasRefSeq)
 319   {
 320
 321     // If a reference sequence is attached then start counting from 1 else
 322     // start from zero
 323     int pdbFieldIndexCounter = hasRefSeq ? 1 : 0;
 324
 325     for (PDBDocField field : wantedFields)
 326     {
 327       if (field.equals(PDBDocField.PDB_ID))
 328       {
 329         break; // Once PDB Id index is determined exit iteration
 330       }
 331       ++pdbFieldIndexCounter;
 332     }
 333     return pdbFieldIndexCounter;
 334   }
 335
 336   /**
 337    * This enum represents the fields available in the PDB JSON response
 338    *
 339    */
 340   public enum PDBDocField
 341   {
 342     PDB_ID("PDB Id", "pdb_id"), TITLE("Title", "title"), MOLECULE_NAME(
 343             "Molecule", "molecule_name"), MOLECULE_TYPE("Molecule Type",
 344             "molecule_type"), MOLECULE_SEQUENCE("Sequence",
 345             "molecule_sequence"), PFAM_ACCESSION("PFAM Accession",
 346             "pfam_accession"), PFAM_NAME("PFAM Name", "pfam_name"), INTERPRO_NAME(
 347             "InterPro Name", "interpro_name"), INTERPRO_ACCESSION(
 348             "InterPro Accession", "interpro_accession"), UNIPROT_ID(
 349             "UniProt Id", "uniprot_id"), UNIPROT_ACCESSION(
 350             "UniProt Accession", "uniprot_accession"), UNIPROT_COVERAGE(
 351             "UniProt Coverage", "uniprot_coverage"), UNIPROT_FEATURES(
 352             "Uniprot Features", "uniprot_features"), R_FACTOR("R Factor",
 353             "r_factor"), RESOLUTION("Resolution", "resolution"), DATA_QUALITY(
 354             "Data Quality", "data_quality"), OVERALL_QUALITY(
 355             "Overall Quality", "overall_quality"), POLYMER_COUNT(
 356             "Number of Polymers", "number_of_polymers"), PROTEIN_CHAIN_COUNT(
 357             "Number of Protein Chains", "number_of_protein_chains"), BOUND_MOLECULE_COUNT(
 358             "Number of Bound Molecule", "number_of_bound_molecules"), POLYMER_RESIDUE_COUNT(
 359             "Number of Polymer Residue", "number_of_polymer_residues"), GENUS(
 360             "GENUS", "genus"), GENE_NAME("Gene Name", "gene_name"), EXPERIMENTAL_METHOD(
 361             "Experimental Method", "experimental_method"), GO_ID("GO Id",
 362             "go_id"), ASSEMBLY_ID("Assembly Id", "assembly_form"), ASSEMBLY_FORM(
 363             "Assembly Form", "assembly_id"), ASSEMBLY_TYPE("Assembly Type",
 364             "assembly_type"), SPACE_GROUP("Space Group", "spacegroup"), CATH_CODE(
 365             "Cath Code", "cath_code"), TAX_ID("Tax Id", "tax_id"), TAX_QUERY(
 366             "Tax Query", "tax_query"), INTERACTING_ENTRY_ID(
 367             "Interacting Entry Id", "interacting_entry_id"), INTERACTING_ENTITY_ID(
 368             "Interacting Entity Id", "interacting_entity_id"), INTERACTING_MOLECULES(
 369             "Interacting Molecules", "interacting_molecules"), PUBMED_ID(
 370             "Pubmed Id", "pubmed_id"), STATUS("Status", "status"), MODEL_QUALITY(
 371             "Model Quality", "model_quality"), PIVOT_RESOLUTION(
 372             "Pivot Resolution", "pivot_resolution"), DATA_REDUCTION_SOFTWARE(
 373             "Data reduction software", "data_reduction_software"), MAX_OBSERVED_RES(
 374             "Max observed residues", "max_observed_residues"), ORG_SCI_NAME(
 375             "Organism scientific name", "organism_scientific_name"), SUPER_KINGDOM(
 376             "Super kingdom", "superkingdom"), RANK("Rank", "rank"), CRYSTALLISATION_PH(
 377             "Crystallisation Ph", "crystallisation_ph"), BIOLOGICAL_FUNCTION(
 378             "Biological Function", "biological_function"), BIOLOGICAL_PROCESS(
 379             "Biological Process", "biological_process"), BIOLOGICAL_CELL_COMPONENT(
 380             "Biological Cell Component", "biological_cell_component"), COMPOUND_NAME(
 381             "Compound Name", "compound_name"), COMPOUND_ID("Compound Id",
 382             "compound_id"), COMPOUND_WEIGHT("Compound Weight",
 383             "compound_weight"), COMPOUND_SYSTEMATIC_NAME(
 384             "Compound Systematic Name", "compound_systematic_name"), INTERACTING_LIG(
 385             "Interacting Ligands", "interacting_ligands"), JOURNAL(
 386             "Journal", "journal"), ALL_AUTHORS("All Authors", "all_authors"), EXPERIMENTAL_DATA_AVAILABLE(
 387             "Experiment Data Available", "experiment_data_available"), DIFFRACTION_PROTOCOL(
 388             "Diffraction Protocol", "diffraction_protocol"), REFINEMENT_SOFTWARE(
 389             "Refinement Software", "refinement_software"), STRUCTURE_DETERMINATION_METHOD(
 390             "Structure Determination Method",
 391             "structure_determination_method"), SYNCHROTON_SITE(
 392             "Synchrotron Site", "synchrotron_site"), SAMPLE_PREP_METHOD(
 393             "Sample Preparation Method", "sample_preparation_method"), ENTRY_AUTHORS(
 394             "Entry Authors", "entry_authors"), CITATION_TITLE(
 395             "Citation Title", "citation_title"), STRUCTURE_SOLUTION_SOFTWARE(
 396             "Structure Solution Software", "structure_solution_software"), ENTRY_ENTITY(
 397             "Entry Entity", "entry_entity"), R_FREE("R Free", "r_free"), NO_OF_POLYMER_ENTITIES(
 398             "Number of Polymer Entities", "number_of_polymer_entities"), NO_OF_BOUND_ENTITIES(
 399             "Number of Bound Entities", "number_of_bound_entities"), CRYSTALLISATION_RESERVOIR(
 400             "Crystallisation Reservoir", "crystallisation_reservoir"), DATA_SCALING_SW(
 401             "Data Scalling Software", "data_scaling_software"), DETECTOR(
 402             "Detector", "detector"), DETECTOR_TYPE("Detector Type",
 403             "detector_type"), MODIFIED_RESIDUE_FLAG(
 404             "Modified Residue Flag", "modified_residue_flag"), NUMBER_OF_COPIES(
 405             "Number of Copies", "number_of_copies"), STRUCT_ASYM_ID(
 406             "Struc Asym Id", "struct_asym_id"), HOMOLOGUS_PDB_ENTITY_ID(
 407             "Homologus PDB Entity Id", "homologus_pdb_entity_id"), MOLECULE_SYNONYM(
 408             "Molecule Synonym", "molecule_synonym"), DEPOSITION_SITE(
 409             "Deposition Site", "deposition_site"), SYNCHROTRON_BEAMLINE(
 410             "Synchrotron Beamline", "synchrotron_beamline"), ENTITY_ID(
 411             "Entity Id", "entity_id"), BEAM_SOURCE_NAME("Beam Source Name",
 412             "beam_source_name"), PROCESSING_SITE("Processing Site",
 413             "processing_site"), ENTITY_WEIGHT("Entity Weight",
 414             "entity_weight"), VERSION("Version", "_version_"), ALL("ALL",
 415             "text");
 416
 417     private String name;
 418
 419     private String code;
 420
 421     PDBDocField(String name, String code)
 422     {
 423       this.name = name;
 424       this.code = code;
 425     }
 426
 427     public String getName()
 428     {
 429       return name;
 430     }
 431
 432     public String getCode()
 433     {
 434       return code;
 435     }
 436
 437     @Override
 438     public String toString()
 439     {
 440       return name;
 441     }
 442   }
 443 }