JAL-1668 finally clean up

diff --git a/src/jalview/ws/dbsources/PDBRestClient.java b/src/jalview/ws/dbsources/PDBRestClient.java
index 039d23f..1ab6125 100644 (file)
--- a/src/jalview/ws/dbsources/PDBRestClient.java
+++ b/src/jalview/ws/dbsources/PDBRestClient.java
@@ -23,16 +23,24 @@ 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?";
+  private static String PDB_SEARCH_ENDPOINT = "http://wwwdev.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 pdbRequest to be sent
-   * @return the pdbResponse object for the given pdbRequest
+   *          the PDBRestRequest instance to be processed
+   * @return the pdbResponse object for the given request
    */
   public PDBRestResponse executeRequest(PDBRestRequest pdbRestRequest)
   {
@@ -41,45 +49,52 @@ public class PDBRestClient
             Boolean.TRUE);
     Client client = Client.create(clientConfig);
 
-    String query = pdbRestRequest.getFieldToSearchBy()
-            + pdbRestRequest.getSearchTerm()
-            + ((pdbRestRequest.isAllowEmptySeq()) ? ""
-                    : " AND molecule_sequence:['' TO *]");
-
     String wantedFields = getPDBDocFieldsAsCommaDelimitedString(pdbRestRequest
             .getWantedFields());
-
-    String responseSize = (pdbRestRequest.getResponseSize() == 0) ? "200"
-            : String.valueOf(pdbRestRequest.getResponseSize());
+    int responseSize = (pdbRestRequest.getResponseSize() == 0) ? DEFAULT_RESPONSE_SIZE
+            : pdbRestRequest.getResponseSize();
     String sortParam = (pdbRestRequest.getFieldToSortBy() == null || pdbRestRequest
-            .getFieldToSortBy().trim().isEmpty()) ? ""
- : (pdbRestRequest
+            .getFieldToSortBy().trim().isEmpty()) ? "" : (pdbRestRequest
             .getFieldToSortBy() + (pdbRestRequest.isAscending() ? " asc"
             : " desc"));
 
-    WebResource webResource = client.resource(pdbSearchEndpoint)
+    // Build request parameters for the REST Request
+    WebResource webResource = client.resource(PDB_SEARCH_ENDPOINT)
             .queryParam("wt", "json").queryParam("fl", wantedFields)
-            .queryParam("rows", responseSize)
-            .queryParam("q", query)
+            .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);
+
+    // Check the response status and report exception if one occurs
     if (clientResponse.getStatus() != 200)
     {
+      String errorMessage = "";
       if (clientResponse.getStatus() == 400)
       {
-        throw new RuntimeException(parseJsonExceptionString(responseString));
+        errorMessage = parseJsonExceptionString(responseString);
+        throw new RuntimeException(errorMessage);
       }
       else
       {
-      throw new RuntimeException("Failed : HTTP error code : "
-              + clientResponse.getStatus());
+        errorMessage = "Failed : HTTP error code : "
+                + clientResponse.getStatus();
+        throw new RuntimeException(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);
   }
 
@@ -87,8 +102,8 @@ public class PDBRestClient
    * 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
+   *          the JSON string containing error message from the server
+   * @return the processed error message from the JSON string
    */
   public static String parseJsonExceptionString(String jsonErrorResponse)
   {
@@ -111,21 +126,20 @@ public class PDBRestClient
   }
 
   /**
-   * Parses json response string from PDB REST API to a PDBRestResponse
-   * instance. The parsed response is dynamic and based upon some of the request
-   * parameters.
+   * 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
+   *          the JSON string to be parsed
    * @param pdbRestRequest
    *          the request object which contains parameters used to process the
-   *          json string
+   *          JSON string
    * @return
    */
   @SuppressWarnings("unchecked")
   public static PDBRestResponse parsePDBJsonResponse(
-          String pdbJsonResponseString,
-          PDBRestRequest pdbRestRequest)
+          String pdbJsonResponseString, PDBRestRequest pdbRestRequest)
   {
     PDBRestResponse searchResult = new PDBRestResponse();
     List<PDBResponseSummary> result = null;
@@ -148,7 +162,8 @@ public class PDBRestClient
                 .hasNext();)
         {
           JSONObject doc = docIter.next();
-          result.add(searchResult.new PDBResponseSummary(doc, pdbRestRequest));
+          result.add(searchResult.new PDBResponseSummary(doc,
+                  pdbRestRequest));
         }
         searchResult.setNumberOfItemsFound(numFound);
         searchResult.setResponseTime(queryTime);
