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  ;
23  import java.io.FileOutputStream  ;
24  import java.io.IOException  ;
25  import java.io.InputStream  ;
26  import java.io.OutputStream  ;
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   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  [] 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  ;
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   name);
96  
97    /**
98     * Accessor for the software version
99     *
100    * @return the version
101    */
102   public static String   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   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   name);
144 
145   /**
146    * Gets the named ranges
147    *
148    * @return the list of named cells within the workbook
149    */
150   public abstract String  [] 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   file)
185     throws IOException  , 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   file, WorkbookSettings ws)
200     throws IOException  , BiffException
201   {
202     FileInputStream   fis = new FileInputStream  (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   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   is)
240     throws IOException  , 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   is, WorkbookSettings ws)
255     throws IOException  , 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   file)
272     throws IOException  
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   file,
285                                                 WorkbookSettings ws)
286     throws IOException  
287   {
288     FileOutputStream   fos = new FileOutputStream  (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   file,
303                                                 Workbook in)
304     throws IOException  
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   file,
320                                                 Workbook in,
321                                                 WorkbookSettings ws)
322     throws IOException  
323   {
324     FileOutputStream   fos = new FileOutputStream  (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   os,
339                                                 Workbook in)
340     throws IOException  
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   os,
356                                                 Workbook in,
357                                                 WorkbookSettings ws)
358     throws IOException  
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   os)
374     throws IOException  
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   os,
390                                                 WorkbookSettings ws)
391     throws IOException  
392   {
393     WritableWorkbook w = new WritableWorkbookImpl(os, false, ws);
394     return w;
395   }
396 }
397 
398 
399 
400 
401 
402
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags