KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > jxl > Workbook


1 /*********************************************************************
2 *
3 * Copyright (C) 2002 Andrew Khan
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 */

19
20 package jxl;
21
22 import java.io.FileInputStream JavaDoc;
23 import java.io.FileOutputStream JavaDoc;
24 import java.io.IOException JavaDoc;
25 import java.io.InputStream JavaDoc;
26 import java.io.OutputStream JavaDoc;
27
28 import jxl.read.biff.File;
29 import jxl.read.biff.WorkbookParser;
30 import jxl.read.biff.BiffException;
31 import jxl.read.biff.PasswordException;
32 import jxl.write.WritableWorkbook;
33 import jxl.write.biff.WritableWorkbookImpl;
34
35 /**
36  * Represents a Workbook. Contains the various factory methods and provides
37  * a variety of accessors which provide access to the work sheets.
38  */

39 public abstract class Workbook
40 {
41   /**
42    * The current version of the software
43    */

44   private static final String JavaDoc version = "2.5.6";
45
46   /**
47    * The constructor
48    */

49   protected Workbook()
50   {
51   }
52
53   /**
54    * Gets the sheets within this workbook. Use of this method for
55    * large worksheets can cause performance problems.
56    *
57    * @return an array of the individual sheets
58    */

59   public abstract Sheet[] getSheets();
60
61   /**
62    * Gets the sheet names
63    *
64    * @return an array of strings containing the sheet names
65    */

66   public abstract String JavaDoc[] getSheetNames();
67
68   /**
69    * Gets the specified sheet within this workbook
70    * As described in the accompanying technical notes, each call
71    * to getSheet forces a reread of the sheet (for memory reasons).
72    * Therefore, do not make unnecessary calls to this method. Furthermore,
73    * do not hold unnecessary references to Sheets in client code, as
74    * this will prevent the garbage collector from freeing the memory
75    *
76    * @param index the zero based index of the reQuired sheet
77    * @return The sheet specified by the index
78    * @exception IndexOutOfBoundException when index refers to a non-existent
79    * sheet
80    */

81   public abstract Sheet getSheet(int index)
82     throws IndexOutOfBoundsException JavaDoc;
83
84   /**
85    * Gets the sheet with the specified name from within this workbook.
86    * As described in the accompanying technical notes, each call
87    * to getSheet forces a reread of the sheet (for memory reasons).
88    * Therefore, do not make unnecessary calls to this method. Furthermore,
89    * do not hold unnecessary references to Sheets in client code, as
90    * this will prevent the garbage collector from freeing the memory
91    *
92    * @param name the sheet name
93    * @return The sheet with the specified name, or null if it is not found
94    */

95   public abstract Sheet getSheet(String JavaDoc name);
96
97   /**
98    * Accessor for the software version
99    *
100    * @return the version
101    */

102   public static String JavaDoc getVersion()
103   {
104     return version;
105   }
106
107   /**
108    * Returns the number of sheets in this workbook
109    *
110    * @return the number of sheets in this workbook
111    */

112   public abstract int getNumberOfSheets();
113
114   /**
115    * Gets the named cell from this workbook. The name refers to a
116    * range of cells, then the cell on the top left is returned. If
117    * the name cannot be, null is returned.
118    * This is a convenience function to quickly access the contents
119    * of a single cell. If you need further information (such as the
120    * sheet or adjacent cells in the range) use the functionally
121    * richer method, findByName which returns a list of ranges
122    *
123    * @param name the name of the cell/range to search for
124    * @return the cell in the top left of the range if found, NULL
125    * otherwise
126    */

127   public abstract Cell findCellByName(String JavaDoc name);
128
129   /**
130    * Gets the named range from this workbook. The Range object returns
131    * contains all the cells from the top left to the bottom right
132    * of the range.
133    * If the named range comprises an adjacent range,
134    * the Range[] will contain one object; for non-adjacent
135    * ranges, it is necessary to return an array of length greater than
136    * one.
137    * If the named range contains a single cell, the top left and
138    * bottom right cell will be the same cell
139    *
140    * @param name the name of the cell/range to search for
141    * @return the range of cells, or NULL if the range does not exist
142    */

143   public abstract Range[] findByName(String JavaDoc name);
144
145   /**
146    * Gets the named ranges
147    *
148    * @return the list of named cells within the workbook
149    */

150   public abstract String JavaDoc[] getRangeNames();
151
152
153   /**
154    * Determines whether the sheet is protected
155    *
156    * @return TRUE if the workbook is protected, FALSE otherwise
157    */

158   public abstract boolean isProtected();
159
160   /**
161    * Parses the excel file.
162    * If the workbook is password protected a PasswordException is thrown
163    * in case consumers of the API wish to handle this in a particular way
164    *
165    * @exception BiffException
166    * @exception PasswordException
167    */

168   protected abstract void parse() throws BiffException, PasswordException;
169
170   /**
171    * Closes this workbook, and frees makes any memory allocated available
172    * for garbage collection
173    */

174   public abstract void close();
175
176   /**
177    * A factory method which takes in an excel file and reads in the contents.
178    *
179    * @exception IOException
180    * @exception BiffException
181    * @param file the excel 97 spreadsheet to parse
182    * @return a workbook instance
183    */

184   public static Workbook getWorkbook(java.io.File JavaDoc file)
185     throws IOException JavaDoc, BiffException
186   {
187     return getWorkbook(file, new WorkbookSettings());
188   }
189
190   /**
191    * A factory method which takes in an excel file and reads in the contents.
192    *
193    * @exception IOException
194    * @exception BiffException
195    * @param file the excel 97 spreadsheet to parse
196    * @param ws the settings for the workbook
197    * @return a workbook instance
198    */

199   public static Workbook getWorkbook(java.io.File JavaDoc file, WorkbookSettings ws)
200     throws IOException JavaDoc, BiffException
201   {
202     FileInputStream JavaDoc fis = new FileInputStream JavaDoc(file);
203
204     // Always close down the input stream, regardless of whether or not the
205
// file can be parsed. Thanks to Steve Hahn for this
206
File dataFile = null;
207
208     try
209     {
210       dataFile = new File(fis, ws);
211     }
212     catch (IOException JavaDoc e)
213     {
214       fis.close();
215       throw e;
216     }
217     catch (BiffException e)
218     {
219       fis.close();
220       throw e;
221     }
222
223     fis.close();
224
225     Workbook workbook = new WorkbookParser(dataFile, ws);
226     workbook.parse();
227
228     return workbook;
229   }
230
231   /**
232    * A factory method which takes in an excel file and reads in the contents.
233    *
234    * @exception IOException
235    * @exception BiffException
236    * @param is an open stream which is the the excel 97 spreadsheet to parse
237    * @return a workbook instance
238    */

239   public static Workbook getWorkbook(InputStream JavaDoc is)
240     throws IOException JavaDoc, BiffException
241   {
242     return getWorkbook(is, new WorkbookSettings());
243   }
244
245   /**
246    * A factory method which takes in an excel file and reads in the contents.
247    *
248    * @exception IOException
249    * @exception BiffException
250    * @param is an open stream which is the the excel 97 spreadsheet to parse
251    * @param ws the settings for the workbook
252    * @return a workbook instance
253    */

254   public static Workbook getWorkbook(InputStream JavaDoc is, WorkbookSettings ws)
255     throws IOException JavaDoc, BiffException
256   {
257     File dataFile = new File(is, ws);
258
259     Workbook workbook = new WorkbookParser(dataFile, ws);
260     workbook.parse();
261
262     return workbook;
263   }
264
265   /**
266    * Creates a writable workbook with the given file name
267    *
268    * @param file the workbook to copy
269    * @return a writable workbook
270    */

271   public static WritableWorkbook createWorkbook(java.io.File JavaDoc file)
272     throws IOException JavaDoc
273   {
274     return createWorkbook(file, new WorkbookSettings());
275   }
276
277   /**
278    * Creates a writable workbook with the given file name
279    *
280    * @param file the file to copy from
281    * @param ws the global workbook settings
282    * @return a writable workbook
283    */

284   public static WritableWorkbook createWorkbook(java.io.File JavaDoc file,
285                                                 WorkbookSettings ws)
286     throws IOException JavaDoc
287   {
288     FileOutputStream JavaDoc fos = new FileOutputStream JavaDoc(file);
289     WritableWorkbook w = new WritableWorkbookImpl(fos, true, ws);
290     return w;
291   }
292
293   /**
294    * Creates a writable workbook with the given filename as a copy of
295    * the workbook passed in. Once created, the contents of the writable
296    * workbook may be modified
297    *
298    * @param file the output file for the copy
299    * @param in the workbook to copy
300    * @return a writable workbook
301    */

302   public static WritableWorkbook createWorkbook(java.io.File JavaDoc file,
303                                                 Workbook in)
304     throws IOException JavaDoc
305   {
306     return createWorkbook(file, in, new WorkbookSettings());
307   }
308
309   /**
310    * Creates a writable workbook with the given filename as a copy of
311    * the workbook passed in. Once created, the contents of the writable
312    * workbook may be modified
313    *
314    * @param file the output file for the copy
315    * @param in the workbook to copy
316    * @param ws the configuration for this workbook
317    * @return a writable workbook
318    */

319   public static WritableWorkbook createWorkbook(java.io.File JavaDoc file,
320                                                 Workbook in,
321                                                 WorkbookSettings ws)
322     throws IOException JavaDoc
323   {
324     FileOutputStream JavaDoc fos = new FileOutputStream JavaDoc(file);
325     WritableWorkbook w = new WritableWorkbookImpl(fos, in, true, ws);
326     return w;
327   }
328
329   /**
330    * Creates a writable workbook as a copy of
331    * the workbook passed in. Once created, the contents of the writable
332    * workbook may be modified
333    *
334    * @param os the stream to write to
335    * @param in the workbook to copy
336    * @return a writable workbook
337    */

338   public static WritableWorkbook createWorkbook(OutputStream JavaDoc os,
339                                                 Workbook in)
340     throws IOException JavaDoc
341   {
342     return createWorkbook(os, in, ((WorkbookParser) in).getSettings());
343   }
344
345   /**
346    * Creates a writable workbook as a copy of
347    * the workbook passed in. Once created, the contents of the writable
348    * workbook may be modified
349    *
350    * @param os the output stream to write to
351    * @param in the workbook to copy
352    * @param ws the configuration for this workbook
353    * @return a writable workbook
354    */

355   public static WritableWorkbook createWorkbook(OutputStream JavaDoc os,
356                                                 Workbook in,
357                                                 WorkbookSettings ws)
358     throws IOException JavaDoc
359   {
360     WritableWorkbook w = new WritableWorkbookImpl(os, in, false, ws);
361     return w;
362   }
363
364   /**
365    * Creates a writable workbook. When the workbook is closed,
366    * it will be streamed directly to the output stream. In this
367    * manner, a generated excel spreadsheet can be passed from
368    * a servlet to the browser over HTTP
369    *
370    * @param os the output stream
371    * @return the writable workbook
372    */

373   public static WritableWorkbook createWorkbook(OutputStream JavaDoc os)
374     throws IOException JavaDoc
375   {
376     return createWorkbook(os, new WorkbookSettings());
377   }
378
379   /**
380    * Creates a writable workbook. When the workbook is closed,
381    * it will be streamed directly to the output stream. In this
382    * manner, a generated excel spreadsheet can be passed from
383    * a servlet to the browser over HTTP
384    *
385    * @param os the output stream
386    * @param ws the configuration for this workbook
387    * @return the writable workbook
388    */

389   public static WritableWorkbook createWorkbook(OutputStream JavaDoc os,
390                                                 WorkbookSettings ws)
391     throws IOException JavaDoc
392   {
393     WritableWorkbook w = new WritableWorkbookImpl(os, false, ws);
394     return w;
395   }
396 }
397
398
399
400
401
402
Popular Tags