+/*
+ * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
+ * Copyright (C) $$Year-Rel$$ The Jalview Authors
+ *
+ * This file is part of Jalview.
+ *
+ * Jalview is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, either version 3
+ * of the License, or (at your option) any later version.
+ *
+ * Jalview is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ * PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Jalview. If not, see <http://www.gnu.org/licenses/>.
+ * The Jalview Authors are detailed in the 'AUTHORS' file.
+ */
package jalview.ws.dbsources;
-import jalview.ws.uimodel.PDBSearchResultPojo;
-import jalview.ws.uimodel.PDBSummaryListModel;
+import jalview.util.MessageManager;
+import jalview.ws.uimodel.PDBRestRequest;
+import jalview.ws.uimodel.PDBRestResponse;
+import jalview.ws.uimodel.PDBRestResponse.PDBResponseSummary;
+import java.util.ArrayList;
+import java.util.Collection;
import java.util.Iterator;
+import java.util.List;
-import javax.swing.DefaultListModel;
import javax.ws.rs.core.MediaType;
import org.json.simple.JSONArray;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.config.ClientConfig;
import com.sun.jersey.api.client.config.DefaultClientConfig;
-import com.sun.jersey.api.json.JSONConfiguration;
+/**
+ * A rest client for querying the Search endpoing of the PDB REST API
+ *
+ * @author tcnofoegbu
+ *
+ */
public class PDBRestClient
{
- private String pdbSearchEndpoint = "http://wwwdev.ebi.ac.uk/pdbe/search/pdb/select?";
+ public static final String PDB_SEARCH_ENDPOINT = "http://www.ebi.ac.uk/pdbe/search/pdb/select?";
+ private static int DEFAULT_RESPONSE_SIZE = 200;
- public static void main(String[] args)
+ /**
+ * Takes a PDBRestRequest object and returns a response upon execution
+ *
+ * @param pdbRestRequest
+ * the PDBRestRequest instance to be processed
+ * @return the pdbResponse object for the given request
+ * @throws Exception
+ */
+ public PDBRestResponse executeRequest(PDBRestRequest pdbRestRequest)
+ throws Exception
{
- new PDBRestClient().searchResult("pfam_name", "Lipoc*");
+ try
+ {
+ ClientConfig clientConfig = new DefaultClientConfig();
+ Client client = Client.create(clientConfig);
+
+ String wantedFields = getPDBDocFieldsAsCommaDelimitedString(pdbRestRequest
+ .getWantedFields());
+ int responseSize = (pdbRestRequest.getResponseSize() == 0) ? DEFAULT_RESPONSE_SIZE
+ : pdbRestRequest.getResponseSize();
+ String sortParam = null;
+ if (pdbRestRequest.getFieldToSortBy() == null
+ || pdbRestRequest.getFieldToSortBy().trim().isEmpty())
+ {
+ sortParam = "";
+ }
+ else
+ {
+ if (pdbRestRequest.getFieldToSortBy()
+ .equalsIgnoreCase("Resolution"))
+ {
+ sortParam = pdbRestRequest.getFieldToSortBy()
+ + (pdbRestRequest.isAscending() ? " asc" : " desc");
+ }
+ else
+ {
+ sortParam = pdbRestRequest.getFieldToSortBy()
+ + (pdbRestRequest.isAscending() ? " desc" : " asc");
+ }
+ }
+
+ String facetPivot = (pdbRestRequest.getFacetPivot() == null || pdbRestRequest
+ .getFacetPivot().isEmpty()) ? "" : pdbRestRequest
+ .getFacetPivot();
+ String facetPivotMinCount = String.valueOf(pdbRestRequest
+ .getFacetPivotMinCount());
+
+ // Build request parameters for the REST Request
+ WebResource webResource = null;
+ if (pdbRestRequest.isFacet())
+ {
+ webResource = client.resource(PDB_SEARCH_ENDPOINT)
+ .queryParam("wt", "json").queryParam("fl", wantedFields)
+ .queryParam("rows", String.valueOf(responseSize))
+ .queryParam("q", pdbRestRequest.getQuery())
+ .queryParam("sort", sortParam).queryParam("facet", "true")
+ .queryParam("facet.pivot", facetPivot)
+ .queryParam("facet.pivot.mincount", facetPivotMinCount);
+ }
+ else
+ {
+ webResource = client.resource(PDB_SEARCH_ENDPOINT)
+ .queryParam("wt", "json").queryParam("fl", wantedFields)
+ .queryParam("rows", String.valueOf(responseSize))
+ .queryParam("q", pdbRestRequest.getQuery())
+ .queryParam("sort", sortParam);
+ }
+ // Execute the REST request
+ ClientResponse clientResponse = webResource.accept(
+ MediaType.APPLICATION_JSON).get(ClientResponse.class);
+
+ // Get the JSON string from the response object
+ String responseString = clientResponse.getEntity(String.class);
+ // System.out.println("query >>>>>>> " + pdbRestRequest.toString());
+
+ // Check the response status and report exception if one occurs
+ if (clientResponse.getStatus() != 200)
+ {
+ String errorMessage = "";
+ if (clientResponse.getStatus() == 400)
+ {
+ errorMessage = parseJsonExceptionString(responseString);
+ throw new Exception(errorMessage);
+ }
+ else
+ {
+ errorMessage = getMessageByHTTPStatusCode(clientResponse
+ .getStatus());
+ throw new Exception(errorMessage);
+ }
+ }
+
+ // Make redundant objects eligible for garbage collection to conserve
+ // memory
+ clientResponse = null;
+ client = null;
+
+ // Process the response and return the result to the caller.
+ return parsePDBJsonResponse(responseString, pdbRestRequest);
+ } catch (Exception e)
+ {
+ String exceptionMsg = e.getMessage();
+ if (exceptionMsg.contains("SocketException"))
+ {
+ // No internet connection
+ throw new Exception(
+ MessageManager
+ .getString("exception.unable_to_detect_internet_connection"));
+ }
+ else if (exceptionMsg.contains("UnknownHostException"))
+ {
+ // The server 'www.ebi.ac.uk' is unreachable
+ throw new Exception(
+ MessageManager
+ .getString("exception.pdb_server_unreachable"));
+ }
+ else
+ {
+ throw e;
+ }
+ }
}
- private String executeRestSearch(String qParam,
- String searchTerm)
+ public String getMessageByHTTPStatusCode(int code)
{
- ClientConfig clientConfig = new DefaultClientConfig();
- clientConfig.getFeatures().put(JSONConfiguration.FEATURE_POJO_MAPPING,
- Boolean.TRUE);
- Client client = Client.create(clientConfig);
- WebResource webResource = client.resource(pdbSearchEndpoint)
- .queryParam("wt", "json")
- .queryParam("q", qParam + ":" + searchTerm);
- ClientResponse clientResponse = webResource.accept(
- MediaType.APPLICATION_JSON).get(ClientResponse.class);
-
- String responseString = clientResponse.getEntity(String.class);
- if (clientResponse.getStatus() != 200)
- {
- throw new RuntimeException("Failed : HTTP error code : "
- + clientResponse.getStatus());
+ String message = "";
+ switch (code)
+ {
+ case 410:
+ message = MessageManager
+ .getString("exception.pdb_rest_service_no_longer_available");
+ break;
+ case 403:
+ case 404:
+ message = MessageManager.getString("exception.resource_not_be_found");
+ break;
+ case 408:
+ case 409:
+ case 500:
+ case 501:
+ case 502:
+ case 503:
+ case 504:
+ case 505:
+ message = MessageManager.getString("exception.pdb_server_error");
+ break;
+
+ default:
+ break;
}
- return responseString;
+ return message;
}
- public PDBSearchResultPojo searchResult(String qParam,
- String searchTerm)
+ /**
+ * Process error response from PDB server if/when one occurs.
+ *
+ * @param jsonResponse
+ * the JSON string containing error message from the server
+ * @return the processed error message from the JSON string
+ */
+ public static String parseJsonExceptionString(String jsonErrorResponse)
{
- String jsonResponseString = executeRestSearch(qParam, searchTerm);
- PDBSearchResultPojo searchResult = new PDBSearchResultPojo();
- DefaultListModel<PDBSummaryListModel> result = null;
+ StringBuilder errorMessage = new StringBuilder(
+ "\n============= PDB Rest Client RunTime error =============\n");
+
+ try
+ {
+ JSONParser jsonParser = new JSONParser();
+ JSONObject jsonObj = (JSONObject) jsonParser.parse(jsonErrorResponse);
+ JSONObject errorResponse = (JSONObject) jsonObj.get("error");
+
+ JSONObject responseHeader = (JSONObject) jsonObj
+ .get("responseHeader");
+ JSONObject paramsObj = (JSONObject) responseHeader.get("params");
+ String status = responseHeader.get("status").toString();
+ String message = errorResponse.get("msg").toString();
+ String query = paramsObj.get("q").toString();
+ String fl = paramsObj.get("fl").toString();
+
+ errorMessage.append("Status: ").append(status).append("\n");
+ errorMessage.append("Message: ").append(message).append("\n");
+ errorMessage.append("query: ").append(query).append("\n");
+ errorMessage.append("fl: ").append(fl).append("\n");
+
+ } catch (ParseException e)
+ {
+ e.printStackTrace();
+ }
+ return errorMessage.toString();
+ }
+
+ /**
+ * Parses the JSON response string from PDB REST API. The response is dynamic
+ * hence, only fields specifically requested for in the 'wantedFields'
+ * parameter is fetched/processed
+ *
+ * @param pdbJsonResponseString
+ * the JSON string to be parsed
+ * @param pdbRestRequest
+ * the request object which contains parameters used to process the
+ * JSON string
+ * @return
+ */
+ @SuppressWarnings("unchecked")
+ public static PDBRestResponse parsePDBJsonResponse(
+ String pdbJsonResponseString, PDBRestRequest pdbRestRequest)
+ {
+ PDBRestResponse searchResult = new PDBRestResponse();
+ List<PDBResponseSummary> result = null;
try
{
JSONParser jsonParser = new JSONParser();
JSONObject jsonObj = (JSONObject) jsonParser
- .parse(jsonResponseString);
+ .parse(pdbJsonResponseString);
JSONObject pdbResponse = (JSONObject) jsonObj.get("response");
String queryTime = ((JSONObject) jsonObj.get("responseHeader")).get(
.valueOf(pdbResponse.get("numFound").toString());
if (numFound > 0)
{
- result = new DefaultListModel<PDBSummaryListModel>();
+ result = new ArrayList<PDBResponseSummary>();
JSONArray docs = (JSONArray) pdbResponse.get("docs");
for (Iterator<JSONObject> docIter = docs.iterator(); docIter
.hasNext();)
{
JSONObject doc = docIter.next();
- if (doc.get("molecule_sequence") != null)
- {
- result.addElement(new PDBSummaryListModel(doc));
- }
+ result.add(searchResult.new PDBResponseSummary(doc,
+ pdbRestRequest));
}
- searchResult.setItemFound(numFound);
+ searchResult.setNumberOfItemsFound(numFound);
searchResult.setResponseTime(queryTime);
searchResult.setSearchSummary(result);
}
{
e.printStackTrace();
}
-
return searchResult;
}
+ /**
+ * Takes a collection of PDBDocField and converts its 'code' Field values into
+ * a comma delimited string.
+ *
+ * @param pdbDocfields
+ * the collection of PDBDocField to process
+ * @return the comma delimited string from the pdbDocFields collection
+ */
+ public static String getPDBDocFieldsAsCommaDelimitedString(
+ Collection<PDBDocField> pdbDocfields)
+ {
+ String result = "";
+ if (pdbDocfields != null && !pdbDocfields.isEmpty())
+ {
+ StringBuilder returnedFields = new StringBuilder();
+ for (PDBDocField field : pdbDocfields)
+ {
+ returnedFields.append(",").append(field.getCode());
+ }
+ returnedFields.deleteCharAt(0);
+ result = returnedFields.toString();
+ }
+ return result;
+ }
+
+ /**
+ * Determines the column index for 'PDB Id' Fields in the dynamic summary
+ * table. The PDB Id serves as a unique identifier for a given row in the
+ * summary table
+ *
+ * @param wantedFields
+ * the available table columns in no particular order
+ * @return the pdb id field column index
+ */
+ public static int getPDBIdColumIndex(
+ Collection<PDBDocField> wantedFields, boolean hasRefSeq)
+ {
+
+ // If a reference sequence is attached then start counting from 1 else
+ // start from zero
+ int pdbFieldIndexCounter = hasRefSeq ? 1 : 0;
+
+ for (PDBDocField field : wantedFields)
+ {
+ if (field.equals(PDBDocField.PDB_ID))
+ {
+ break; // Once PDB Id index is determined exit iteration
+ }
+ ++pdbFieldIndexCounter;
+ }
+ return pdbFieldIndexCounter;
+ }
+
+ public static PDBDocField getPDBDocFieldByCode(String fieldCode)
+ throws Exception
+ {
+ for (PDBDocField curPDBDocField : PDBDocField.values())
+ {
+ if (curPDBDocField.getCode().equalsIgnoreCase(fieldCode))
+ {
+ return curPDBDocField;
+ }
+ }
+ throw new Exception("PDB doc Field not found!");
+ }
+
+ /**
+ * This enum represents the fields available in the PDB JSON response
+ *
+ */
+ public enum PDBDocField
+ {
+ PDB_ID("PDB Id", "pdb_id", Group.CROSS_REFS), TITLE(
+ "Title",
+ "title", Group.MISCELLENOUS),
+ MOLECULE_NAME("Molecule",
+ "molecule_name",
+ Group.NAMES_AND_TAXONOMY), MOLECULE_TYPE(
+ "Molecule Type", "molecule_type", Group.NAMES_AND_TAXONOMY), MOLECULE_SEQUENCE(
+ "Sequence", "molecule_sequence", Group.MISCELLENOUS), PFAM_ACCESSION(
+ "PFAM Accession", "pfam_accession",
+ Group.CROSS_REFS), PFAM_NAME(
+ "PFAM Name", "pfam_name", Group.NAMES_AND_TAXONOMY), INTERPRO_NAME(
+ "InterPro Name", "interpro_name", Group.NAMES_AND_TAXONOMY), INTERPRO_ACCESSION(
+ "InterPro Accession", "interpro_accession",
+ Group.CROSS_REFS), UNIPROT_ID("UniProt Id",
+ "uniprot_id", Group.CROSS_REFS), UNIPROT_ACCESSION(
+ "UniProt Accession", "uniprot_accession",
+ Group.CROSS_REFS),
+
+ UNIPROT_COVERAGE(
+ "UniProt Coverage", "uniprot_coverage", Group.MISCELLENOUS), UNIPROT_FEATURES(
+ "Uniprot Features", "uniprot_features", Group.MISCELLENOUS), R_FACTOR(
+"R Factor",
+ "r_factor", Group.QUALITY_MEASURES), RESOLUTION("Resolution",
+ "resolution", Group.QUALITY_MEASURES), DATA_QUALITY(
+ "Data Quality", "data_quality", Group.QUALITY_MEASURES), OVERALL_QUALITY(
+ "Overall Quality", "overall_quality", Group.QUALITY_MEASURES), POLYMER_COUNT(
+ "Number of Polymers", "number_of_polymers", Group.MISCELLENOUS), PROTEIN_CHAIN_COUNT(
+ "Number of Protein Chains", "number_of_protein_chains",
+ Group.MISCELLENOUS), BOUND_MOLECULE_COUNT(
+ "Number of Bound Molecule", "number_of_bound_molecules",
+ Group.MISCELLENOUS), POLYMER_RESIDUE_COUNT(
+ "Number of Polymer Residue", "number_of_polymer_residues",
+ Group.MISCELLENOUS), GENUS("GENUS", "genus",
+ Group.NAMES_AND_TAXONOMY), GENE_NAME("Gene Name", "gene_name",
+ Group.NAMES_AND_TAXONOMY), EXPERIMENTAL_METHOD(
+ "Experimental Method", "experimental_method",
+ Group.PROCEDURE_AND_SOFTWARE), GO_ID("GO Id", "go_id",
+ Group.CROSS_REFS), ASSEMBLY_ID("Assembly Id",
+ "assembly_id", Group.CROSS_REFS), ASSEMBLY_FORM(
+ "Assembly Form", "assembly_form", Group.MISCELLENOUS), ASSEMBLY_TYPE(
+ "Assembly Type", "assembly_type", Group.MISCELLENOUS), SPACE_GROUP(
+ "Space Group", "spacegroup", Group.MISCELLENOUS), CATH_CODE(
+ "Cath Code", "cath_code", Group.CROSS_REFS), TAX_ID(
+ "Tax Id", "tax_id", Group.CROSS_REFS), TAX_QUERY(
+ "Tax Query", "tax_query", Group.CROSS_REFS), INTERACTING_ENTITY_ID(
+ "Interacting Entity Id", "interacting_entity_id",
+ Group.CROSS_REFS), INTERACTING_MOLECULES(
+ "Interacting Molecules", "interacting_molecules",
+ Group.MISCELLENOUS), PUBMED_ID("Pubmed Id", "pubmed_id",
+ Group.CROSS_REFS), STATUS("Status", "status",
+ Group.MISCELLENOUS), MODEL_QUALITY("Model Quality",
+ "model_quality", Group.QUALITY_MEASURES), PIVOT_RESOLUTION(
+ "Pivot Resolution", "pivot_resolution", Group.QUALITY_MEASURES), DATA_REDUCTION_SOFTWARE(
+ "Data reduction software", "data_reduction_software",
+ Group.PROCEDURE_AND_SOFTWARE), MAX_OBSERVED_RES(
+ "Max observed residues",
+ "max_observed_residues", Group.MISCELLENOUS), ORG_SCI_NAME(
+ "Organism scientific name", "organism_scientific_name",
+ Group.NAMES_AND_TAXONOMY), SUPER_KINGDOM("Super kingdom",
+ "superkingdom", Group.NAMES_AND_TAXONOMY), RANK("Rank", "rank",
+ Group.NAMES_AND_TAXONOMY), CRYSTALLISATION_PH(
+ "Crystallisation Ph",
+ "crystallisation_ph", Group.MISCELLENOUS), BIOLOGICAL_FUNCTION(
+ "Biological Function", "biological_function",
+ Group.MISCELLENOUS), BIOLOGICAL_PROCESS("Biological Process",
+ "biological_process", Group.MISCELLENOUS), BIOLOGICAL_CELL_COMPONENT(
+ "Biological Cell Component", "biological_cell_component",
+ Group.MISCELLENOUS), COMPOUND_NAME("Compound Name",
+ "compound_name", Group.NAMES_AND_TAXONOMY), COMPOUND_ID(
+ "Compound Id", "compound_id", Group.CROSS_REFS), COMPOUND_WEIGHT(
+ "Compound Weight", "compound_weight", Group.MISCELLENOUS), COMPOUND_SYSTEMATIC_NAME(
+ "Compound Systematic Name", "compound_systematic_name",
+ Group.NAMES_AND_TAXONOMY), INTERACTING_LIG(
+ "Interacting Ligands",
+ "interacting_ligands", Group.MISCELLENOUS), JOURNAL("Journal",
+ "journal", Group.MISCELLENOUS), ALL_AUTHORS("All Authors",
+ "all_authors", Group.MISCELLENOUS), EXPERIMENTAL_DATA_AVAILABLE(
+ "Experiment Data Available", "experiment_data_available",
+ Group.MISCELLENOUS), DIFFRACTION_PROTOCOL(
+ "Diffraction Protocol", "diffraction_protocol",
+ Group.PROCEDURE_AND_SOFTWARE), REFINEMENT_SOFTWARE(
+ "Refinement Software", "refinement_software",
+ Group.PROCEDURE_AND_SOFTWARE), STRUCTURE_DETERMINATION_METHOD(
+ "Structure Determination Method",
+ "structure_determination_method", Group.PROCEDURE_AND_SOFTWARE), SYNCHROTON_SITE(
+ "Synchrotron Site", "synchrotron_site", Group.MISCELLENOUS), SAMPLE_PREP_METHOD(
+ "Sample Preparation Method", "sample_preparation_method",
+ Group.PROCEDURE_AND_SOFTWARE), ENTRY_AUTHORS("Entry Authors",
+ "entry_authors", Group.MISCELLENOUS), CITATION_TITLE(
+ "Citation Title", "citation_title", Group.MISCELLENOUS), STRUCTURE_SOLUTION_SOFTWARE(
+ "Structure Solution Software", "structure_solution_software",
+ Group.PROCEDURE_AND_SOFTWARE), ENTRY_ENTITY("Entry Entity",
+ "entry_entity", Group.MISCELLENOUS), R_FREE("R Free", "r_free",
+ Group.QUALITY_MEASURES), NO_OF_POLYMER_ENTITIES(
+ "Number of Polymer Entities", "number_of_polymer_entities",
+ Group.MISCELLENOUS), NO_OF_BOUND_ENTITIES(
+ "Number of Bound Entities", "number_of_bound_entities",
+ Group.MISCELLENOUS), CRYSTALLISATION_RESERVOIR(
+ "Crystallisation Reservoir", "crystallisation_reservoir",
+ Group.MISCELLENOUS), DATA_SCALING_SW("Data Scalling Software",
+ "data_scaling_software", Group.PROCEDURE_AND_SOFTWARE), DETECTOR(
+ "Detector", "detector", Group.MISCELLENOUS), DETECTOR_TYPE(
+ "Detector Type", "detector_type", Group.MISCELLENOUS), MODIFIED_RESIDUE_FLAG(
+ "Modified Residue Flag", "modified_residue_flag",
+ Group.MISCELLENOUS), NUMBER_OF_COPIES("Number of Copies",
+ "number_of_copies", Group.MISCELLENOUS), STRUCT_ASYM_ID(
+ "Struc Asym Id", "struct_asym_id",
+ Group.CROSS_REFS), HOMOLOGUS_PDB_ENTITY_ID(
+ "Homologus PDB Entity Id", "homologus_pdb_entity_id",
+ Group.CROSS_REFS), MOLECULE_SYNONYM(
+ "Molecule Synonym",
+ "molecule_synonym", Group.MISCELLENOUS), DEPOSITION_SITE(
+ "Deposition Site", "deposition_site", Group.MISCELLENOUS), SYNCHROTRON_BEAMLINE(
+ "Synchrotron Beamline", "synchrotron_beamline",
+ Group.MISCELLENOUS), ENTITY_ID("Entity Id", "entity_id",
+ Group.CROSS_REFS), BEAM_SOURCE_NAME(
+ "Beam Source Name",
+ "beam_source_name",
+ Group.NAMES_AND_TAXONOMY), PROCESSING_SITE(
+ "Processing Site", "processing_site", Group.MISCELLENOUS), ENTITY_WEIGHT(
+ "Entity Weight", "entity_weight", Group.MISCELLENOUS), VERSION(
+ "Version", "_version_", Group.MISCELLENOUS), ALL("ALL", "text",
+ Group.MISCELLENOUS);
+
+ public enum Group
+ {
+ DATE_OF("Date Of", 5), NAMES_AND_TAXONOMY("Names & Taxonomy", 3),
+ MISCELLENOUS("Miscellenous", 6), QUALITY_MEASURES("Quality Measures",
+ 1), CROSS_REFS("Cross References", 2),
+ PROCEDURE_AND_SOFTWARE("Procedures & Softwares", 4);
+
+ Group(String name, int sortOrder)
+ {
+ this.name = name;
+ this.sortOrder = sortOrder;
+ }
+
+ private String name;
+
+ private int sortOrder;
+
+ public String getName()
+ {
+ return this.name;
+ }
+
+ public int getSortOrder()
+ {
+ return sortOrder;
+ }
+
+ @Override
+ public String toString()
+ {
+ return this.name;
+ }
+ };
+ private String name;
+
+ private String code;
+
+ private Group group;
+
+ PDBDocField(String name, String code, Group group)
+ {
+ this.name = name;
+ this.code = code;
+ this.group = group;
+ }
+
+ public String getName()
+ {
+ return name;
+ }
+
+ public String getCode()
+ {
+ return code;
+ }
+
+ public Group getGroup()
+ {
+ return group;
+ }
+
+ @Override
+ public String toString()
+ {
+ return name;
+ }
+ }
}