| blob | e74b6f0901fede7219b9207c7e86818e17debfaf |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3 ====================================================================
4 Licensed to the Apache Software Foundation (ASF) under one or more
5 contributor license agreements. See the NOTICE file distributed with
6 this work for additional information regarding copyright ownership.
7 The ASF licenses this file to You under the Apache License, Version 2.0
8 (the "License"); you may not use this file except in compliance with
9 the License. You may obtain a copy of the License at
11 http://www.apache.org/licenses/LICENSE-2.0
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18 ====================================================================
19 -->
20 <!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN" "./dtd/faq-v11.dtd">
22 <faqs title="Frequently Asked Questions">
23 <faq>
24 <question>
25 Why is reading a simple sheet taking so long?
26 </question>
27 <answer>
28 <p>You've probably enabled logging. Logging is intended only for
29 autopsie style debugging. Having it enabled will reduce performance
30 by a factor of at least 100. Logging is helpful for understanding
31 why POI can't read some file or developing POI itself. Important
32 errors are thrown as exceptions, which means you probably don't need
33 logging.</p>
34 </answer>
35 </faq>
36 <faq>
37 <question>
38 What is the HSSF "eventmodel"?
39 </question>
40 <answer>
41 <p>The HSSF eventmodel package is a new API for reading XLS files more efficiently. It does
42 require more knowledge on the part of the user, but reduces memory consumption by more than
43 tenfold. It is based on the AWT event model in combination with SAX. If you need read-only
44 access to a given XLS file, this is the best way to do it.</p>
45 </answer>
47 </faq>
48 <faq>
49 <question>
50 Why can't read the document I created using Star Office 5.1?
51 </question>
52 <answer>
53 <p>Star Office 5.1 writes some records using the older BIFF standard. This causes some problems
54 with POI which supports only BIFF8.</p>
55 </answer>
56 </faq>
57 <faq>
58 <question>
59 Why am I getting an exception each time I attempt to read my spreadsheet?
60 </question>
61 <answer>
62 <p>It's possible your spreadsheet contains a feature that is not currently supported by HSSF.
63 For example - spreadsheets containing cells with rich text are not currently supported.</p>
64 </answer>
65 </faq>
66 <faq>
67 <question>
68 Does HSSF support protected spreadsheets?
69 </question>
70 <answer>
71 <p>Protecting a spreadsheet encrypts it. We wont touch encryption because we're not legally educated
72 and don't understand the full implications of trying to implement this. If you wish to have a go
73 at this feel free to add it as a plugin module. We wont be hosting it here however.</p>
74 </answer>
75 </faq>
76 <faq>
77 <question>
78 How do you tell if a field contains a date with HSSF?
79 </question>
80 <answer>
81 <p>Excel stores dates as numbers therefore the only way to determine if a cell is
82 actually stored as a date is to look at the formatting. There is a helper method
83 in HSSFDateUtil (since the 1.7.0-dev release) that checks for this.
84 Thanks to Jason Hoffman for providing the solution.</p>
85 <source>
86 case HSSFCell.CELL_TYPE_NUMERIC:
87 double d = cell.getNumericCellValue();
88 // test if a date!
89 if (HSSFDateUtil.isCellDateFormatted(cell)) {
90 // format in form of M/D/YY
91 cal.setTime(HSSFDateUtil.getJavaDate(d));
92 cellText =
93 (String.valueOf(cal.get(Calendar.YEAR))).substring(2);
94 cellText = cal.get(Calendar.MONTH)+1 + "/" +
95 cal.get(Calendar.DAY_OF_MONTH) + "/" +
96 cellText;
97 } </source>
98 </answer>
99 </faq>
100 <faq>
101 <question>
102 I'm trying to stream an XLS file from a servlet and I'm having some trouble. What's the problem?
103 </question>
104 <answer>
105 <p>
106 The problem usually manifests itself as the junk characters being shown on
107 screen. The problem persists even though you have set the correct mime type.
108 </p>
109 <p>
110 The short answer is, don't depend on IE to display a binary file type properly if you stream it via a
111 servlet. Every minor version of IE has different bugs on this issue.
112 </p>
113 <p>
114 The problem in most versions of IE is that it does not use the mime type on
115 the HTTP response to determine the file type; rather it uses the file extension
116 on the request. Thus you might want to add a
117 <strong>.xls</strong> to your request
118 string. For example
119 <em>http://yourserver.com/myServelet.xls?param1=xx</em>. This is
120 easily accomplished through URL mapping in any servlet container. Sometimes
121 a request like
122 <em>http://yourserver.com/myServelet?param1=xx&dummy=file.xls</em> is also
123 known to work.
125 </p>
126 <p>
127 To guarantee opening the file properly in Excel from IE, write out your file to a
128 temporary file under your web root from your servelet. Then send an http response
129 to the browser to do a client side redirection to your temp file. (Note that using a
130 server side redirect using RequestDispatcher will not be effective in this case)
131 </p>
132 <p>
133 Note also that when you request a document that is opened with an
134 external handler, IE sometimes makes two requests to the webserver. So if your
135 generating process is heavy, it makes sense to write out to a temporary file, so that multiple
136 requests happen for a static file.
137 </p>
138 <p>
139 None of this is particular to Excel. The same problem arises when you try to
140 generate any binary file dynamically to an IE client. For example, if you generate
141 pdf files using
142 <link href="http://xml.apache.org/fop">FOP</link>, you will come across many of the same issues.
144 </p>
145 <!-- Thanks to Avik for the answer -->
146 </answer>
147 </faq>
148 <faq>
149 <question>
150 I want to set a cell format (Data format of a cell) of a excel sheet as ###,###,###.#### or ###,###,###.0000. Is it possible using POI ?
151 </question>
152 <answer>
153 <p>
154 Yes. You first need to get a HSSFDataFormat object from the workbook and call getFormat with the desired format. Some examples are <link href="hssf/quick-guide.html#DataFormats">here</link>.
155 </p>
156 </answer>
157 </faq>
158 <faq>
159 <question>
160 I want to set a cell format (Data format of a cell) of a excel sheet as text. Is it possible using POI ?
161 </question>
162 <answer>
163 <p>
164 Yes. This is a built-in format for excel that you can get from HSSFDataFormat object using the format string "@". Also, the string "text" will alias this format.
165 </p>
166 </answer>
167 </faq>
168 <faq>
169 <question>
170 How do I add a border around a merged cell?
171 </question>
172 <answer>
173 <p>Add blank cells around where the cells normally would have been and set the borders individually for each cell.
174 We will probably enhance HSSF in the future to make this process easier.</p>
175 </answer>
176 </faq>
177 <faq>
178 <question>
179 I tried to set cell values and Excel sheet name on my native language,
180 but I failed to do it. :(
181 </question>
182 <answer>
183 <p>By default HSSF uses cell values and sheet names as compressed unicode,
184 so to support localization you should use Unicode.
185 To do it you should set it manually:</p>
186 <source>
187 // for sheet name
188 HSSFWorkbook wb = new HSSFWorkbook();
189 HSSFSheet s = wb.createSheet();
190 wb.setSheetName( 0, "SomeUnicodeName", HSSFWorkbook.ENCODING_UTF_16 );
192 // for cell value
193 HSSFRow r = s.createRow( 0 );
194 HSSFCell c = r.createCell( (short)0 );
195 c.setCellType( HSSFCell.CELL_TYPE_STRING );
196 c.setEncoding( HSSFCell.ENCODING_UTF_16 );
197 c.setCellValue( "\u0422\u0435\u0441\u0442\u043E\u0432\u0430\u044F" ); </source>
198 <p>
199 Make sure you make the call to setEncoding() before calling setCellValue(), otherwise what you pass in won't be interpreted properly.
200 </p>
201 </answer>
202 </faq>
203 <faq>
204 <question>
205 I'm having trouble creating a spreadsheet using POI using
206 websphere 3.5.
207 </question>
208 <answer>
209 <p>Make sure you have fix pack 4 installed.</p>
210 </answer>
211 </faq>
212 <faq>
213 <question>
214 I am using styles when creating a workbook in POI, but Excel refuses to open the file, complaining about "Too Many Styles".
215 </question>
216 <answer>
217 <p>You just create the styles OUTSIDE of the loop in which you create cells.</p>
218 <p>GOOD:</p>
219 <source>
220 HSSFWorkbook wb = new HSSFWorkbook();
221 HSSFSheet sheet = wb.createSheet("new sheet");
222 HSSFRow row = null;
224 // Aqua background
225 HSSFCellStyle style = wb.createCellStyle();
226 style.setFillBackgroundColor(HSSFColor.AQUA.index);
227 style.setFillPattern(HSSFCellStyle.BIG_SPOTS);
228 HSSFCell cell = row.createCell((short) 1);
229 cell.setCellValue("X");
230 cell.setCellStyle(style);
232 // Orange "foreground", foreground being the fill foreground not the font color.
233 style = wb.createCellStyle();
234 style.setFillForegroundColor(HSSFColor.ORANGE.index);
235 style.setFillPattern(HSSFCellStyle.SOLID_FOREGROUND);
237 for (int x = 0; x < 1000; x++) {
239 // Create a row and put some cells in it. Rows are 0 based.
240 row = sheet.createRow((short) k);
242 for (int y = 0; y < 100; y++) {
243 cell = row.createCell((short) k);
244 cell.setCellValue("X");
245 cell.setCellStyle(style);
246 }
247 }
249 // Write the output to a file
250 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
251 wb.write(fileOut);
252 fileOut.close(); </source>
254 <p>BAD:</p>
255 <source>
256 HSSFWorkbook wb = new HSSFWorkbook();
257 HSSFSheet sheet = wb.createSheet("new sheet");
258 HSSFRow row = null;
260 for (int x = 0; x < 1000; x++) {
261 // Aqua background
262 HSSFCellStyle style = wb.createCellStyle();
263 style.setFillBackgroundColor(HSSFColor.AQUA.index);
264 style.setFillPattern(HSSFCellStyle.BIG_SPOTS);
265 HSSFCell cell = row.createCell((short) 1);
266 cell.setCellValue("X");
267 cell.setCellStyle(style);
269 // Orange "foreground", foreground being the fill foreground not the font color.
270 style = wb.createCellStyle();
271 style.setFillForegroundColor(HSSFColor.ORANGE.index);
272 style.setFillPattern(HSSFCellStyle.SOLID_FOREGROUND);
274 // Create a row and put some cells in it. Rows are 0 based.
275 row = sheet.createRow((short) k);
277 for (int y = 0; y < 100; y++) {
278 cell = row.createCell((short) k);
279 cell.setCellValue("X");
280 cell.setCellStyle(style);
281 }
282 }
284 // Write the output to a file
285 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
286 wb.write(fileOut);
287 fileOut.close(); </source>
288 </answer>
289 </faq>
290 <faq>
291 <question>
292 Will POI read any spreadsheet and rewrite it with modifications.
293 </question>
294 <answer>
295 <p>POI is not guanteed to read the contents of any spreadsheet.
296 Certain features may cause spreadsheets to fail to read. More
297 problematic is rewriting spreadsheets. POI tried hard to
298 preserve the records of the original spreadsheet but some
299 features may cause problems. We advise that you limit the
300 formatting of spreadsheets you process so as to not be
301 unpleasantly suprised at a later stage.</p>
302 </answer>
303 </faq>
304 </faqs>