Commit 4b9eb068 authored by Stephane Dallongeville's avatar Stephane Dallongeville
Browse files

fixed javadoc errors

parent e683a1ec
......@@ -25,46 +25,48 @@ import plugins.adufour.workbooks.Workbooks;
*/
public class FileToWorkbook extends Plugin implements IOBlock
{
VarFile inputFile = new VarFile("input file", null);
VarWorkbook workbook = new VarWorkbook("workbook", (Workbook) null);
VarFile inputFile = new VarFile("input file", null);
VarWorkbook workbook = new VarWorkbook("workbook", (Workbook) null);
@Override
public void run()
{
workbook.setValue(readWorkbook(inputFile.getValue(true)));
}
@Override
public void declareInput(VarList inputMap)
{
inputMap.add("input file", inputFile);
}
@Override
public void declareOutput(VarList outputMap)
{
outputMap.add("workbook", workbook);
}
/**
* Reads the specified file into a workbook. This method will read Excel-compatible (.xls)
* files, but will also read tab-delimited text files. <br/>
* files, but will also read tab-delimited text files. <br>
* Note: tab-delimited text files may contain multiple sheets, if specified as in the following
* example:<br/>
* <code>== sheet 1 ==<br/>
* item1 (tab) item2<br/>
* == sheet 2 ==<br/>
* item3 (tab) item4</code><br/>
* example:<br>
* <code>== sheet 1 ==<br>
* item1 (tab) item2<br>
* == sheet 2 ==<br>
* item3 (tab) item4</code><br>
* (the same convention is followed by
* {@link WorkbookToFile#saveAsText(Workbook, String, MergePolicy)}
*
* @param file
* @return
* input file
* @return the workbook read from input file
*/
public static Workbook readWorkbook(File file)
{
if (!file.exists() || file.isDirectory()) throw new IllegalArgumentException("Cannot read a workbook from " + file.getPath());
if (!file.exists() || file.isDirectory())
throw new IllegalArgumentException("Cannot read a workbook from " + file.getPath());
try
{
FileInputStream fis = new FileInputStream(file);
......@@ -77,26 +79,26 @@ public class FileToWorkbook extends Plugin implements IOBlock
// try text
Workbook wb = Workbooks.createEmptyWorkbook();
Sheet sheet = null;
try
{
BufferedReader reader = new BufferedReader(new FileReader(file));
int rowID = 0;
boolean newLine = false;
while (reader.ready())
{
String line = reader.readLine();
if (line.isEmpty())
{
// remember there is a new line, deal with it later
newLine = true;
continue;
}
// 1) fetch (or create) the sheet
// special case: sheet name saved using FileToWorkbook
if (line.startsWith("== "))
{
......@@ -104,14 +106,14 @@ public class FileToWorkbook extends Plugin implements IOBlock
newLine = false;
String sheetName = line.substring(3, line.indexOf(" =="));
sheet = wb.createSheet(sheetName);
// reset the row
rowID = 0;
// nothing else interesting in this line...
continue;
}
// otherwise, create a (default) empty sheet
if (sheet == null)
{
......@@ -119,18 +121,20 @@ public class FileToWorkbook extends Plugin implements IOBlock
// reset the row
rowID = 0;
}
// 2) add the new line (if any)
if (newLine) sheet.createRow(rowID++);
if (newLine)
sheet.createRow(rowID++);
// 3) Create a new row for the current input
Row row = sheet.createRow(rowID++);
// skip empty lines
if (line.isEmpty()) continue;
if (line.isEmpty())
continue;
int colID = 0;
String[] words = line.split("\t");
for (String word : words)
{
......@@ -149,9 +153,9 @@ public class FileToWorkbook extends Plugin implements IOBlock
colID++;
}
}
reader.close();
return wb;
}
catch (Exception e2)
......
......@@ -99,7 +99,9 @@ public class WorkbookToFile extends Plugin implements IOBlock
* added to the file name if it is not present
*
* @param workbook
* workbook to save
* @param fileName
* file name where to save workbook
* @deprecated Use {@link #saveAsSpreadSheet(Workbook, String, MergePolicy)} instead.
*/
@Deprecated
......@@ -113,7 +115,11 @@ public class WorkbookToFile extends Plugin implements IOBlock
* added to the file name if it is not present
*
* @param workbook
* workbook to save
* @param fileName
* file name where to save workbook
* @param mergePolicy
* indicates if and how the file should be appended
*/
public static void saveAsSpreadSheet(Workbook workbook, String fileName, MergePolicy mergePolicy)
{
......@@ -180,7 +186,9 @@ public class WorkbookToFile extends Plugin implements IOBlock
* added to the file name if it is not present
*
* @param workbook
* workbook to save
* @param fileName
* file name where to save workbook
* @deprecated Use {@link #saveAsText(Workbook, String, MergePolicy)} instead.
*/
@Deprecated
......@@ -192,12 +200,12 @@ public class WorkbookToFile extends Plugin implements IOBlock
/**
* Saves the specified workbook to a spreadsheet file. By default, the ".txt" extension will be
* added to the file name if it is not present. If the workbook contains multiple sheets, they
* will be stored in the text file as in the following example:<br/>
* <code>== sheet 1 ==<br/>
* item1 (tab) item2<br/>
* <br/>
* == sheet 2 ==<br/>
* item3 (tab) item4</code><br/>
* will be stored in the text file as in the following example:<br>
* <code>== sheet 1 ==<br>
* item1 (tab) item2<br>
* <br>
* == sheet 2 ==<br>
* item3 (tab) item4</code><br>
*
* @param workbook
* the workbook to save
......
......@@ -17,8 +17,8 @@ import org.pushingpixels.substance.internal.ui.SubstanceCheckBoxMenuItemUI;
/**
* Persistent version of JXTable's column control button that keeps the pop-up open even after a
* column is clicked (allowing multiple clicks at once). The pop-up will close if the
* ColumnControlButton is pressed again. <br/>
* <br/>
* ColumnControlButton is pressed again. <br>
* <br>
* This code was adapted from the <a
* href="http://www.coding-dude.com/wp/java/custom-columncontrolbutton-java-swing-jxtable/">
* following page</a>.
......
......@@ -231,7 +231,7 @@ public class WorkbookEditor extends SwingVarEditor<Workbook>
/**
* Sets whether the open button should be visible
*
* @param visible
* @param visible visible state
*/
public void setOpenButtonVisible(boolean visible)
{
......@@ -240,6 +240,8 @@ public class WorkbookEditor extends SwingVarEditor<Workbook>
/**
* Sets whether the table editor is read-only, and therefore rejects user input
*
* @param readOnly read only state
*/
public void setReadOnly(boolean readOnly)
{
......
......@@ -15,7 +15,6 @@ import plugins.adufour.vars.gui.VarEditor;
import plugins.adufour.vars.gui.swing.WorkbookEditor;
import plugins.adufour.vars.util.VarException;
import plugins.adufour.workbooks.Workbooks;
import plugins.adufour.workbooks.Workbooks.WorkbookFormat;
public class VarWorkbook extends Var<Workbook>
{
......@@ -23,50 +22,54 @@ public class VarWorkbook extends Var<Workbook>
* Creates a new variable with the workbook read from the specified file
*
* @param name
* the name of the workbook
* the name of the workbook
* @param workbook
* the workbook to work with
* the workbook to work with
*/
public VarWorkbook(String name, Workbook workbook)
{
super(name, Workbook.class, workbook, null);
}
/**
* Creates a new variable with the workbook read from the specified file
*
* @param name
* the name of the workbook
* the name of the workbook
* @param file
* the file to read the workbook from
* the file to read the workbook from
* @throws InvalidFormatException
* if input file format is incorrect
* @throws IOException
* if input file is not found
*/
public VarWorkbook(String name, File file) throws InvalidFormatException, IOException
{
this(name, WorkbookFactory.create(file));
}
/**
* Creates a new variable with a new empty workbook
*
* @param name
* the name of the workbook
* the name of the workbook
* @param firstSheetName
* the name of the first sheet
* the name of the first sheet
*/
public VarWorkbook(String name, String firstSheetName)
{
this(name, Workbooks.createEmptyWorkbook());
getValue().createSheet(firstSheetName);
}
@Override
public VarEditor<Workbook> createVarEditor()
{
WorkbookEditor editor = new WorkbookEditor(this);
return editor;
}
@Override
public VarEditor<Workbook> createVarViewer()
{
......@@ -75,29 +78,31 @@ public class VarWorkbook extends Var<Workbook>
editor.setOpenButtonVisible(false);
return editor;
}
/**
* Save the workbook to disk
*
* @param folder
* the folder on disk where the workbook should be saved (must exist)
* the folder on disk where the workbook should be saved (must exist)
* @param workbookName
* the name of the workbook (without extension)
* the name of the workbook (without extension)
* @throws VarException
* if the workbook is <code>null</code>
* if the workbook is <code>null</code>
* @throws IOException
* if the file cannot be accessed
* if the file cannot be accessed
*/
public void saveToDisk(File folder, String workbookName) throws VarException, IOException
{
if (!folder.isDirectory()) throw new FilerException(folder + "is not a valid folder");
if (!folder.isDirectory())
throw new FilerException(folder + "is not a valid folder");
Workbook wb = getValue(true);
String filename = folder.getPath() + File.separator + workbookName + ".xls";
if (wb instanceof XSSFWorkbook) filename = filename + "x";
if (wb instanceof XSSFWorkbook)
filename = filename + "x";
FileOutputStream out = new FileOutputStream(filename);
wb.write(out);
out.close();
......
......@@ -45,9 +45,9 @@ public class IcySpreadSheet
}
/**
* @param source
* @param sourceColumn
* the index of the row to copy (NB: the first row is at index 0)
* @param target
* @param targetColumn
* the index of the row where the source row will be pasted (NB: the first row is at
* index 0)
*/
......@@ -81,9 +81,9 @@ public class IcySpreadSheet
}
/**
* @param source
* @param sourceRow
* the index of the row to copy (NB: the first row is at index 0)
* @param target
* @param targetRow
* the index of the row where the source row will be pasted (NB: the first row is at
* index 0)
*/
......@@ -209,7 +209,9 @@ public class IcySpreadSheet
/**
* @param row
* row index
* @param column
* column index
* @return the background color of the specified cell
*/
public Color getFillColor(int row, int column)
......@@ -350,7 +352,9 @@ public class IcySpreadSheet
* Sets the fill color of the specified cell
*
* @param row
* row index
* @param column
* column index
* @param color
* the color to assign
*/
......@@ -401,11 +405,13 @@ public class IcySpreadSheet
/**
* Sets the formula for the specified cell. The formula follows the standard Excel-compatible
* syntax with alphanumeric references to other cells (e.g. "=A1*A2"). <br/>
* syntax with alphanumeric references to other cells (e.g. "=A1*A2"). <br>
* NOTE: this method is not responsible for checking the formula for potential syntax errors.
*
* @param row
* row index
* @param column
* column index
* @param formula
* the formula
* @throws FormulaParseException
......@@ -431,7 +437,7 @@ public class IcySpreadSheet
* <li>Any compatible {@link Number} (will be converted to double precision)</li>
* </ul>
* Other unsupported objects will be replaced by their String representation (via
* {@link Object#toString()})<br/>
* {@link Object#toString()})<br>
* NOTE: to assign a formula to this cell, use {@link #setFormula(int, int, String)}.
*
* @param row
......@@ -582,7 +588,7 @@ public class IcySpreadSheet
* the index of the row to fill (Note: the first column is at index 0)
* @param values
* the values to add, separated by commas, or a single array containing the values to
* add.<br/>
* add.<br>
* NB: numbers and string will be recognized as such, any other item will be
* converted to string using {@link Object#toString()}, while <code>null</code>
* values will result in an empty cell
......
......@@ -40,12 +40,12 @@ public class Workbooks extends PluginActionable implements PluginThreaded
*/
public enum WorkbookFormat
{
/** Legacy format (compatible with Excel <= 2004). Limited to 256 columns and 65536 rows */
/** Legacy format (compatible with Excel &lt;= 2004). Limited to 256 columns and 65536 rows */
XLS,
/** Recommended format (compatible with Excel >= 2007) */
/** Recommended format (compatible with Excel &gt;= 2007) */
XLSX;
Workbook createEmptyWorkbook()
{
switch (this)
......@@ -58,29 +58,32 @@ public class Workbooks extends PluginActionable implements PluginThreaded
throw new UnsupportedOperationException("Unknown format: " + toString());
}
}
public String getExtension()
{
return '.' + name().toLowerCase();
}
public static WorkbookFormat getFormat(Workbook workbook)
{
if (workbook instanceof HSSFWorkbook) return XLS;
if (workbook instanceof XSSFWorkbook) return XLSX;
if (workbook instanceof HSSFWorkbook)
return XLS;
if (workbook instanceof XSSFWorkbook)
return XLSX;
throw new IllegalArgumentException("Unknown format for workbook " + workbook);
}
}
private final String defaultTitle = "Icy Workbooks v." + getDescriptor().getVersion().getMajor() + "." + getDescriptor().getVersion().getMinor();
private final String defaultTitle = "Icy Workbooks v." + getDescriptor().getVersion().getMajor() + "."
+ getDescriptor().getVersion().getMinor();
@Override
public void run()
{
show(createEmptyWorkbook(), defaultTitle, true);
}
/**
* @return A new empty workbook using the old compatibility format (XLS).
*/
......@@ -88,12 +91,12 @@ public class Workbooks extends PluginActionable implements PluginThreaded
{
return createEmptyWorkbook(WorkbookFormat.XLSX);
}
/**
* Creates a new (empty) workbook with the specified format
*
* @param format
* the format of the workbook to create (see {@link WorkbookFormat})
* the format of the workbook to create (see {@link WorkbookFormat})
* @return a new (empty) workbook
* @see WorkbookFormat
* @see WorkbookFormat#XLS
......@@ -104,87 +107,90 @@ public class Workbooks extends PluginActionable implements PluginThreaded
workbook.setMissingCellPolicy(Row.MissingCellPolicy.CREATE_NULL_AS_BLANK);
return workbook;
}
/**
* Reads the specified file into a workbook. This method will read Excel-compatible (.xls)
* files, but will also read tab-delimited text files. <br/>
* files, but will also read tab-delimited text files. <br>
* Note: tab-delimited text files may contain multiple sheets, if specified as in the following
* example:<br/>
* <code>== sheet 1 ==<br/>
* item1 (tab) item2<br/>
* == sheet 2 ==<br/>
* item3 (tab) item4</code><br/>
* example:<br>
* <code>== sheet 1 ==<br>
* item1 (tab) item2<br>
* == sheet 2 ==<br>
* item3 (tab) item4</code><br>
* (the same convention is followed by
* {@link WorkbookToFile#saveAsText(Workbook, String, MergePolicy)}
*
* @param filePath
* the path of the file to open
* @return
* the path of the file to open
* @return the workbook read from input file
*/
public static Workbook openWorkbook(String filePath)
{
return openWorkbook(new File(filePath));
}
/**
* Reads the specified file into a workbook. This method will read Excel-compatible (.xls)
* files, but will also read tab-delimited text files. <br/>
* files, but will also read tab-delimited text files. <br>
* Note: tab-delimited text files may contain multiple sheets, if specified as in the following
* example:<br/>
* <code>== sheet 1 ==<br/>
* item1 (tab) item2<br/>
* == sheet 2 ==<br/>
* item3 (tab) item4</code><br/>
* example:<br>
* <code>== sheet 1 ==<br>
* item1 (tab) item2<br>
* == sheet 2 ==<br>
* item3 (tab) item4</code><br>
* (the same convention is followed by
* {@link WorkbookToFile#saveAsText(Workbook, String, MergePolicy)}
*
* @param file
* the file to open
* @return
* the file to open
* @return the workbook read from input file
*/
public static Workbook openWorkbook(File file)
{
return FileToWorkbook.readWorkbook(file);
}
/**
* @param wb
* input {@link Workbook}
* @return The format of this workbook (see the {@link WorkbookFormat} enumeration)
*/
public static WorkbookFormat getFormat(Workbook wb)
{
return WorkbookFormat.getFormat(wb);
}
/**
* Fetches the specified sheet from the specified workbook. The sheet is created if necessary.
* <br/>
* <br>
* NB: If the provided sheet name contains invalid characters, they are automatically replaced
* in order to comply with the workbook format (similarly to the
* {@link #containsSheet(Workbook, String)} method)
*
* @param workbook
* the workbook where the sheet should be fetched (or created)
* the workbook where the sheet should be fetched (or created)
* @param sheetName
* the name of the sheet to fetch or create. Note that the final sheet name may be
* different from the provided name, for instance if the name contains special
* characters
* the name of the sheet to fetch or create. Note that the final sheet name may be
* different from the provided name, for instance if the name contains special
* characters
* @return the sheet with the specified name, wrapped into a {@link IcySpreadSheet} object for
* simplified manipulation
*/
public static IcySpreadSheet getSheet(Workbook workbook, String sheetName)
{
Sheet sheet = workbook.getSheet(sheetName);
if (sheet != null) return new IcySpreadSheet(sheet);
if (sheet != null)
return new IcySpreadSheet(sheet);
sheetName = WorkbookUtil.createSafeSheetName(sheetName);
sheet = workbook.getSheet(sheetName);
return new IcySpreadSheet(sheet != null ? sheet : workbook.createSheet(sheetName));
}
/**