/*
* 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 .
* The Jalview Authors are detailed in the 'AUTHORS' file.
*/
package jalview.ws.dbsources;
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.ws.rs.core.MediaType;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import org.json.simple.parser.JSONParser;
import org.json.simple.parser.ParseException;
import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.config.ClientConfig;
import com.sun.jersey.api.client.config.DefaultClientConfig;
/**
* A rest client for querying the Search endpoing of the PDB REST API
*
* @author tcnofoegbu
*
*/
public class PDBRestClient
{
public static final String PDB_SEARCH_ENDPOINT = "http://www.ebi.ac.uk/pdbe/search/pdb/select?";
private static int DEFAULT_RESPONSE_SIZE = 200;
/**
* 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
{
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;
}
}
}
public String getMessageByHTTPStatusCode(int code)
{
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 message;
}
/**
* 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)
{
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 result = null;
try
{
JSONParser jsonParser = new JSONParser();
JSONObject jsonObj = (JSONObject) jsonParser
.parse(pdbJsonResponseString);
JSONObject pdbResponse = (JSONObject) jsonObj.get("response");
String queryTime = ((JSONObject) jsonObj.get("responseHeader")).get(
"QTime").toString();
int numFound = Integer
.valueOf(pdbResponse.get("numFound").toString());
if (numFound > 0)
{
result = new ArrayList();
JSONArray docs = (JSONArray) pdbResponse.get("docs");
for (Iterator docIter = docs.iterator(); docIter
.hasNext();)
{
JSONObject doc = docIter.next();
result.add(searchResult.new PDBResponseSummary(doc,
pdbRestRequest));
}
searchResult.setNumberOfItemsFound(numFound);
searchResult.setResponseTime(queryTime);
searchResult.setSearchSummary(result);
}
} catch (ParseException e)
{
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 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 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;
}
}
}