Merge pull request #36 from pwrose/master

Add functionality to read from https and support reduced files.

mmtf-codec/src/main/java/org/rcsb/mmtf/decoder/ReaderUtils.java

@@ -14,7 +14,7 @@
 import org.rcsb.mmtf.utils.CodecUtils;
 
 /**
- * A class of static utility methods for reading data.
+ * This class provides methods to retrieve and decode MMTF data from the MMTF server and MMTF files. 
  *
  * @author Anthony Bradley
  *
@@ -26,35 +26,66 @@ public class ReaderUtils {
 	 */
 	private static final int BYTE_BUFFER_CHUNK_SIZE = 4096;
 
+
 	/**
-	 * Find the message pack byte array from the web using the input code and a base url. Caches the
-	 * file if possible.
+	 * Returns a full (atom atom) MmmtfStructure given a PDB Id from the MMTF web server using HTTP.
 	 *
-	 * @param pdbCode the pdb code for the desired structure.
-	 * @return the MMTFBean of the deserialized data
+	 * @param pdbId the pdb code for the desired structure.
+	 * @return MmtfStructure containing the decoded structure
 	 * @throws IOException if the data cannot be read from the URL
 	 */
-	public static MmtfStructure getDataFromUrl(String pdbCode)
+	public static MmtfStructure getDataFromUrl(String pdbId) throws IOException {
+	    return getDataFromUrl(pdbId, false, false);
+	}
+
+	/**
+	 * Returns an MmmtfStructure given a PDB Id from the MMTF web server. 
+	 * It requests, gets, decompresses, deserializes and decodes the message pack byte array from the MMTF web server.
+	 * This methods support http and https protocols and two MMTF representations: full and reduced.
+	 * reduced: C-alpha atoms for polypeptides, P for polynucleotides, and all atom for all other groups (residues) at 0.1 A coordinate precision;
+	 * full: all atoms at 0.001 A coordinate precision
+	 *
+	 * @param pdbId the pdb code for the desired structure.
+	 * @return decoded MmmtfStructure
+	 * @throws IOException if the data cannot be read from the URL
+	 */
+	public static MmtfStructure getDataFromUrl(String pdbId, boolean https, boolean reduced)
 		throws IOException {
 		// Get these as an inputstream
-		byte[] bytes = getByteArrayFromUrl(pdbCode);
+		byte[] bytes = getByteArrayFromUrl(pdbId, https, reduced);
 		// Now return the gzip deflated and deserialized byte array
 		MessagePackSerialization mmtfBeanSeDeMessagePackImpl
 			= new MessagePackSerialization();
 		return mmtfBeanSeDeMessagePackImpl.deserialize(new ByteArrayInputStream(
 			deflateGzip(bytes)));
 	}
+
+
 
 	/**
-	 * Get the GZIP compressed and messagepack serialized data from the MMTF servers
+	 * Gets the GZIP compressed and messagepack serialized data from the MMTF servers
 	 *
-	 * @param pdbCode the PDB code for the data required
+	 * @param pdbId the PDB code for the data required
 	 * @return the byte array (GZIP compressed) of the data from the URL
 	 * @throws IOException an error reading the URL
 	 */
