1 | /* ====================================================================
|
---|
2 | Licensed to the Apache Software Foundation (ASF) under one or more
|
---|
3 | contributor license agreements. See the NOTICE file distributed with
|
---|
4 | this work for additional information regarding copyright ownership.
|
---|
5 | The ASF licenses this file to You under the Apache License, Version 2.0
|
---|
6 | (the "License"); you may not use this file except in compliance with
|
---|
7 | the License. You may obtain a copy of the License at
|
---|
8 |
|
---|
9 | http://www.apache.org/licenses/LICENSE-2.0
|
---|
10 |
|
---|
11 | Unless required by applicable law or agreed to in writing, software
|
---|
12 | distributed under the License is distributed on an "AS IS" BASIS,
|
---|
13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
14 | See the License for the specific language governing permissions and
|
---|
15 | limitations under the License.
|
---|
16 | ==================================================================== */
|
---|
17 |
|
---|
18 | package org.apache.poi.ss.usermodel;
|
---|
19 |
|
---|
20 | /**
|
---|
21 | * High level representation of a row of a spreadsheet.
|
---|
22 | */
|
---|
23 | public interface Row {
|
---|
24 |
|
---|
25 | /**
|
---|
26 | * Use this to create new cells within the row and return it.
|
---|
27 | * <p>
|
---|
28 | * The cell that is returned is a {@link Cell#CELL_TYPE_BLANK}. The type can be changed
|
---|
29 | * either through calling <code>setCellValue</code> or <code>setCellType</code>.
|
---|
30 | *
|
---|
31 | * @param column - the column number this cell represents
|
---|
32 | * @return Cell a high level representation of the created cell.
|
---|
33 | * @throws IllegalArgumentException if columnIndex < 0 or greater than the maximum number of supported columns
|
---|
34 | * (255 for *.xls, 1048576 for *.xlsx)
|
---|
35 | */
|
---|
36 | Cell createCell(int column);
|
---|
37 |
|
---|
38 | /**
|
---|
39 | * Use this to create new cells within the row and return it.
|
---|
40 | * <p>
|
---|
41 | * The cell that is returned is a {@link Cell#CELL_TYPE_BLANK}. The type can be changed
|
---|
42 | * either through calling setCellValue or setCellType.
|
---|
43 | *
|
---|
44 | * @param column - the column number this cell represents
|
---|
45 | * @return Cell a high level representation of the created cell.
|
---|
46 | * @throws IllegalArgumentException if columnIndex < 0 or greate than a maximum number of supported columns
|
---|
47 | * (255 for *.xls, 1048576 for *.xlsx)
|
---|
48 | */
|
---|
49 | Cell createCell(int column, int type);
|
---|
50 |
|
---|
51 | /**
|
---|
52 | * Set the row number of this row.
|
---|
53 | *
|
---|
54 | * @param rowNum the row number (0-based)
|
---|
55 | * @throws IllegalArgumentException if rowNum < 0
|
---|
56 | */
|
---|
57 | void setRowNum(int rowNum);
|
---|
58 |
|
---|
59 | /**
|
---|
60 | * Get row number this row represents
|
---|
61 | *
|
---|
62 | * @return the row number (0 based)
|
---|
63 | */
|
---|
64 | int getRowNum();
|
---|
65 |
|
---|
66 | /**
|
---|
67 | * Get the cell representing a given column (logical cell) 0-based. If you
|
---|
68 | * ask for a cell that is not defined....you get a null.
|
---|
69 | *
|
---|
70 | * @param cellnum 0 based column number
|
---|
71 | * @return Cell representing that column or null if undefined.
|
---|
72 | * @see #getCell(int, org.apache.poi.ss.usermodel.Row.MissingCellPolicy)
|
---|
73 | */
|
---|
74 | Cell getCell(int cellnum);
|
---|
75 |
|
---|
76 | /**
|
---|
77 | * Returns the cell at the given (0 based) index, with the specified {@link org.apache.poi.ss.usermodel.Row.MissingCellPolicy}
|
---|
78 | *
|
---|
79 | * @return the cell at the given (0 based) index
|
---|
80 | * @throws IllegalArgumentException if cellnum < 0 or the specified MissingCellPolicy is invalid
|
---|
81 | * @see Row#RETURN_NULL_AND_BLANK
|
---|
82 | * @see Row#RETURN_BLANK_AS_NULL
|
---|
83 | * @see Row#CREATE_NULL_AS_BLANK
|
---|
84 | */
|
---|
85 | Cell getCell(int cellnum, MissingCellPolicy policy);
|
---|
86 |
|
---|
87 | /**
|
---|
88 | * Gets the index of the last cell contained in this row <b>PLUS ONE</b>. The result also
|
---|
89 | * happens to be the 1-based column number of the last cell. This value can be used as a
|
---|
90 | * standard upper bound when iterating over cells:
|
---|
91 | * <pre>
|
---|
92 | * short minColIx = row.getFirstCellNum();
|
---|
93 | * short maxColIx = row.getLastCellNum();
|
---|
94 | * for(short colIx=minColIx; colIx<maxColIx; colIx++) {
|
---|
95 | * Cell cell = row.getCell(colIx);
|
---|
96 | * if(cell == null) {
|
---|
97 | * continue;
|
---|
98 | * }
|
---|
99 | * //... do something with cell
|
---|
100 | * }
|
---|
101 | * </pre>
|
---|
102 | *
|
---|
103 | * @return short representing the last logical cell in the row <b>PLUS ONE</b>,
|
---|
104 | * or -1 if the row does not contain any cells.
|
---|
105 | */
|
---|
106 | short getLastCellNum();
|
---|
107 |
|
---|
108 | /**
|
---|
109 | * Returns the Sheet this row belongs to
|
---|
110 | *
|
---|
111 | * @return the Sheet that owns this row
|
---|
112 | */
|
---|
113 | Sheet getSheet();
|
---|
114 |
|
---|
115 | /**
|
---|
116 | * Used to specify the different possible policies
|
---|
117 | * if for the case of null and blank cells
|
---|
118 | */
|
---|
119 | public static final class MissingCellPolicy {
|
---|
120 | private static int NEXT_ID = 1;
|
---|
121 | public final int id;
|
---|
122 | private MissingCellPolicy() {
|
---|
123 | this.id = NEXT_ID++;
|
---|
124 | }
|
---|
125 | }
|
---|
126 | /** Missing cells are returned as null, Blank cells are returned as normal */
|
---|
127 | public static final MissingCellPolicy RETURN_NULL_AND_BLANK = new MissingCellPolicy();
|
---|
128 | /** Missing cells are returned as null, as are blank cells */
|
---|
129 | public static final MissingCellPolicy RETURN_BLANK_AS_NULL = new MissingCellPolicy();
|
---|
130 | /** A new, blank cell is created for missing cells. Blank cells are returned as normal */
|
---|
131 | public static final MissingCellPolicy CREATE_NULL_AS_BLANK = new MissingCellPolicy();
|
---|
132 | }
|
---|