moved common interfaces from src/ooxml/interfaces-jdk15 to src/java, they do belong there

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@763332 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 359 insertions, 0 deletions

diff --git a/src/java/org/apache/poi/ss/usermodel/Cell.java b/src/java/org/apache/poi/ss/usermodel/Cell.java
new file mode 100644
index 0000000000..aa1e8c3955
--- /dev/null
+++ b/src/java/org/apache/poi/ss/usermodel/Cell.java
@@ -0,0 +1,359 @@
+/* ====================================================================
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+==================================================================== */
+
+package org.apache.poi.ss.usermodel;
+
+import java.util.Calendar;
+import java.util.Date;
+
+/**
+ * High level representation of a cell in a row of a spreadsheet.
+ * <p>
+ * Cells can be numeric, formula-based or string-based (text).  The cell type
+ * specifies this.  String cells cannot conatin numbers and numeric cells cannot
+ * contain strings (at least according to our model).  Client apps should do the
+ * conversions themselves.  Formula cells have the formula string, as well as
+ * the formula result, which can be numeric or string.
+ * </p>
+ * <p>
+ * Cells should have their number (0 based) before being added to a row.
+ * </p>
+ */
+public interface Cell {
+
+    /**
+     * Numeric Cell type (0)
+     * @see #setCellType(int)
+     * @see #getCellType()
+     */
+    public final static int CELL_TYPE_NUMERIC = 0;
+
+    /**
+     * String Cell type (1)
+     * @see #setCellType(int)
+     * @see #getCellType()
+     */
+    public final static int CELL_TYPE_STRING = 1;
+
+    /**
+     * Formula Cell type (2)
+     * @see #setCellType(int)
+     * @see #getCellType()
+     */
+    public final static int CELL_TYPE_FORMULA = 2;
+
+    /**
+     * Blank Cell type (3)
+     * @see #setCellType(int)
+     * @see #getCellType()
+     */
+    public final static int CELL_TYPE_BLANK = 3;
+
+    /**
+     * Boolean Cell type (4)
+     * @see #setCellType(int)
+     * @see #getCellType()
+     */
+    public final static int CELL_TYPE_BOOLEAN = 4;
+
+    /**
+     * Error Cell type (5)
+     * @see #setCellType(int)
+     * @see #getCellType()
+     */
+    public final static int CELL_TYPE_ERROR = 5;
+    
+    /**
+     * Returns column index of this cell
+     *
+     * @return zero-based column index of a column in a sheet.
+     */
+    int getColumnIndex();
+
+    /**
+     * Returns row index of a row in the sheet that contains this cell
+     *
+     * @return zero-based row index of a row in the sheet that contains this cell
+     */
+    int getRowIndex();
+
+    /**
+     * Returns the sheet this cell belongs to
+     *
+     * @return the sheet this cell belongs to
+     */
+    Sheet getSheet();
+
+    /**
+     * Returns the Row this cell belongs to
+     *
+     * @return the Row that owns this cell
+     */
+     Row getRow();
+
+    /**
+     * Set the cells type (numeric, formula or string)
+     *
+     * @throws IllegalArgumentException if the specified cell type is invalid
+     * @see #CELL_TYPE_NUMERIC
+     * @see #CELL_TYPE_STRING
+     * @see #CELL_TYPE_FORMULA
+     * @see #CELL_TYPE_BLANK
+     * @see #CELL_TYPE_BOOLEAN
+     * @see #CELL_TYPE_ERROR
+     */
+    void setCellType(int cellType);
+
+    /**
+     * Return the cell type.
+     *
+     * @return the cell type
+     * @see Cell#CELL_TYPE_BLANK
+     * @see Cell#CELL_TYPE_NUMERIC
+     * @see Cell#CELL_TYPE_STRING
+     * @see Cell#CELL_TYPE_FORMULA
+     * @see Cell#CELL_TYPE_BOOLEAN
+     * @see Cell#CELL_TYPE_ERROR
+     */
+    int getCellType();
+
+    /**
+     * Only valid for formula cells
+     * @return one of ({@link #CELL_TYPE_NUMERIC}, {@link #CELL_TYPE_STRING},
+     *     {@link #CELL_TYPE_BOOLEAN}, {@link #CELL_TYPE_ERROR}) depending
+     * on the cached value of the formula
+     */
+    int getCachedFormulaResultType();
+
+    /**
+     * Set a numeric value for the cell
+     *
+     * @param value  the numeric value to set this cell to.  For formulas we'll set the
+     *        precalculated value, for numerics we'll set its value. For other types we
+     *        will change the cell to a numeric cell and set its value.
+     */
+    void setCellValue(double value);
+
+    /**
+     * Set a boolean value for the cell
+     *
+     * @param value the boolean value to set this cell to.  For formulas we'll set the
+     *        precalculated value, for booleans we'll set its value. For other types we
+     *        will change the cell to a boolean cell and set its value.
+     */
+    void setCellValue(Date value);
+
+    /**
+     * Set a date value for the cell. Excel treats dates as numeric so you will need to format the cell as
+     * a date.
+     * <p>
+     * This will set the cell value based on the Calendar's timezone. As Excel
+     * does not support timezones this means that both 20:00+03:00 and
+     * 20:00-03:00 will be reported as the same value (20:00) even that there
+     * are 6 hours difference between the two times. This difference can be
+     * preserved by using <code>setCellValue(value.getTime())</code> which will
+     * automatically shift the times to the default timezone.
+     * </p>
+     *
+     * @param value  the date value to set this cell to.  For formulas we'll set the
+     *        precalculated value, for numerics we'll set its value. For othertypes we
+     *        will change the cell to a numeric cell and set its value.
+     */
+    void setCellValue(Calendar value);
+
+    /**
+     * Set a rich string value for the cell.
+     *
+     * @param value  value to set the cell to.  For formulas we'll set the formula
+     * string, for String cells we'll set its value.  For other types we will
+     * change the cell to a string cell and set its value.
+     * If value is null then we will change the cell to a Blank cell.
+     */
+    void setCellValue(RichTextString value);
+
+    /**
+     * Set a string value for the cell.
+     *
+     * @param value  value to set the cell to.  For formulas we'll set the formula
+     * string, for String cells we'll set its value.  For other types we will
+     * change the cell to a string cell and set its value.
+     * If value is null then we will change the cell to a Blank cell.
+     */
+    void setCellValue(String value);
+
+    /**
+     * Sets formula for this cell.
+     * <p>
+     * Note, this method only sets the formula string and does not calculate the formula value.
+     * To set the precalculated value use {@link #setCellValue(double)} or {@link #setCellValue(String)}
+     * </p>
+     *
+     * @param formula the formula to set, e.g. <code>SUM(C4:E4)</code>.
+     *  If the argument is <code>null</code> then the current formula is removed.
+     * @throws IllegalArgumentException if the formula is unparsable
+     */
+    void setCellFormula(String formula);
+
+    /**
+     * Return a formula for the cell, for example, <code>SUM(C4:E4)</code>
+     *
+     * @return a formula for the cell
+     * @throws IllegalStateException if the cell type returned by {@link #getCellType()} is not CELL_TYPE_FORMULA
+     */
+    String getCellFormula();
+
+    /**
+     * Get the value of the cell as a number.
+     * <p>
+     * For strings we throw an exception. For blank cells we return a 0.
+     * For formulas or error cells we return the precalculated value;
+     * </p>
+     * @return the value of the cell as a number
+     * @throws IllegalStateException if the cell type returned by {@link #getCellType()} is CELL_TYPE_STRING
+     * @exception NumberFormatException if the cell value isn't a parsable <code>double</code>.
+     * @see DataFormatter for turning this number into a string similar to that which Excel would render this number as.
+     */
+    double getNumericCellValue();
+
+    /**
+     * Get the value of the cell as a date.
+     * <p>
+     * For strings we throw an exception. For blank cells we return a null.
+     * </p>
+     * @return the value of the cell as a date
+     * @throws IllegalStateException if the cell type returned by {@link #getCellType()} is CELL_TYPE_STRING
+     * @exception NumberFormatException if the cell value isn't a parsable <code>double</code>.
+     * @see DataFormatter for formatting  this date into a string similar to how excel does.
+     */
+    Date getDateCellValue();
+
+    /**
+     * Get the value of the cell as a XSSFRichTextString
+     * <p>
+     * For numeric cells we throw an exception. For blank cells we return an empty string.
+     * For formula cells we return the pre-calculated value.
+     * </p>
+     * @return the value of the cell as a XSSFRichTextString
+     */
+    RichTextString getRichStringCellValue();
+
+    /**
+     * Get the value of the cell as a string
+     * <p>
+     * For numeric cells we throw an exception. For blank cells we return an empty string.
+     * For formulaCells that are not string Formulas, we return empty String.
+     * </p>
+     * @return the value of the cell as a string
+     */
+    String getStringCellValue();
+
+    /**
+     * Set a boolean value for the cell
+     *
+     * @param value the boolean value to set this cell to.  For formulas we'll set the
+     *        precalculated value, for booleans we'll set its value. For other types we
+     *        will change the cell to a boolean cell and set its value.
+     */
+     void setCellValue(boolean value);
+
+    /**
+     * Set a error value for the cell
+     *
+     * @param value the error value to set this cell to.  For formulas we'll set the
+     *        precalculated value , for errors we'll set
+     *        its value. For other types we will change the cell to an error
+     *        cell and set its value.
+     * @see FormulaError
+     */
+    void setCellErrorValue(byte value);
+
+    /**
+     * Get the value of the cell as a boolean.
+     * <p>
+     * For strings, numbers, and errors, we throw an exception. For blank cells we return a false.
+     * </p>
+     * @return the value of the cell as a boolean
+     * @throws IllegalStateException if the cell type returned by {@link #getCellType()}
+     *   is not CELL_TYPE_BOOLEAN, CELL_TYPE_BLANK or CELL_TYPE_FORMULA
+     */
+    boolean getBooleanCellValue();
+
+    /**
+     * Get the value of the cell as an error code.
+     * <p>
+     * For strings, numbers, and booleans, we throw an exception.
+     * For blank cells we return a 0.
+     * </p>
+     *
+     * @return the value of the cell as an error code
+     * @throws IllegalStateException if the cell type returned by {@link #getCellType()} isn't CELL_TYPE_ERROR
+     * @see FormulaError for error codes
+     */
+    byte getErrorCellValue();
+
+    /**
+     * Set the style for the cell.  The style should be an CellStyle created/retreived from
+     * the Workbook.
+     *
+     * @param style  reference contained in the workbook.
+     * If the value is null then the style information is removed causing the cell to used the default workbook style.
+     * @see org.apache.poi.ss.usermodel.Workbook#createCellStyle()
+     */
+    void setCellStyle(CellStyle style);
+
+    /**
+     * Return the cell's style.
+     *
+     * @return the cell's style. Always not-null. Default cell style has zero index and can be obtained as
+     * <code>workbook.getCellStyleAt(0)</code>
+     * @see Workbook#getCellStyleAt(short)
+     */
+    CellStyle getCellStyle();
+
+    /**
+     * Sets this cell as the active cell for the worksheet
+     */
+    void setAsActiveCell();
+
+    /**
+     * Assign a comment to this cell
+     *
+     * @param comment comment associated with this cell
+     */
+    void setCellComment(Comment comment);
+
+    /**
+     * Returns comment associated with this cell
+     *
+     * @return comment associated with this cell or <code>null</code> if not found
+     */
+    Comment getCellComment();
+
+    /**
+     * Returns hyperlink associated with this cell
+     *
+     * @return hyperlink associated with this cell or <code>null</code> if not found
+     */
+    Hyperlink getHyperlink();
+
+    /**
+     * Assign a hypelrink to this cell
+     *
+     * @param link hypelrink associated with this cell
+     */
+    void setHyperlink(Hyperlink link);
+}