javadocs fixes (jdk8)

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1751387 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Andreas Beeker 2016-07-04 23:45:19 +00:00
parent e4d673ddc3
commit 3ef17caad7
14 changed files with 183 additions and 37 deletions

View File

@ -32,6 +32,10 @@ public final class RecordStream {
/**
* Creates a RecordStream bounded by startIndex and endIndex
*
* @param inputList the list to iterate over
* @param startIndex the start index within the list
* @param endIx the end index within the list, which is the index of the end element + 1
*/
public RecordStream(List<Record> inputList, int startIndex, int endIx) {
_list = inputList;

View File

@ -43,6 +43,8 @@ public final class RowBlocksReader {
/**
* Also collects any loose MergeCellRecords and puts them in the supplied
* mergedCellsTable
*
* @param rs the record stream
*/
public RowBlocksReader(RecordStream rs) {
List<Record> plainRecords = new ArrayList<Record>();

View File

@ -18,7 +18,6 @@
package org.apache.poi.hssf.record;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import org.apache.poi.ddf.DefaultEscherRecordFactory;
@ -32,9 +31,6 @@ import org.apache.poi.hssf.util.LazilyConcatenatedByteArray;
/**
* The escher container record is used to hold escher records. It is abstract and
* must be subclassed for maximum benefit.
*
* @author Glen Stampoultzis (glens at apache.org)
* @author Michael Zalewski (zalewski at optonline.net)
*/
public abstract class AbstractEscherHolderRecord extends Record implements Cloneable {
private static boolean DESERIALISE;
@ -46,8 +42,8 @@ public abstract class AbstractEscherHolderRecord extends Record implements Clone
}
}
private List<EscherRecord> escherRecords;
private LazilyConcatenatedByteArray rawDataContainer = new LazilyConcatenatedByteArray();
private final List<EscherRecord> escherRecords;
private final LazilyConcatenatedByteArray rawDataContainer = new LazilyConcatenatedByteArray();
public AbstractEscherHolderRecord()
{
@ -85,6 +81,7 @@ public abstract class AbstractEscherHolderRecord extends Record implements Clone
}
}
@Override
public String toString()
{
StringBuffer buffer = new StringBuffer();
@ -93,9 +90,7 @@ public abstract class AbstractEscherHolderRecord extends Record implements Clone
buffer.append('[' + getRecordName() + ']' + nl);
if (escherRecords.size() == 0)
buffer.append("No Escher Records Decoded" + nl);
for ( Iterator<EscherRecord> iterator = escherRecords.iterator(); iterator.hasNext(); )
{
EscherRecord r = iterator.next();
for (EscherRecord r : escherRecords) {
buffer.append(r.toString());
}
buffer.append("[/" + getRecordName() + ']' + nl);
@ -105,6 +100,7 @@ public abstract class AbstractEscherHolderRecord extends Record implements Clone
protected abstract String getRecordName();
@Override
public int serialize(int offset, byte[] data)
{
LittleEndian.putShort( data, 0 + offset, getSid() );
@ -121,14 +117,13 @@ public abstract class AbstractEscherHolderRecord extends Record implements Clone
LittleEndian.putShort(data, 2 + offset, (short)(getRecordSize() - 4));
int pos = offset + 4;
for ( Iterator<EscherRecord> iterator = escherRecords.iterator(); iterator.hasNext(); )
{
EscherRecord r = iterator.next();
for (EscherRecord r : escherRecords) {
pos += r.serialize( pos, data, new NullEscherSerializationListener() );
}
return getRecordSize();
}
@Override
public int getRecordSize() {
byte[] rawData = getRawData();
if (escherRecords.size() == 0 && rawData != null) {
@ -136,9 +131,7 @@ public abstract class AbstractEscherHolderRecord extends Record implements Clone
return rawData.length;
}
int size = 0;
for ( Iterator<EscherRecord> iterator = escherRecords.iterator(); iterator.hasNext(); )
{
EscherRecord r = iterator.next();
for (EscherRecord r : escherRecords) {
size += r.getRecordSize();
}
return size;
@ -146,6 +139,7 @@ public abstract class AbstractEscherHolderRecord extends Record implements Clone
@Override
public abstract short getSid();
@Override
@ -177,10 +171,11 @@ public abstract class AbstractEscherHolderRecord extends Record implements Clone
* If we have a EscherContainerRecord as one of our
* children (and most top level escher holders do),
* then return that.
*
* @return the EscherContainerRecord or {@code null} if no child is a container record
*/
public EscherContainerRecord getEscherContainer() {
for(Iterator<EscherRecord> it = escherRecords.iterator(); it.hasNext();) {
EscherRecord er = it.next();
for (EscherRecord er : escherRecords) {
if(er instanceof EscherContainerRecord) {
return (EscherContainerRecord)er;
}
@ -192,22 +187,25 @@ public abstract class AbstractEscherHolderRecord extends Record implements Clone
* Descends into all our children, returning the
* first EscherRecord with the given id, or null
* if none found
*
* @param id the record to look for
*
* @return the record or {@code null} if it can't be found
*/
public EscherRecord findFirstWithId(short id) {
return findFirstWithId(id, getEscherRecords());
}
private EscherRecord findFirstWithId(short id, List<EscherRecord> records) {
// Check at our level
for(Iterator<EscherRecord> it = records.iterator(); it.hasNext();) {
EscherRecord r = it.next();
for (EscherRecord r : records) {
if(r.getRecordId() == id) {
return r;
}
}
// Then check our children in turn
for(Iterator<EscherRecord> it = records.iterator(); it.hasNext();) {
EscherRecord r = it.next();
for (EscherRecord r : records) {
if(r.isContainerRecord()) {
EscherRecord found = findFirstWithId(id, r.getChildRecords());
if(found != null) {
@ -229,6 +227,8 @@ public abstract class AbstractEscherHolderRecord extends Record implements Clone
/**
* Big drawing group records are split but it's easier to deal with them
* as a whole group so we need to join them together.
*
* @param record the record data to concatenate to the end
*/
public void join( AbstractEscherHolderRecord record )
{

View File

@ -20,13 +20,21 @@ public interface BiffHeaderInput {
/**
* Read an unsigned short from the stream without decrypting
*
* @return the record sid
*/
int readRecordSID();
/**
* Read an unsigned short from the stream without decrypting
*
* @return the data size
*/
int readDataSize();
/**
* @return the available bytes
*/
int available();
}

View File

@ -33,9 +33,7 @@ import org.apache.poi.ss.util.WorkbookUtil;
* Description: Defines a sheet within a workbook. Basically stores the sheet name
* and tells where the Beginning of file record is within the HSSF
* file. <P>
* REFERENCE: PG 291 Microsoft Excel 97 Developer's Kit (ISBN: 1-57231-498-2)<P>
* @author Andrew C. Oliver (acoliver at apache dot org)
* @author Sergei Kozello (sergeikozello at mail.ru)
* REFERENCE: PG 291 Microsoft Excel 97 Developer's Kit (ISBN: 1-57231-498-2)
*/
public final class BoundSheetRecord extends StandardRecord {
public final static short sid = 0x0085;
@ -58,6 +56,8 @@ public final class BoundSheetRecord extends StandardRecord {
*
* UNICODE: sid + len + bof + flags + len(str) + unicode + str 2 + 2 + 4 + 2 +
* 1 + 1 + 2 * len(str)
*
* @param in the record stream to read from
*/
public BoundSheetRecord(RecordInputStream in) {
field_1_position_of_BOF = in.readInt();
@ -154,6 +154,8 @@ public final class BoundSheetRecord extends StandardRecord {
/**
* Is the sheet hidden? Different from very hidden
*
* @return {@code true} if hidden
*/
public boolean isHidden() {
return hiddenFlag.isSet(field_2_option_flags);
@ -161,6 +163,8 @@ public final class BoundSheetRecord extends StandardRecord {
/**
* Is the sheet hidden? Different from very hidden
*
* @param hidden {@code true} if hidden
*/
public void setHidden(boolean hidden) {
field_2_option_flags = hiddenFlag.setBoolean(field_2_option_flags, hidden);
@ -168,6 +172,8 @@ public final class BoundSheetRecord extends StandardRecord {
/**
* Is the sheet very hidden? Different from (normal) hidden
*
* @return {@code true} if very hidden
*/
public boolean isVeryHidden() {
return veryHiddenFlag.isSet(field_2_option_flags);
@ -175,6 +181,8 @@ public final class BoundSheetRecord extends StandardRecord {
/**
* Is the sheet very hidden? Different from (normal) hidden
*
* @param veryHidden {@code true} if very hidden
*/
public void setVeryHidden(boolean veryHidden) {
field_2_option_flags = veryHiddenFlag.setBoolean(field_2_option_flags, veryHidden);
@ -183,6 +191,10 @@ public final class BoundSheetRecord extends StandardRecord {
/**
* Converts a List of {@link BoundSheetRecord}s to an array and sorts by the position of their
* BOFs.
*
* @param boundSheetRecords the boundSheetRecord list to arrayify
*
* @return the sorted boundSheetRecords
*/
public static BoundSheetRecord[] orderByBofPosition(List<BoundSheetRecord> boundSheetRecords) {
BoundSheetRecord[] bsrs = new BoundSheetRecord[boundSheetRecords.size()];
@ -190,6 +202,7 @@ public final class BoundSheetRecord extends StandardRecord {
Arrays.sort(bsrs, BOFComparator);
return bsrs;
}
private static final Comparator<BoundSheetRecord> BOFComparator = new Comparator<BoundSheetRecord>() {
public int compare(BoundSheetRecord bsr1, BoundSheetRecord bsr2) {

View File

@ -97,14 +97,27 @@ public final class CFRule12Record extends CFRuleBase implements FutureRecord, Cl
/**
* Creates a new comparison operation rule
*
* @param sheet the sheet
* @param formulaText the first formula text
*
* @return a new comparison operation rule
*/
public static CFRule12Record create(HSSFSheet sheet, String formulaText) {
Ptg[] formula1 = parseFormula(formulaText, sheet);
return new CFRule12Record(CONDITION_TYPE_FORMULA, ComparisonOperator.NO_COMPARISON,
formula1, null, null);
}
/**
* Creates a new comparison operation rule
*
* @param sheet the sheet
* @param comparisonOperation the comparison operation
* @param formulaText1 the first formula text
* @param formulaText2 the second formula text
*
* @return a new comparison operation rule
*/
public static CFRule12Record create(HSSFSheet sheet, byte comparisonOperation,
String formulaText1, String formulaText2) {
@ -113,8 +126,17 @@ public final class CFRule12Record extends CFRuleBase implements FutureRecord, Cl
return new CFRule12Record(CONDITION_TYPE_CELL_VALUE_IS, comparisonOperation,
formula1, formula2, null);
}
/**
* Creates a new comparison operation rule
*
* @param sheet the sheet
* @param comparisonOperation the comparison operation
* @param formulaText1 the first formula text
* @param formulaText2 the second formula text
* @param formulaTextScale the scale to apply for the comparison
*
* @return a new comparison operation rule
*/
public static CFRule12Record create(HSSFSheet sheet, byte comparisonOperation,
String formulaText1, String formulaText2, String formulaTextScale) {
@ -124,8 +146,14 @@ public final class CFRule12Record extends CFRuleBase implements FutureRecord, Cl
return new CFRule12Record(CONDITION_TYPE_CELL_VALUE_IS, comparisonOperation,
formula1, formula2, formula3);
}
/**
* Creates a new Data Bar formatting
*
* @param sheet the sheet
* @param color the data bar color
*
* @return a new Data Bar formatting
*/
public static CFRule12Record create(HSSFSheet sheet, ExtendedColor color) {
CFRule12Record r = new CFRule12Record(CONDITION_TYPE_DATA_BAR,
@ -145,8 +173,14 @@ public final class CFRule12Record extends CFRuleBase implements FutureRecord, Cl
return r;
}
/**
* Creates a new Icon Set / Multi-State formatting
*
* @param sheet the sheet
* @param iconSet the icon set
*
* @return a new Icon Set / Multi-State formatting
*/
public static CFRule12Record create(HSSFSheet sheet, IconSet iconSet) {
Threshold[] ts = new Threshold[iconSet.num];
@ -161,8 +195,13 @@ public final class CFRule12Record extends CFRuleBase implements FutureRecord, Cl
imf.setThresholds(ts);
return r;
}
/**
* Creates a new Color Scale / Color Gradient formatting
*
* @param sheet the sheet
*
* @return a new Color Scale / Color Gradient formatting
*/
public static CFRule12Record createColorScale(HSSFSheet sheet) {
int numPoints = 3;

View File

@ -139,7 +139,12 @@ public abstract class CFRuleBase extends StandardRecord implements Cloneable {
private Formula formula1;
private Formula formula2;
/** Creates new CFRuleRecord */
/**
* Creates new CFRuleRecord
*
* @param conditionType the condition type
* @param comparisonOperation the comparison operation
*/
protected CFRuleBase(byte conditionType, byte comparisonOperation) {
setConditionType(conditionType);
setComparisonOperation(comparisonOperation);

View File

@ -59,6 +59,11 @@ public final class CFRuleRecord extends CFRuleBase implements Cloneable {
/**
* Creates a new comparison operation rule
*
* @param sheet the sheet
* @param formulaText the formula text
*
* @return a new comparison operation rule
*/
public static CFRuleRecord create(HSSFSheet sheet, String formulaText) {
Ptg[] formula1 = parseFormula(formulaText, sheet);
@ -67,6 +72,13 @@ public final class CFRuleRecord extends CFRuleBase implements Cloneable {
}
/**
* Creates a new comparison operation rule
*
* @param sheet the sheet
* @param comparisonOperation the comparison operation
* @param formulaText1 the first formula text
* @param formulaText2 the second formula text
*
* @return a new comparison operation rule
*/
public static CFRuleRecord create(HSSFSheet sheet, byte comparisonOperation,
String formulaText1, String formulaText2) {
@ -87,6 +99,7 @@ public final class CFRuleRecord extends CFRuleBase implements Cloneable {
setFormula2(Formula.read(field_4_formula2_len, in));
}
@Override
public short getSid() {
return sid;
}
@ -98,6 +111,7 @@ public final class CFRuleRecord extends CFRuleBase implements Cloneable {
*
* @param out the stream to write to
*/
@Override
public void serialize(LittleEndianOutput out) {
int formula1Len=getFormulaSize(getFormula1());
int formula2Len=getFormulaSize(getFormula2());
@ -113,12 +127,14 @@ public final class CFRuleRecord extends CFRuleBase implements Cloneable {
getFormula2().serializeTokens(out);
}
@Override
protected int getDataSize() {
return 6 + getFormattingBlockSize() +
getFormulaSize(getFormula1())+
getFormulaSize(getFormula2());
}
@Override
public String toString() {
StringBuffer buffer = new StringBuffer();
buffer.append("[CFRULE]\n");

View File

@ -23,8 +23,6 @@ import org.apache.poi.util.LittleEndianOutput;
/**
* Base class for all cell value records (implementors of {@link CellValueRecordInterface}).
* Subclasses are expected to manage the cell data values (of various types).
*
* @author Josh Micich
*/
public abstract class CellRecord extends StandardRecord implements CellValueRecordInterface {
private int _rowIndex;
@ -41,10 +39,12 @@ public abstract class CellRecord extends StandardRecord implements CellValueReco
_formatIndex = in.readUShort();
}
@Override
public final void setRow(int row) {
_rowIndex = row;
}
@Override
public final void setColumn(short col) {
_columnIndex = col;
}
@ -55,14 +55,17 @@ public abstract class CellRecord extends StandardRecord implements CellValueReco
* @see org.apache.poi.hssf.record.ExtendedFormatRecord
* @param xf index to the XF record
*/
@Override
public final void setXFIndex(short xf) {
_formatIndex = xf;
}
@Override
public final int getRow() {
return _rowIndex;
}
@Override
public final short getColumn() {
return (short) _columnIndex;
}
@ -73,6 +76,7 @@ public abstract class CellRecord extends StandardRecord implements CellValueReco
* @see org.apache.poi.hssf.record.ExtendedFormatRecord
* @return index to the XF record
*/
@Override
public final short getXFIndex() {
return (short) _formatIndex;
}
@ -96,16 +100,22 @@ public abstract class CellRecord extends StandardRecord implements CellValueReco
* Append specific debug info (used by {@link #toString()} for the value
* contained in this record. Trailing new-line should not be appended
* (superclass does that).
*
* @param sb the StringBuilder to write to
*/
protected abstract void appendValueText(StringBuilder sb);
/**
* Gets the debug info BIFF record type name (used by {@link #toString()}.
*
* @return the record type name
*/
protected abstract String getRecordName();
/**
* writes out the value data for this cell record
*
* @param out the output
*/
protected abstract void serializeValue(LittleEndianOutput out);

View File

@ -195,7 +195,9 @@ public final class ColumnInfoRecord extends StandardRecord implements Cloneable
}
/**
* @return <code>true</code> if the format, options and column width match
* @param other the format to match with
*
* @return {@code true} if the format, options and column width match
*/
public boolean formatMatches(ColumnInfoRecord other) {
if (_xfIndex != other._xfIndex) {

View File

@ -91,6 +91,7 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
field_6_reserved3 = in.readInt();
}
@Override
public String toString()
{
StringBuffer buffer = new StringBuffer();
@ -129,6 +130,7 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
return buffer.toString();
}
@Override
public void serialize(LittleEndianOutput out) {
out.writeShort(sid);
@ -142,10 +144,14 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
out.writeInt(field_6_reserved3);
}
protected int getDataSize() {
@Override
protected int getDataSize() {
return 2 + 2 + 2 + 4 + 4 + 4;
}
/**
* @return the record sid
*/
public short getSid()
{
return sid;
@ -250,6 +256,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Get the object id field for the CommonObjectData record.
*
* @return the object id field
*/
public int getObjectId()
{
@ -258,6 +266,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Set the object id field for the CommonObjectData record.
*
* @param field_2_objectId the object id field
*/
public void setObjectId(int field_2_objectId)
{
@ -266,6 +276,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Get the option field for the CommonObjectData record.
*
* @return the option field
*/
public short getOption()
{
@ -274,6 +286,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Set the option field for the CommonObjectData record.
*
* @param field_3_option the option field
*/
public void setOption(short field_3_option)
{
@ -282,6 +296,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Get the reserved1 field for the CommonObjectData record.
*
* @return the reserved1 field
*/
public int getReserved1()
{
@ -290,6 +306,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Set the reserved1 field for the CommonObjectData record.
*
* @param field_4_reserved1 the reserved1 field
*/
public void setReserved1(int field_4_reserved1)
{
@ -298,6 +316,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Get the reserved2 field for the CommonObjectData record.
*
* @return the reserved2 field
*/
public int getReserved2()
{
@ -306,6 +326,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Set the reserved2 field for the CommonObjectData record.
*
* @param field_5_reserved2 the reserved2 field
*/
public void setReserved2(int field_5_reserved2)
{
@ -314,6 +336,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Get the reserved3 field for the CommonObjectData record.
*
* @return the reserved3 field
*/
public int getReserved3()
{
@ -322,6 +346,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Set the reserved3 field for the CommonObjectData record.
*
* @param field_6_reserved3 the reserved3 field
*/
public void setReserved3(int field_6_reserved3)
{
@ -331,6 +357,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Sets the locked field value.
* true if object is locked when sheet has been protected
*
* @param value {@code true} if object is locked when sheet has been protected
*/
public void setLocked(boolean value)
{
@ -349,6 +377,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Sets the printable field value.
* object appears when printed
*
* @param value {@code true} if object appears when printed
*/
public void setPrintable(boolean value)
{
@ -367,6 +397,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Sets the autofill field value.
* whether object uses an automatic fill style
*
* @param value {@code true} if object uses an automatic fill style
*/
public void setAutofill(boolean value)
{
@ -385,6 +417,8 @@ public final class CommonObjectDataSubRecord extends SubRecord implements Clonea
/**
* Sets the autoline field value.
* whether object uses an automatic line style
*
* @param value {@code true} if object uses an automatic line style
*/
public void setAutoline(boolean value)
{

View File

@ -20,18 +20,20 @@ package org.apache.poi.hssf.record;
/**
* The margin interface is a parent used to define left, right, top and bottom margins.
* This allows much of the code to be generic when it comes to handling margins.
*
* @author Shawn Laubach (slaubach at apache dot org)
*/
public interface Margin {
// TODO - introduce MarginBaseRecord
/**
* Get the margin field for the Margin.
*
* @return the margin
*/
public double getMargin();
/**
* Set the margin field for the Margin.
*
* @param field_1_margin the margin
*/
public void setMargin(double field_1_margin);
}

View File

@ -24,8 +24,6 @@ import org.apache.poi.util.LittleEndianOutput;
/**
* Common base class for {@link SharedFormulaRecord}, {@link ArrayRecord} and
* {@link TableRecord} which are have similarities.
*
* @author Josh Micich
*/
public abstract class SharedValueRecordBase extends StandardRecord {
@ -86,8 +84,12 @@ public abstract class SharedValueRecordBase extends StandardRecord {
}
/**
* @return <code>true</code> if (rowIx, colIx) is within the range ({@link #getRange()})
* of this shared value object.
* @param rowIx the row index
* @param colIx the column index
*
* @return {@code true} if (rowIx, colIx) is within the range of this shared value object.
*
* @see #getRange()
*/
public final boolean isInRange(int rowIx, int colIx) {
CellRangeAddress8Bit r = _range;
@ -97,8 +99,15 @@ public abstract class SharedValueRecordBase extends StandardRecord {
&& r.getLastColumn() >= colIx;
}
/**
* @return <code>true</code> if (rowIx, colIx) describes the first cell in this shared value
* object's range ({@link #getRange()})
* @return {@code true} if (rowIx, colIx) describes the first cell in this shared value
* object's range
*
* @param rowIx the row index
* @param colIx the column index
*
* @return {@code true} if its the first cell in this shared value object range
*
* @see #getRange()
*/
public final boolean isFirstCell(int rowIx, int colIx) {
CellRangeAddress8Bit r = getRange();

View File

@ -60,6 +60,8 @@ public abstract class StandardRecord extends Record {
* {@link org.apache.poi.hssf.record.Record#getRecordSize()}} minus four
* ( record header consisting of a 'ushort sid' and 'ushort reclength' has already been written
* by their superclass).
*
* @param out the output object
*/
protected abstract void serialize(LittleEndianOutput out);
}