2 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3 * Copyright (C) $$Year-Rel$$ The Jalview Authors
5 * This file is part of Jalview.
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.
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.
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.
21 package jalview.ws.dbsources;
23 import jalview.util.MessageManager;
24 import jalview.ws.uimodel.PDBRestRequest;
25 import jalview.ws.uimodel.PDBRestResponse;
26 import jalview.ws.uimodel.PDBRestResponse.PDBResponseSummary;
28 import java.util.ArrayList;
29 import java.util.Collection;
30 import java.util.Iterator;
31 import java.util.List;
33 import javax.ws.rs.core.MediaType;
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;
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;
47 * A rest client for querying the Search endpoing of the PDB REST API
52 public class PDBRestClient
54 public static final String PDB_SEARCH_ENDPOINT = "http://www.ebi.ac.uk/pdbe/search/pdb/select?";
56 private static int DEFAULT_RESPONSE_SIZE = 200;
59 * Takes a PDBRestRequest object and returns a response upon execution
61 * @param pdbRestRequest
62 * the PDBRestRequest instance to be processed
63 * @return the pdbResponse object for the given request
66 public PDBRestResponse executeRequest(PDBRestRequest pdbRestRequest)
71 ClientConfig clientConfig = new DefaultClientConfig();
72 Client client = Client.create(clientConfig);
74 String wantedFields = getPDBDocFieldsAsCommaDelimitedString(pdbRestRequest
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"
82 String facetPivot = (pdbRestRequest.getFacetPivot() == null || pdbRestRequest
83 .getFacetPivot().isEmpty()) ? "" : pdbRestRequest
85 String facetPivotMinCount = String.valueOf(pdbRestRequest
86 .getFacetPivotMinCount());
88 // Build request parameters for the REST Request
89 WebResource webResource = null;
90 if (pdbRestRequest.isFacet())
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);
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);
108 // Execute the REST request
109 ClientResponse clientResponse = webResource.accept(
110 MediaType.APPLICATION_JSON).get(ClientResponse.class);
112 // Get the JSON string from the response object
113 String responseString = clientResponse.getEntity(String.class);
114 // System.out.println("query >>>>>>> " + pdbRestRequest.toString());
116 // Check the response status and report exception if one occurs
117 if (clientResponse.getStatus() != 200)
119 String errorMessage = "";
120 if (clientResponse.getStatus() == 400)
122 errorMessage = parseJsonExceptionString(responseString);
123 throw new Exception(errorMessage);
127 errorMessage = getMessageByHTTPStatusCode(clientResponse
129 throw new Exception(errorMessage);
133 // Make redundant objects eligible for garbage collection to conserve
135 clientResponse = null;
138 // Process the response and return the result to the caller.
139 return parsePDBJsonResponse(responseString, pdbRestRequest);
140 } catch (Exception e)
142 String exceptionMsg = e.getMessage();
143 if (exceptionMsg.contains("SocketException"))
145 // No internet connection
148 .getString("exception.unable_to_detect_internet_connection"));
150 else if (exceptionMsg.contains("UnknownHostException"))
152 // The server 'www.ebi.ac.uk' is unreachable
155 .getString("exception.pdb_server_unreachable"));
164 public String getMessageByHTTPStatusCode(int code)
170 message = MessageManager
171 .getString("exception.pdb_rest_service_no_longer_available");
175 message = MessageManager.getString("exception.resource_not_be_found");
185 message = MessageManager.getString("exception.pdb_server_error");
195 * Process error response from PDB server if/when one occurs.
197 * @param jsonResponse
198 * the JSON string containing error message from the server
199 * @return the processed error message from the JSON string
201 public static String parseJsonExceptionString(String jsonErrorResponse)
203 StringBuilder errorMessage = new StringBuilder(
204 "\n============= PDB Rest Client RunTime error =============\n");
208 JSONParser jsonParser = new JSONParser();
209 JSONObject jsonObj = (JSONObject) jsonParser.parse(jsonErrorResponse);
210 JSONObject errorResponse = (JSONObject) jsonObj.get("error");
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();
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");
225 } catch (ParseException e)
229 return errorMessage.toString();
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
237 * @param pdbJsonResponseString
238 * the JSON string to be parsed
239 * @param pdbRestRequest
240 * the request object which contains parameters used to process the
244 @SuppressWarnings("unchecked")
245 public static PDBRestResponse parsePDBJsonResponse(
246 String pdbJsonResponseString, PDBRestRequest pdbRestRequest)
248 PDBRestResponse searchResult = new PDBRestResponse();
249 List<PDBResponseSummary> result = null;
252 JSONParser jsonParser = new JSONParser();
253 JSONObject jsonObj = (JSONObject) jsonParser
254 .parse(pdbJsonResponseString);
256 JSONObject pdbResponse = (JSONObject) jsonObj.get("response");
257 String queryTime = ((JSONObject) jsonObj.get("responseHeader")).get(
259 int numFound = Integer
260 .valueOf(pdbResponse.get("numFound").toString());
263 result = new ArrayList<PDBResponseSummary>();
264 JSONArray docs = (JSONArray) pdbResponse.get("docs");
265 for (Iterator<JSONObject> docIter = docs.iterator(); docIter
268 JSONObject doc = docIter.next();
269 result.add(searchResult.new PDBResponseSummary(doc,
272 searchResult.setNumberOfItemsFound(numFound);
273 searchResult.setResponseTime(queryTime);
274 searchResult.setSearchSummary(result);
276 } catch (ParseException e)
284 * Takes a collection of PDBDocField and converts its 'code' Field values into
285 * a comma delimited string.
287 * @param pdbDocfields
288 * the collection of PDBDocField to process
289 * @return the comma delimited string from the pdbDocFields collection
291 public static String getPDBDocFieldsAsCommaDelimitedString(
292 Collection<PDBDocField> pdbDocfields)
295 if (pdbDocfields != null && !pdbDocfields.isEmpty())
297 StringBuilder returnedFields = new StringBuilder();
298 for (PDBDocField field : pdbDocfields)
300 returnedFields.append(",").append(field.getCode());
302 returnedFields.deleteCharAt(0);
303 result = returnedFields.toString();
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
313 * @param wantedFields
314 * the available table columns in no particular order
315 * @return the pdb id field column index
317 public static int getPDBIdColumIndex(
318 Collection<PDBDocField> wantedFields, boolean hasRefSeq)
321 // If a reference sequence is attached then start counting from 1 else
323 int pdbFieldIndexCounter = hasRefSeq ? 1 : 0;
325 for (PDBDocField field : wantedFields)
327 if (field.equals(PDBDocField.PDB_ID))
329 break; // Once PDB Id index is determined exit iteration
331 ++pdbFieldIndexCounter;
333 return pdbFieldIndexCounter;
336 public static PDBDocField getPDBDocFieldByCode(String fieldCode)
339 for (PDBDocField curPDBDocField : PDBDocField.values())
341 if (curPDBDocField.getCode().equalsIgnoreCase(fieldCode))
343 return curPDBDocField;
346 throw new Exception("PDB doc Field not found!");
350 * This enum represents the fields available in the PDB JSON response
353 public enum PDBDocField
355 PDB_ID("PDB Id", "pdb_id"), TITLE("Title", "title"), MOLECULE_NAME(
356 "Molecule", "molecule_name"), MOLECULE_TYPE("Molecule Type",
357 "molecule_type"), MOLECULE_SEQUENCE("Sequence",
358 "molecule_sequence"), PFAM_ACCESSION("PFAM Accession",
359 "pfam_accession"), PFAM_NAME("PFAM Name", "pfam_name"), INTERPRO_NAME(
360 "InterPro Name", "interpro_name"), INTERPRO_ACCESSION(
361 "InterPro Accession", "interpro_accession"), UNIPROT_ID(
362 "UniProt Id", "uniprot_id"), UNIPROT_ACCESSION(
363 "UniProt Accession", "uniprot_accession"), UNIPROT_COVERAGE(
364 "UniProt Coverage", "uniprot_coverage"), UNIPROT_FEATURES(
365 "Uniprot Features", "uniprot_features"), R_FACTOR("R Factor",
366 "r_factor"), RESOLUTION("Resolution", "resolution"), DATA_QUALITY(
367 "Data Quality", "data_quality"), OVERALL_QUALITY(
368 "Overall Quality", "overall_quality"), POLYMER_COUNT(
369 "Number of Polymers", "number_of_polymers"), PROTEIN_CHAIN_COUNT(
370 "Number of Protein Chains", "number_of_protein_chains"), BOUND_MOLECULE_COUNT(
371 "Number of Bound Molecule", "number_of_bound_molecules"), POLYMER_RESIDUE_COUNT(
372 "Number of Polymer Residue", "number_of_polymer_residues"), GENUS(
373 "GENUS", "genus"), GENE_NAME("Gene Name", "gene_name"), EXPERIMENTAL_METHOD(
374 "Experimental Method", "experimental_method"), GO_ID("GO Id",
375 "go_id"), ASSEMBLY_ID("Assembly Id", "assembly_form"), ASSEMBLY_FORM(
376 "Assembly Form", "assembly_id"), ASSEMBLY_TYPE("Assembly Type",
377 "assembly_type"), SPACE_GROUP("Space Group", "spacegroup"), CATH_CODE(
378 "Cath Code", "cath_code"), TAX_ID("Tax Id", "tax_id"), TAX_QUERY(
379 "Tax Query", "tax_query"), INTERACTING_ENTRY_ID(
380 "Interacting Entry Id", "interacting_entry_id"), INTERACTING_ENTITY_ID(
381 "Interacting Entity Id", "interacting_entity_id"), INTERACTING_MOLECULES(
382 "Interacting Molecules", "interacting_molecules"), PUBMED_ID(
383 "Pubmed Id", "pubmed_id"), STATUS("Status", "status"), MODEL_QUALITY(
384 "Model Quality", "model_quality"), PIVOT_RESOLUTION(
385 "Pivot Resolution", "pivot_resolution"), DATA_REDUCTION_SOFTWARE(
386 "Data reduction software", "data_reduction_software"), MAX_OBSERVED_RES(
387 "Max observed residues", "max_observed_residues"), ORG_SCI_NAME(
388 "Organism scientific name", "organism_scientific_name"), SUPER_KINGDOM(
389 "Super kingdom", "superkingdom"), RANK("Rank", "rank"), CRYSTALLISATION_PH(
390 "Crystallisation Ph", "crystallisation_ph"), BIOLOGICAL_FUNCTION(
391 "Biological Function", "biological_function"), BIOLOGICAL_PROCESS(
392 "Biological Process", "biological_process"), BIOLOGICAL_CELL_COMPONENT(
393 "Biological Cell Component", "biological_cell_component"), COMPOUND_NAME(
394 "Compound Name", "compound_name"), COMPOUND_ID("Compound Id",
395 "compound_id"), COMPOUND_WEIGHT("Compound Weight",
396 "compound_weight"), COMPOUND_SYSTEMATIC_NAME(
397 "Compound Systematic Name", "compound_systematic_name"), INTERACTING_LIG(
398 "Interacting Ligands", "interacting_ligands"), JOURNAL(
399 "Journal", "journal"), ALL_AUTHORS("All Authors", "all_authors"), EXPERIMENTAL_DATA_AVAILABLE(
400 "Experiment Data Available", "experiment_data_available"), DIFFRACTION_PROTOCOL(
401 "Diffraction Protocol", "diffraction_protocol"), REFINEMENT_SOFTWARE(
402 "Refinement Software", "refinement_software"), STRUCTURE_DETERMINATION_METHOD(
403 "Structure Determination Method",
404 "structure_determination_method"), SYNCHROTON_SITE(
405 "Synchrotron Site", "synchrotron_site"), SAMPLE_PREP_METHOD(
406 "Sample Preparation Method", "sample_preparation_method"), ENTRY_AUTHORS(
407 "Entry Authors", "entry_authors"), CITATION_TITLE(
408 "Citation Title", "citation_title"), STRUCTURE_SOLUTION_SOFTWARE(
409 "Structure Solution Software", "structure_solution_software"), ENTRY_ENTITY(
410 "Entry Entity", "entry_entity"), R_FREE("R Free", "r_free"), NO_OF_POLYMER_ENTITIES(
411 "Number of Polymer Entities", "number_of_polymer_entities"), NO_OF_BOUND_ENTITIES(
412 "Number of Bound Entities", "number_of_bound_entities"), CRYSTALLISATION_RESERVOIR(
413 "Crystallisation Reservoir", "crystallisation_reservoir"), DATA_SCALING_SW(
414 "Data Scalling Software", "data_scaling_software"), DETECTOR(
415 "Detector", "detector"), DETECTOR_TYPE("Detector Type",
416 "detector_type"), MODIFIED_RESIDUE_FLAG(
417 "Modified Residue Flag", "modified_residue_flag"), NUMBER_OF_COPIES(
418 "Number of Copies", "number_of_copies"), STRUCT_ASYM_ID(
419 "Struc Asym Id", "struct_asym_id"), HOMOLOGUS_PDB_ENTITY_ID(
420 "Homologus PDB Entity Id", "homologus_pdb_entity_id"), MOLECULE_SYNONYM(
421 "Molecule Synonym", "molecule_synonym"), DEPOSITION_SITE(
422 "Deposition Site", "deposition_site"), SYNCHROTRON_BEAMLINE(
423 "Synchrotron Beamline", "synchrotron_beamline"), ENTITY_ID(
424 "Entity Id", "entity_id"), BEAM_SOURCE_NAME("Beam Source Name",
425 "beam_source_name"), PROCESSING_SITE("Processing Site",
426 "processing_site"), ENTITY_WEIGHT("Entity Weight",
427 "entity_weight"), VERSION("Version", "_version_"), ALL("ALL",
434 PDBDocField(String name, String code)
440 public String getName()
445 public String getCode()
451 public String toString()