-	public static byte[] getByteArrayFromUrl(String pdbCode)
+	public static byte[] getByteArrayFromUrl(String pdbId) throws IOException {
+		return getByteArrayFromUrl(pdbId, false, false);
+	}
+
+	/**
+	 * Gets the GZIP compressed and messagepack serialized data from the MMTF servers.
+	 * This methods support http and https protocols and two MMTF representations: full and reduced.
+	 * reduced: C-alpha atoms for polypeptides, P for polynucleotides, and all atom for all other groups (residues) at 0.1 A coordinate precision;
+	 * full: all atoms at 0.001 A coordinate precision
+	 *
+	 * @param pdbId the PDB Id to retrieve
+	 * @return the byte array (GZIP compressed) of the data from the URL
+	 * @throws IOException an error reading the URL
+	 */
+	public static byte[] getByteArrayFromUrl(String pdbId, boolean https, boolean reduced)
 		throws IOException {
-		URL url = new URL(getUrl(pdbCode));
+		URL url = new URL(CodecUtils.getMmtfEntryUrl(pdbId, https, reduced));
 		try (InputStream inputStream = url.openStream();
 			ByteArrayOutputStream baos = new ByteArrayOutputStream();) {
 			byte[] byteChunk = new byte[BYTE_BUFFER_CHUNK_SIZE];
@@ -92,7 +123,7 @@ public static byte[] deflateGzip(byte[] inputBytes) throws IOException {
 	}
 
 	/**
-	 * A function to get MMTF data from a file path.
+	 * Reads and deserializes an uncompressed MMTF file.
 	 *
 	 * @param filePath the full path of the file to be read
 	 * @return the deserialized {@link MmtfStructure}
@@ -132,13 +163,4 @@ public static MmtfStructure getDataFromInputStream(InputStream inStream)
 		return mmtfBeanSeDeMessagePackImpl.deserialize(inStream);
 	}
 
-	/**
-	 * Get the URL to return a given PDB id
-	 *
-	 * @param pdbId the input PDB id
-	 * @return the URL {@link String} to get data from
-	 */
-	public static String getUrl(String pdbId) {
-		return CodecUtils.BASE_URL + pdbId;
-	}
 }

mmtf-codec/src/test/java/org/rcsb/mmtf/decoder/TestReaderUtils.java

@@ -87,5 +87,61 @@ public void testReadFromFile() throws IOException, ParseException {
 		MmtfStructure mmtfBean = ReaderUtils.getDataFromFile(Utils.getResource("/mmtf/4cup.mmtf"));
 		assertNotEquals(mmtfBean, null);
 		assertEquals(mmtfBean.getDepositionDate(), "2014-03-21");
+		assertEquals(mmtfBean.getNumAtoms(), 1107);
+		assertEquals(mmtfBean.getNumBonds(), 978);
+	}
+
+	/**
+	 * Test that we can read an mmtf file from the MMTF web server
+	 * @throws IOException error accessing the data
+	 */
+	@Test 
+	public void testReadFromUrl() throws IOException, ParseException {
+		MmtfStructure mmtfBean = ReaderUtils.getDataFromUrl("4cup");
+		assertNotEquals(mmtfBean, null);
+		assertEquals(mmtfBean.getDepositionDate(), "2014-03-21");
+		assertEquals(mmtfBean.getNumAtoms(), 1107);
+		assertEquals(mmtfBean.getNumBonds(), 978);
+	}
+
+	/**
+	 * Test that we can read an mmtf file from the MMTF web server using HTTPS
+	 * @throws IOException error accessing the data
+	 */
+	@Test 
+	public void testReadFromHttpsUrl() throws IOException, ParseException {
+		MmtfStructure mmtfBean = ReaderUtils.getDataFromUrl("4cup", true, false);
+		assertNotEquals(mmtfBean, null);
+		assertEquals(mmtfBean.getDepositionDate(), "2014-03-21");
+		assertEquals(mmtfBean.getNumAtoms(), 1107);
+		assertEquals(mmtfBean.getNumBonds(), 978);
+	}
+
+	/**
+	 * Test that we can read a reduced mmtf file from the MMTF web server using HTTP
+	 * @throws IOException error accessing the data
+	 */
+	@Test 
+	public void testReadFromReducedUrl() throws IOException, ParseException {
+		MmtfStructure mmtfBean = ReaderUtils.getDataFromUrl("4cup", true, true);
+		assertNotEquals(mmtfBean, null);
+		assertEquals(mmtfBean.getDepositionDate(), "2014-03-21");
+		// Actual number of atoms is 24 ligand atoms + 115 CA = 139 atoms. 
+		// Problem: residue A1945 has two alternate locations for the side chain, however, there is only 1 CA location. 
+		assertEquals(mmtfBean.getNumAtoms(), 140);
+		assertEquals(mmtfBean.getNumBonds(), 21);
+	}
+
+	/**
+	 * Test that we can read a reduced mmtf file from the MMTF web server using HTTPS
+	 * @throws IOException error accessing the data
+	 */
+	@Test 
+	public void testReadFromReducedHttpsUrl() throws IOException, ParseException {
+		MmtfStructure mmtfBean = ReaderUtils.getDataFromUrl("4cup", true, true);
+		assertNotEquals(mmtfBean, null);
+		assertEquals(mmtfBean.getDepositionDate(), "2014-03-21");
+		assertEquals(mmtfBean.getNumAtoms(), 140); 
+		assertEquals(mmtfBean.getNumBonds(), 21);
 	}
 }

mmtf-serialization/src/main/java/org/rcsb/mmtf/utils/CodecUtils.java

@@ -4,24 +4,60 @@
 
 /**
  * A utility class of static methods and constants
- * for the codec project.
  * @author Anthony Bradley
  *
  */
 public class CodecUtils {
-	
-
-	/** The base url for this version of MMTF. */
-	public static final String BASE_URL = "http://mmtf.rcsb.org/v1.0/full/";
-	
+
+	/**
+	 * Path to MMTF files compatible with MMTF Specification version 1.0
+	 */
+    private static final String MMTF_PATH = "mmtf.rcsb.org/v1.0/";
 
 	/** The maximum number of chars in a chain entry. */
 	public static final int MAX_CHARS_PER_CHAIN_ENTRY= 4;
 
+	/**
+	 * Returns the RESTful URL to an MMTF encoded PDB entry. This methods support http and https protocols and two MMTF representations: full and reduced.
+	 * reduced: C-alpha atoms for polypeptides, P for polynucleotides, and all atom for all other groups (residues) at 0.1 A coordinate precision;
+	 * full: all atoms at 0.001 A coordinate precision
+	 * @param pdbId PDB Id
+	 * @param https if true, use HTTPS instead of HTTP
+	 * @param reduced if true, use reduced representation of MMTF file instead of full representation
+	 * @return
+	 */
+	public static String getMmtfEntryUrl(String pdbId, boolean https, boolean reduced) {
+		return getMmtfBaseUrl(https, reduced) + pdbId;
+	}
 
+	/**
+	 * Returns the base URL to retrieve MMTF files.
+	 * @param https if true, returns https URL, otherwise http URL
+	 * @param reduced if true, returns URL to 
+	 * reduced MMTF files (C-alpha: polypeptides, P polynucleotides, all other groups: all atom, limited precision), 
+	 * otherwise full version (all atoms, full precision)
+	 * @return base URL
+	 */
+	public static String getMmtfBaseUrl(boolean https, boolean reduced) {
+		String url = "http://";
+
+		if (https) {
+			url = "https://";
+		}
+
+		if (reduced) {
+			url = url + MMTF_PATH + "reduced/";
+		} else {
+			url = url + MMTF_PATH + "full/";
+		}
+
+		return url;
+	}
+
+
 
 	/**
-	 * Convert an integer list to an integer array
+	 * Converts an integer list to an integer array
 	 * @param integerList the input list
 	 * @return the output array
 	 */