add Gzip support to file selectors

Add Gzip support for the UI file selection classes. #91
- FileSelection: Specifically, the extension-based single file selection was adjusted to add support for ignoring or including files with a ".gz" extension.
- ExtensionFileFilter: add a stripExtension method that works on String-type filenames
- decorate both classes with JavaDocs

Author: owlang

src/util/ExtensionFileFilter.java

@@ -5,27 +5,48 @@
 
 import javax.swing.filechooser.FileFilter;
 
+/**
+ * Filters files such as BAI, BAM, BED, CDT, FASTA, FA, GFF, TAB for the FileSelection tool base on the extension of the filename. Also includes file extension parsing utilities used across all ScriptManager classes (especially for creating default filenames).
+ * 
+ * @author William KM Lai
+ * @see util.FileSelection
+ *
+ */
 public class ExtensionFileFilter extends FileFilter{
-	//Filters files such as BAI, BAM, BED, CDT, FASTA, FA, GFF, TAB
-		
+
 	private String ext = "";
 	private String ext2 = "";
 	private String ext3 = "";
 	private boolean includeGZ = false;
-	
+
+	/**
+	 * Create file filter for the given file extension. 
+	 * If ExtensionFileFilter is instantiated with "fa", file extensions "fasta" and "fsa" are set to be equivalent.
+	 * If ExtensionFileFilter is instantiated with "gff", file extensions "gtf" and "gff3" are set to be equivalent.
+	 * 
+	 * @param filter file extension to filter by (see notes on "fa" and "gff").
+	 */
 	public ExtensionFileFilter(String filter) {
 		ext = filter;
 		if(ext.equals("fa")) { ext2 = "fasta"; ext3 = "fsa"; }
 		if(ext.equals("gff")) { ext2 = "gtf"; ext3 = "gff3"; }
 	}
-	
+
+	/**
+	 * Create file filter for the given file extension with option to ignore or include ".gz" extensions. 
+	 * If ExtensionFileFilter is instantiated with "fa", file extensions "fasta" and "fsa" are set to be equivalent.
+	 * If ExtensionFileFilter is instantiated with "gff", file extensions "gtf" and "gff3" are set to be equivalent.
+	 * 
+	 * @param filter file extension to filter by (see notes on "fa" and "gff").
+	 * @param gz whether or not to ignore the ".gz" extension (e.g. if gz=true and filter="bed", then "XXX.bed.gz" will pass the filter, "XXX.bed" will pass the filter, but "XXX.gff" will NOT pass the filter).
+	 */
 	public ExtensionFileFilter(String filter, boolean gz) {
 		ext = filter;
 		if(ext.equals("fa")) { ext2 = "fasta"; ext3 = "fsa"; }
 		if(ext.equals("gff")) { ext2 = "gtf"; ext3 = "gff3"; }
 		includeGZ = gz;
 	}
-	
+
 	public boolean accept(File f) {
 		if (f.isDirectory()) return true;
 		String extension = includeGZ ? getExtensionIgnoreGZ(f) : getExtension(f);
@@ -38,7 +59,13 @@ public boolean accept(File f) {
 		}
 		return false;
 	}
-	
+
+	/**
+	 * Get the extension string from a File object.
+	 * 
+	 * @param f the input file to get the extension for
+	 * @return the file extension string (without "." char)
+	 */
 	public static String getExtension(File f) {
         String ext = null;
         String s = f.getName();
@@ -48,7 +75,13 @@ public static String getExtension(File f) {
         }
         return ext;
     }
-	
+
+	/**
+	 * Get the extension string from a File object, ignoring ".gz" extension if present and searching for next extension.
+	 * 
+	 * @param f the input file to get the extension for
+	 * @return the file extension string (without "." char)
+	 */
 	public static String getExtensionIgnoreGZ(File f) {
 		String ext = null;
 		String s = f.getName();
@@ -65,6 +98,15 @@ public static String getExtensionIgnoreGZ(File f) {
 		return ext;
 	}
 
+	/**
+	 * Get the filename without the last extension (tokenize filename by "." char and pull off last "." character and last token. If no "." characters, return the whole filename)
+	 * e.g. f="blahblah.fa" returns "blahblah"
+	 * e.g. f="oompaloompa" returns "oompaloompa"
+	 * 
+	 * @param f the File to strip an extension from
+	 * @return string of filename with extension stripped away
+	 * @throws IOException
+	 */
 	public static String stripExtension(File f) throws IOException {
 		String[] name = f.getName().split("\\.");
 		String NEWNAME = name[0];
@@ -74,6 +116,17 @@ public static String stripExtension(File f) throws IOException {
 		return(NEWNAME);
 	}
 
+	/**
+	 * Get the string without the last extension, ignoring any ".gz" extensions (tokenize strings by "." char and pull off last "." character and last token. If no "." characters, return the whole filename)
+	 * e.g. f="blahblah.fa" returns "blahblah"
+	 * e.g. f="oompaloompa" returns "oompaloompa"
+	 * e.g. f="blahblah.fa.gz" returns "blahblah"
+	 * e.g. f="oompaloompa.gz" returns "oompaloompa"
+	 * 
+	 * @param f the File to strip an extension from
+	 * @return string of filename with extension stripped away
+	 * @throws IOException
+	 */
 	public static String stripExtensionIgnoreGZ(File f) throws IOException {
 		String NEWNAME = f.getName();
 		if (NEWNAME.endsWith(".gz")) { NEWNAME = NEWNAME.substring(0, NEWNAME.length()-3); }
@@ -83,7 +136,31 @@ public static String stripExtensionIgnoreGZ(File f) throws IOException {
 		}
 		return(NEWNAME);
 	}
-	
+
+	/**
+	 * Get the string without the last extension (tokenize strings by "." char and pull off last "." character and last token. If no "." characters, return the whole filename)
+	 * e.g. f="blahblah.fa" returns "blahblah"
+	 * e.g. f="oompaloompa" returns "oompaloompa"
+	 * 
+	 * @param f the String to strip an extension from
+	 * @return string of filename with extension stripped away
+	 */
+	public static String stripExtension(String f) {
+		String[] name = f.split("\\.");
+		String NEWNAME = name[0];
+		for(int x = 1; x < name.length-1; x++) {
+			NEWNAME += ("." + name[x]);
+		}
+		return(NEWNAME);
+	}
+
+	/**
+	 * Get the string of the cannonical filepath without the last extension. Return every character in the path until the last instance of "." character (not including ".").
+	 * e.g. f="/parent/directory/blahblah.fa" returns "/parent/directory/blahblah"
+	 * 
+	 * @param f the String to strip an extension from
+	 * @return string of filename with extension stripped away
+	 */
 	public static String stripExtensionPath(File f) throws IOException {
 		String NAME = f.getCanonicalPath();
 		return(NAME.substring(0, NAME.lastIndexOf('.')));

src/util/FileSelection.java

@@ -4,8 +4,20 @@
 
 import javax.swing.JFileChooser;
 
+/**
+ * Various kinds of file selectors used by the window_interface objects to restrict user input selection options.
+ * 
+ * @author William KM Lai
+ *
+ */
 public class FileSelection {
-	
+
+	/**
+	 * Generic multi-file FileSelector without extension restrictions (commonly TAB-delimited file formats like matrix/table data).
+	 * 
+	 * @param fc
+	 * @return array of File objects from selector UI
+	 */
 	public static File[] getGenericFiles(JFileChooser fc){
 		fc.setFileSelectionMode(JFileChooser.FILES_ONLY);
 		fc.setMultiSelectionEnabled(true);
@@ -18,7 +30,13 @@ public static File[] getGenericFiles(JFileChooser fc){
 		}
 		return Files;
 	}
-	
+
+	/**
+	 * Generic single-file FileSelector for retrieving directories.
+	 * 
+	 * @param fc
+	 * @return a directory file
+	 */
 	public static File getOutputDir(JFileChooser fc) {
 		fc.setDialogTitle("Output Directory");
 		fc.setFileSelectionMode(JFileChooser.DIRECTORIES_ONLY);
@@ -29,9 +47,26 @@ public static File getOutputDir(JFileChooser fc) {
 			return null;
 		}	
 	}
-	
+
+	/**
+	 * Extension-based single-file FileSelector for retrieving a single file with a specific extension.
+	 * @param fc
+	 * @param ext the extension to restrict file selection options by
+	 * @return a single file with a specific extension (see "ext")
+	 */
 	public static File getFile(JFileChooser fc, String ext){
-		fc.setFileFilter(new ExtensionFileFilter(ext));
+		return getFile(fc, ext, false);
+	}
+
+	/**
+	 * Extension-based single-file FileSelector for retrieving a single file with a specific extension where ignoring ".gz" extensions can be toggled.
+	 * @param fc
+	 * @param ext the extension to restrict file selection options by
+	 * @param includeGZ true value means ignore the ".gz" if present when checking the extension
+	 * @return a single file with a specific extension (see "ext")
+	 */
+	public static File getFile(JFileChooser fc, String ext, boolean includeGZ){
+		fc.setFileFilter(new ExtensionFileFilter(ext,includeGZ));
 		fc.setFileSelectionMode(JFileChooser.FILES_ONLY);
 		fc.setMultiSelectionEnabled(false);
 		fc.setSelectedFile(new File(""));
@@ -43,11 +78,24 @@ public static File getFile(JFileChooser fc, String ext){
 		}
 		return Files;
 	}
-	
+
+	/**
+	 * Extension-based multi-file FileSelector for retrieving a set of files with a specific extension.
+	 * @param fc
+	 * @param ext the extension to restrict file selection options by
+	 * @return a list of files with a specific extension (see "ext")
+	 */
 	public static File[] getFiles(JFileChooser fc, String ext){
 		return getFiles(fc, ext, false);
 	}
 
+	/**
+	 * Extension-based multi-file FileSelector for retrieving a set of files with a specific extension where ignoring ".gz" extensions can be toggled.
+	 * @param fc
+	 * @param ext the extension to restrict file selection options by
+	 * @param includeGZ true value means ignore the ".gz" if present when checking the extension
+	 * @return a list of files with a specific extension (see "ext")
+	 */
 	public static File[] getFiles(JFileChooser fc, String ext, boolean includeGZ){
 		fc.setFileFilter(new ExtensionFileFilter(ext,includeGZ));
 		fc.setFileSelectionMode(JFileChooser.FILES_ONLY);