General FAQ
-----------

  1. How does the ExcelWorksheetAccessor set of beans access an Excel 
     workbook?

      Excel provides a COM (Component Object Model) object that exposes 
      the API to access an Excel workbook. As Java cannot access the COM 
      object directly, it does so using the  Java Native Interface (JNI). 
      The native C++ code that interacts with the COM object can be 
      wrapped in a DLL, and hence accessed by a Java program using JNI. 
      Java provides the mechanism to load the DLL and invoke the 
      functions on it. ExcelWorksheetAccessor uses this approach to access 
      an Excel workbook.
    
  2. What are the benefits of the ExcelWorksheetAccessor Suite
     of Beans?

      The ExcelWorksheetAccessor suite of beans provides the functionality
      to visually program a Java application to access the contents of a 
      Microsoft Excel worksheet. The suite contains two non-visual beans 
      that can be easily wired with other beans in various IDE's to 
      create applications.

  3. Do I have to use the ExcelRange/ExcelWorkbook beans together? Why are 
     they 2 separate beans if they cannot be used without each other?

      Yes. The ExcelWorkbook bean handles Excel's workbook related 
      functionality such as open/close a workbook or unprotect workbook 
      structure. The ExcelRange bean, as the name suggests, handles the 
      range related functionality including insertion/removal of 
      worksheets. Now, you can work on multiple worksheets/ranges in a 
      single workbook. You may have one instance of the ExcelWorkbook 
      bean and use multiple instances of the ExcelRange bean, with the 
      same ExcelWorkbook instance.

  4. How do I use these beans to access range data? 

      Following is an example of the steps to be followed to access 
      range data using the ExcelWorksheetAccessor suite of beans:
      a. Create an instance of the ExcelWorkbook bean. Supply the name 
         of the workbook, and the mode in which the workbook is to be 
         opened. (The default is the read mode). Set the flag  to save 
         the workbook data when closed. (By default, the workbook 
         will be saved on closing).
      b. You may call the openWorkbook method of ExcelWorkbook bean 
         to open the workbook. However, this is optional. The workbook 
         opens itself when accessed for the first time, if it is not 
         already open.
      c. Create an instance of the ExcelRange bean. Supply the instance 
         of the ExcelWorkbook bean, worksheet name, and, range for which 
         data is to be accessed.
      d. Call the initRange method of the ExcelRange bean explicitly.
      e. If the initRange method is successful,  it updates the  value, 
         formula, format, text and noteText properties of this bean, 
         with the properties associated with the cells for the given 
         range. You can call the setters on these properties to write 
         them on to the Excel worksheets. (The workbook should be open 
         in the read-write mode).
      f. Call the closeWorkbook method on the ExcelWorkbook bean, if you
         do not need to access the workbook anymore. The method fires 
         an event to determine whether modifications to the workbook 
         are to be discarded. By default, the workbook is saved while 
         closing.


  5. What are the limitations associated with the ExcelWorksheetAccessor 
     suite of beans?

     The following are the limitations of the ExcelWorksheetAccessor 
     suite of beans.

     a. The beans do not provide any Array Formula functionality. In 
        Excel, a group of cells can be designated as an array and a 
        formula associated with the group. It is not possible to modify 
        individual cells in such an array. In the bean suite, if a 
        range given by the user contains cells of an array formula, it 
        is not possible to modify the values in these cells. In other 
        words, these beans are able to write values to a range, only 
        if the range does not contain any cells of an array formula.  
     b. If an .xls file contains links to other sheets in other 
        workbooks, these links will not be updated when the file is 
        opened. Thus, only old values can be accessed.
     c. The ExcelWorkbook bean supports valid .xls files only. The 
        behavior of the beans in case an invalid file is supplied, 
        is unpredictable.
     d. This suite of beans would not handle any other objects such as 
        charts, drawings etc., which might be embedded inside an Excel 
        file. These bean concern themselves with the values in the 
        cells alone.
     e. If the workbook being opened has any Auto_Open macros in it, 
        they will not be run when the bean opens the file.
     f. The ExcelRange bean works only with ranges, which are 
        continuous, i.e. the range cannot contain multiple rectangular 
        areas.

  6. What are the platforms supported?
  
        Since the ExcelWorksheetAccessor suite uses ActiveX controls 
        for Excel, it is tied to the Windows platform. 

  7. Is it "100% Pure Java"?

        As the ExcelWorksheetAccessor bean suite accesses native code 
        using JNI, it is not 100% pure Java. Since the suite uses 
        ActiveX controls, it is tied to the Windows platform.

  8. What builder tools can be used?

        The ExcelWorksheetAccessor bean suite is not 100% pure Java as 
        it accesses native code using JNI (JDK 1.1 standard). It 
        should be usable in all Java environments that support JNI 
        and JavaBeans. 

        However, see below for some problems that exist in some of the
        builder tools.      
  
  9. What known problems are there?

    BeanBox:
    --------
    1. As the beans use native code, they do not work in the current 
       version (BDK March, 1998) of BeanBox. However, you can drop the 
       beans in BeanBox and customize various properties.


    IBM VisualAge for Java v2.0:
    ----------------------------
    1.  The fixpack 'Rollup1' has to be installed. This fixpack can be downloaded 
        from the IBM Visual Age web site. 