@@ -162,11 +177,12 @@ public class PDBRestClient
   }
 
   /**
-   * Takes a collection of PDBDocField and converts its code values into a comma
-   * delimited string.
+   * Takes a collection of PDBDocField and converts its 'code' Field values into
+   * a comma delimited string.
    * 
    * @param pdbDocfields
-   * @return
+   *          the collection of PDBDocField to process
+   * @return the comma delimited string from the pdbDocFields collection
    */
   public static String getPDBDocFieldsAsCommaDelimitedString(
           Collection<PDBDocField> pdbDocfields)
@@ -179,7 +195,7 @@ public class PDBRestClient
       {
         returnedFields.append(",").append(field.getCode());
       }
-      returnedFields.deleteCharAt(0); 
+      returnedFields.deleteCharAt(0);
       result = returnedFields.toString();
     }
     return result;
@@ -197,14 +213,16 @@ public class PDBRestClient
   public static int getPDBIdColumIndex(
           Collection<PDBDocField> wantedFeilds, boolean hasRefSeq)
   {
-    int pdbFeildIndexCounter = hasRefSeq ? 1 : 0; // If a reference sequence is
-                                           // attached then start counting from
-                                           // 1 else start from zero
+
+    // If a reference sequence is attached then start counting from 1 else
+    // start from zero
+    int pdbFeildIndexCounter = hasRefSeq ? 1 : 0;
+
     for (PDBDocField feild : wantedFeilds)
     {
       if (feild.equals(PDBDocField.PDB_ID))
       {
-        break; // once PDB Id index is determined exit iteration
+        break; // Once PDB Id index is determined exit iteration
       }
       ++pdbFeildIndexCounter;
     }
@@ -212,7 +230,7 @@ public class PDBRestClient
   }
 
   /**
-   * Represents the fields retrievable from a PDB Document response
+   * This enum represents the fields available in the PDB JSON response
    *
    */
   public enum PDBDocField
@@ -252,14 +270,14 @@ public class PDBRestClient
             "Max observed residues", "max_observed_residues"), ORG_SCI_NAME(
             "Organism scientific name", "organism_scientific_name"), SUPER_KINGDOM(
             "Super kingdom", "superkingdom"), RANK("Rank", "rank"), CRYSTALLISATION_PH(
-            "Crystallisation Ph", "crystallisation_ph"), BIO_FUNCTION(
-            "Biological Function", "biological_function"), BIO_PROCESS(
-            "Biological Process", "biological_process"), BIO_CELL_COMP(
+            "Crystallisation Ph", "crystallisation_ph"), BIOLOGICAL_FUNCTION(
+            "Biological Function", "biological_function"), BIOLOGICAL_PROCESS(
+            "Biological Process", "biological_process"), BIOLOGICAL_CELL_COMPONENT(
             "Biological Cell Component", "biological_cell_component"), COMPOUND_NAME(
             "Compound Name", "compound_name"), COMPOUND_ID("Compound Id",
             "compound_id"), COMPOUND_WEIGHT("Compound Weight",
-            "compound_weight"), COMP_SYS_NAME("Compound Systematic Name",
-            "compound_systematic_name"), INTERACTING_LIG(
+            "compound_weight"), COMPOUND_SYSTEMATIC_NAME(
+            "Compound Systematic Name", "compound_systematic_name"), INTERACTING_LIG(
             "Interacting Ligands", "interacting_ligands"), JOURNAL(
             "Journal", "journal"), ALL_AUTHORS("All Authors", "all_authors"), EXPERIMENTAL_DATA_AVAILABLE(
             "Experiment Data Available", "experiment_data_available"), DIFFRACTION_PROTOCOL(
@@ -317,4 +335,4 @@ public class PDBRestClient
       return name;
     }
   }