Bean Specific FAQ
------------------

  ExcelWorkbook FAQ
  -----------------

  1. Is it necessary to invoke the openWorkbook() method on the 
     ExcelWorkbook bean?
    
      No. The workbook is opened, (if not already open), when it is 
      accessed for the first time (using the ExcelRange bean).
 
  
  2. Is it necessary to invoke the closeWorkbook() method on the 
     ExcelWorkbook bean?

      The finalize method on this bean calls the closeWorkbook method 
      explicitly. But the finalize method call depends upon the garbage
      collector and hence cannot be guaranteed. Hence, it is preferable
      to invoke the closeWorkbook() method, otherwise changes made to 
      the workbook may be lost.

  3. How do I open a workbook that is password protected?
    
      The openWorkbook() method on this bean fires the FetchPasswordEvent
      whenever it requires a password. Listen for this event and provide
      the password. Alternatively, you may set the required password 
      prior to calling openWorkbook method.
    
  4. Can I open multiple workbooks on a single instance of this bean?

      No. You cannot open multiple workbooks on a single instance of 
      this bean. The already open workbook is closed, (the data is 
      saved by default), as you set the new workbook name. You could, 
      of course, create as many instances of the bean as the number 
      of workbooks to be opened.


  ExcelRange FAQ
  --------------

  1. If I do not identify the range but provide the worksheetName, will 
     the bean take the default range on the worksheet?
    
        No. You need to identify both the range and worksheet.

  2. What are the different ways of identifying a cell/range for this 
     bean?

        There are two ways of referencing a cell. The "A1" style of 
        reference identifies a cell by its name. i.e. a cell say, B4, 
        is referenced by the name "B4". The "R1C1" style of reference, 
        on the other hand, references a cell using the row and column 
        number. In this case, the cell B4 would be referenced as 
        "row 4, column 2". The ExcelRange bean allows you to select a 
        range using either of these methods (it provides setters for both
        cases). In case you invoke both types of setters on the 
        ExcelRange bean, the setter that was invoked last is used to 
        identify the range to be accessed.
        
        A range from cell "A1" to say "F3", is referenced as "A1:F3" in 
        the A1 style reference. In "R1C1" style the range is referenced 
        using the top-left and bottom-right cells, i.e. "row 1, columnn 1",
        "row 3, column 6".

        The beans do not have support for ranges that contain 
        multiple areas (i.e. ranges which are not contiguous).

        For detailed information refer to the Microsoft Excel 
        documentation. 
       
  3. I have identified the range both by A1 style and R1C1 style. 
     What range will be considered?
        
        The range that has been supplied last will be considered.

  4. Can I use the same ExcelRange bean to access different ranges?
        
        Yes, a single instance of the range bean can be used to access 
        different ranges. Calling the setter for the range name (or 
        selecting a different range using row and column numbers) 
        results in the range bean getting uninitialized. 'initRange' 
        has to be invoked again to initialize the range.

  5. What is the difference between the "text" and "defaultText" 
     properties of the ExcelRange bean?
        
        By default, Excel returns null if the text in all the cells 
        of the range is not the same. If it is the same, it is returned 
        as a String. This is the "defaultText" property.
        
        However, for the "text" property, the ExcelRange bean iterates 
        through all the cells in the range and returns the text for 
        each cell in the range as a 2-D Vector of Strings.

  6. What are the datatypes of the various cell properties that I 
     access using the ExcelRange bean?
     
     Value       - The value property of cells in the range is 
                   accessible as a vector of vectors. The inner vectors 
                   represent the respective rows. The values in these 
                   vectors can be of types Double, String, Date, and 
                   Boolean. The value can also be accessed as a 2-D 
                   array of objects (or just a single object if the 
                   range is a single cell).

     Formula     - The formula property of cells in the range is 
                   accessible as a Vector of Vectors. The inner vectors 
                   represent the respective rows. The formulas in these 
                   vectors are of the String type. The formula can also 
                   be accessed as a 2-D array of objects (or just a 
                   single object if the range is a single cell).

     Format      - The format property is returned as String.

     Text        - The text property of the cells is returned as the 
                   Vector of Vectors of Strings. The inner vectors 
                   represent the respective rows.

     DefaultText - The defaultText property of cell is returned as a 
                   String.

     NoteText    - The noteText property is returned as a String.

  7. How do I unprotect a worksheet?

        This can be done by setting the autoUnprotectSheet flag to 
        true before initializing the ExcelRange bean. Alternatively, 
        you may explicitly call the unprotectWorksheet() method to 
        unprotect the worksheet. A password may be required to 
        unprotect the worksheet. This can be supplied before invoking 
        this method, or when the FetchPasswordEvent is fired.

  8. What will be the behavior in case of there is a difference between
     the dimensions of the range and the Vector I supply to the setter?
    
        In this case the behavior will be the same as the default Excel
        behavior.


  ExcelCell FAQ
  -------------

  1. How is the ExcelCell bean different from the ExcelRange bean?
    
        The ExcelCell bean operates on a single cell only, whereas the 
        ExcelRange bean can be used to operate on ranges.

        On the ExcelRange bean, the text, value and formula property 
        are 2-D vectors containing information about all cells in the 
        range. However on the ExcelCell bean these properties are scalars. 
        If a range is accessed, the ExcelCell bean operates only on the
        first cell (i.e. the cell in the top-left corner)
        of the range.



TroubleShooting FAQ
-------------------
 1. I set the range name etc, on the range bean and called initRange(). 
    The range bean does not throw any error, yet I get the 
    UnInitializedRangeException?     
    
       The ExcelWorkbook bean could have encountered an error and hence 
       fired a workbook related error event. You should listen to the 
       ExcelWorkbookErrorEvents to get the details of errors that might 
       have occurred on the ExcelWorkbook bean.   

 2. I access my data, then quit the Java application. When I start 
    another application and access the same workbook, I get the 
    "Workbook already open in write mode elsewhere" message? 
    
       When you quit the application without closing the workbook, 
       there is no guarantee that the finalize method of the 
       ExcelWorkbook would have been called to close the already 
       open Excel workbook. Hence, the resource might not have been 
       released. Next time, when you access the same workbook, the
       older resource may still exist in memory, and the "Open in 
       write mode elsewhere" problem is encountered.
       You can overcome this problem by explicitly calling the 
       closeWorkbook() method on the ExcelWorkbook bean.
 
 3. I am unable to get the names of the worksheets associated with 
    an Excel workbook from the ExcelWorkbook bean?
    
       The required Excel workbook has to be open before you can 
       access the worksheets in that workbook.
                             
 4. If I try to access a range, I get an error NoClassDefFoundError?
  
       The number of cells in the range you are trying to access 
       could be very large. Try accessing a smaller range.

 5. I am using Excel v5.0 and when I try to open an xls file, I get a 
    file not found error, even though the file exists?
        
       Excel v5.0 supports only DOS i.e. 8.3 file names. Make sure 
       that the file name (including all directories) is in the 
       requisite format.            