-}
+}
\ No newline at end of file

diff --git a/src/jalview/ws/uimodel/PDBRestRequest.java b/src/jalview/ws/uimodel/PDBRestRequest.java
index 2b9a7f3..70dae0b 100644 (file)
--- a/src/jalview/ws/uimodel/PDBRestRequest.java
+++ b/src/jalview/ws/uimodel/PDBRestRequest.java
@@ -127,4 +127,9 @@ public class PDBRestRequest
     this.associatedSequence = associatedSequence;
   }
 
+  public String getQuery()
+  {
+    return fieldToSearchBy + searchTerm
+            + (isAllowEmptySeq() ? "" : " AND molecule_sequence:['' TO *]");
+  }
 }

diff --git a/src/jalview/ws/uimodel/PDBRestResponse.java b/src/jalview/ws/uimodel/PDBRestResponse.java
index fb227ee..7f570a4 100644 (file)
--- a/src/jalview/ws/uimodel/PDBRestResponse.java
+++ b/src/jalview/ws/uimodel/PDBRestResponse.java
@@ -77,8 +77,8 @@ public class PDBRestResponse
 
 
   /**
-   * Convenience method to obtain a Table model for a given summary List and
-   * request
+   * Convenience method to obtain a Table model for a given summary List based
+   * on the request parameters
    * 
    * @param request
    *          the PDBRestRequest object which holds useful information for
@@ -115,8 +115,6 @@ public class PDBRestResponse
   /**
    * Model for a unique response summary
    * 
-   * @author tcnofoegbu
-   *
    */
   public class PDBResponseSummary
   {
@@ -126,7 +124,7 @@ public class PDBRestResponse
 
     private String associatedSequence;
 
-    public PDBResponseSummary(JSONObject doc, PDBRestRequest request)
+    public PDBResponseSummary(JSONObject pdbJsonDoc, PDBRestRequest request)
     {
       Collection<PDBDocField> diplayFields = request.getWantedFields();
       String associatedSeq = request.getAssociatedSequence();
@@ -143,10 +141,11 @@ public class PDBRestResponse
 
       for (PDBDocField field : diplayFields)
       {
-        String fieldData = (doc.get(field.getCode()) == null) ? "" : doc
+        String fieldData = (pdbJsonDoc.get(field.getCode()) == null) ? ""
+                : pdbJsonDoc
                 .get(field.getCode()).toString();
         if (field.equals(PDBDocField.PDB_ID)
-                && doc.get(PDBDocField.PDB_ID.getCode()) != null)
+                && pdbJsonDoc.get(PDBDocField.PDB_ID.getCode()) != null)
         {
           this.pdbId = fieldData;
           summaryRowData[colCounter++] = this.pdbId;
@@ -178,6 +177,9 @@ public class PDBRestResponse
       this.summaryRowData = summaryData;
     }
 
+    /**
+     * Returns a string representation of this object;
+     */
     @Override
     public String toString()
     {
@@ -189,12 +191,18 @@ public class PDBRestResponse
       return summaryFieldValues.toString();
     }
 
+    /**
+     * Returns hash code value for this object
+     */
     @Override
     public int hashCode()
     {
       return Objects.hash(this.pdbId, this.toString());
     }
 
+    /**
+     * Indicates whether some object is equal to this one
+     */
     @Override
     public boolean equals(Object that)
     {