XMLBeans i XPath

XMLBeans posiada fajną funkcjonalność, pozwalająca na użycie języka XPath do wyciągania z obiektu klasy XmlObject (klasy do której “wparsowany” jest nasz xml) potrzebnych nam danych. Z tak zwanego out of the box, nasza biblioteka pozwala na tworzenie jedynie prostych zapytań XPath (np: //book). Jeżeli chcemy wykorzystać trochę bardziej złożoną semantykę (powiedzmy: //book[@title='EJB3 in Action']) powinniśmy spiąć XMLBeans z biblioteką Saxon (procesor XSLT i XQuery). Takie spięcie polega jedynie na dodaniu do naszej aplikacji bibliotek saxon.jar, saxon-dom.jar (znajdują się w jednym archiwum ściąganym ze strony saxona) oraz xbean_xpath.jar (dostępnego razem z dystrybucją XMLBeans). Jeśli środowisko jest już przygotowane, wystarczy wywołać na obiekcie XmlObject metodę selectPath podając w jej parametrze wyrażenie XPath. W odpowiedzi powinniśmy dostać tablicę obiektów XmlObject z interesującymi nas danymi.

XmlObject[] data = BookDocument.selectPath("//book[@title='EJB3 in Action']");

W moim przypadku coś poszło jednak nie tak. Mimo, że sprawdziłem poprawność wyrażenia XPath, zmienna data była nullem. Zajęło mi trochę czasu aby problem rozwiązać. Okazuje się że Apache XMLBeans w wersji 2.3.0 współpracuje tylko z bardzo konkretną wersją biblioteki Saxon: wersją 8.8. Ja posiadałem najnowszego Saxon’a oznaczonego numerem 9.0. W taki oto sposób straciłem 45 minut i przed tą stratą postanowiłem ostrzec Was :)

Apache HSSF POI i przeliczanie formuł w Excelu

O problemie przeliczania formuł w arkuszach MS Excel pisałem już wcześniej. Wtedy była to tylko wzmianka o tym, że istnieje specjalna klasa służąca właśnie do tego (HSSFFormulaEvaluator) i że nie udało mi się jej użyć ;) Od wersji 3.0.1 klasa ta już jest niedostępna, a problem pozostał. No właśnie… może przybliżę problem: powiedzmy, że istnieje arkusz Excela, który posiada tylko trzy pola: A1 – liczba, A2 – liczba, A3 = A2 – A1. Z jakiegoś tylko tobie znanego powodu, za pomocą Apache POI chcesz zmienić liczbę w polu A2 na jakąś inną.. lepszą ;) Robisz wszystko co potrzeba, zapisujesz arkusz na dysku, otwierasz go w Excelu i zauważasz, że formuła w polu A3 ciągle pokazuje wyliczenia z poprzednimi wartościami. Co należy zrobić aby formuła została przeliczona ? Należy zapamiętać formułę w stringu, nadać komórce typ: HSSFCell.CELL_TYPE_FORMULA oraz zapisać ponownie do komórki zapamiętaną wcześniej formułę. Rozwiązanie proste jak budowa cepa, tym bardziej więc dziwi, że działa tak, jakbyśmy tego chcieli ;)

String formula = cell.getCellFormula();
cell.setCellType(HSSFCell.CELL_TYPE_FORMULA);
cell.setCellFormula(formula);

To by było na tyle. Obiecuję, że już nie będę Was męczył zagadnieniami związanymi z POI i XMLBeans :)

W niniejszym artykule zaprezentuję podstawowe możliwości HSSF: wyświetlenie na konsoli prostego pliku MS Excel, manipulacja danymi, oraz zapis. Aplikacja stworzona zostanie w Eclipse 3.2.2, a do jej budowania użyję Maven 2.0.7. Aby nie wybiegać poza temat, musiałem założyć, że obydwa te narzędzia są czytelnikowi znane. W Eclipse korzystam m.in. z wtyczki m2eclipse, która ułatwia korzystanie z mavena. Dobrą i darmową książkę o Apache Maven można pobrać ze strony http://www.mergere.com/m2book_download.jsp

Zaczynamy..
Za pomocą Mavena tworze szkielet aplikacji, a następnie, po przejściu do katalogu poi-excel, tworzę projekt dla Eclipse

mvn archetype:create -DgroupId=pl.j2ee.poi.hssf -DartifactId=poi-excel

mvn eclipse:eclipse

Obydwa polecenia powinny zakończyć się komunikatem BUILD SUCCESSFUL .

Otwieram wygenerowany projekt w Eclipse i zabieram się za edycje pliku pom.xml do którego dodam odpowiednie zależnosci oraz skonfiguruję build. Usunę także klasę wygenerowanego przez mavena testu AppTest.

W rezultacie otrzymuję taki oto plik (opis w komentarzach):

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
  http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>pl.j2ee.poi.hssf</groupId>
  <artifactId>poi-excel</artifactId>
  <packaging>jar</packaging>
  <version>1.0</version>
  <name>poi-excel</name>
  <url>http://j2ee.pl</url>
  <build>
    <!-- build do pliku poi-excel.jar -->
    <finalName>poi-excel</finalName>
    <sourceDirectory>${basedir}/src/main</sourceDirectory>
    <plugins>
      <!-- Kompilacja w Java 6.0 (moze byc 1.4)-->
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.6</source>
          <target>1.6</target>
        </configuration>
      </plugin>
      <!-- Nasz wlasny plik MANIFEST.MF, w ktorym
           umieszczamy m.in. info o naszej klasie glownej -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <configuration>
          <archive>
            <manifestFile>
              src/main/resources/META-INF/MANIFEST.MF
            </manifestFile>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>
  <dependencies>
    <!-- Gwozdz programu.. Apache POI. W momencie powstawania artykulu
          w repozytorium nie bylo jeszcze wersji 3.0.1 -->
    <dependency>
      <groupId>poi</groupId>
      <artifactId>poi</artifactId>
      <version>3.0-FINAL</version>
    </dependency>
  </dependencies>
  <repositories>
    <!-- Dodatkowe repozytorium (na ibiblio biblioteki
    sa znacznie nowsze niz na glownym serwerze mavena -->
    <repository>
      <name>ibiblio</name>
      <id>ibiblio</id>
      <url>http://www.ibiblio.org/maven/</url>
    </repository>
  </repositories>
</project>

Dodatkowo w katalogu src/main/resources/META-INF umieszczam plik MANIFEST.MF, w którym wskazuje na klasę pl.j2ee.poi.hssf.App jako na punkt startowy mojej aplikacji.

Main-Class: pl.j2ee.poi.hssf.App

Tworzę prosty plik w formacie MS Excel. Utworzę go za pomocą pakietu Open Office 2.2. Arkusz o nazwie “Faktura” przedstawia.. i tutaj uwaga: (bardzo) prostą fakturę ;) Poniżej link do pliku oraz jego screenshot. Jak można zauważyć, w arkuszu znajduje się trzy kolumny z wartościami liczbowymi (L.P.; Cenna Netto, VAT), jedna kolumna tekstowa (Nazwa) oraz jedna kolumna wyliczana (Cenna Brutto = Cenna Netto * (1 + VAT)). Dodatkowo w komórce F9 umieściłem sumę cen brutto.

example.xls

Nadszedł już czas aby wreszcie napisać trochę kodu. Nasza prosta aplikacja będzie miała do wykonania cztery czynności

1. Wydrukowanie arkusza na standardowe wyjście
2. Zmiana ceny piwa
3. Dodanie zniżki
4. Zapis zmienionego arkusza do nowego pliku

Operacje te pozwolą na szybkie opanowanie podstawowych klas pakietu POI HSSF. Poszczególne funkcjonalności zostaną zaimplementowane w prostych metodach prywatnych, tak abym ja miał ułatwione zadanie w opisywaniu poszczególnych kroków, oraz po to, aby kod aplikacji wyglądał jako tako ;) Przepływ (w sensie flow) aplikacji definiujemy w starym dobrym public static void main. Dodatkowo definiujemy kilka stałych które wykorzystamy później.

public class App {

  // sciezka do pliku MS Excel
  private static final String EXCEL_FILE = "c:example.xls";
  // sciezka to nowego pliku MS Excel
  private static final String NEW_EXCEL_FILE = "c:example-new.xls";
  // nazwa arkusza z danymi
  private static final String SHEET_NAME = "Faktura";
  // numer kolumny z nazwami produktow
  private static final short NAME_COL_NUMBER = 2;
  // numer kolumny z cenami netto produktow
  private static final short PRICE_NET_COL_NUMBER = 3;
  //numer kolumny z cenami netto produktow
  private static final short PRICE_COL_NUMBER = 5;
  // identyfikator komorki z suma faktury
  private static final String SUM_CELL = "F9";

  private HSSFWorkbook workbook;
  private HSSFSheet sheet;

  public static void main(String[] args) throws IOException {

    App app = new App();
    app.initializeWorkbook();
    app.printWorksheet();
    app.changeBeerPrice(60);
    app.discount();
    app.saveAs(NEW_EXCEL_FILE);

  }
}

Na dobry początek idzie pod młotek inicalizacja (czyli w tym przypadku wczytanie) pliku MS Excel, a następnie wybór arkusza w którym znajdują się dane. Aby to zrobić musimy poznać trzy istotne klasy:

• HSSFWorkbook reprezentuje plik MSExcel. Wykorzystujemy ją kiedy chcemy wczytać lub zapisać plik XLS. Służy ona także do tworzenia nowych plików. Na potrzeby tego artykułu przyjmuję, że słowo workbook jest tożsame z plik XLS – jest to byt który zawiera arkusze z danymi.
• HSSFSheet reprezentuje arkusz z danymi.
• POIFSFileSystem zarządza cyklem życia systemu plików. Wykorzystujemy ją m.in. do wczytania pliku do obiektu klasy HSSFWorkbook.

Wczytanie danych z pliku .xls do obiektu HSSFWorkbook polega na utworzeniu obiektu POIFSFileSystem, który przekazywany jest następnie do konstruktora obiektu HSSFWorkbook.
Aby utworzyć obiekt reprezentujący interesujący nas arkusz z danymi, należy wywołać metodę getSheet(nazwa_arkusza) na obiekcie workbooka.

  /**
   * Inicjalizacja obiektu Workbook na podstawie pliku
   * example.xls
   * @throws IOException
   */
  private void initializeWorkbook() throws IOException {
    FileInputStream file = new FileInputStream(EXCEL_FILE);
    POIFSFileSystem poiFileSystem = new POIFSFileSystem(file);
    // klasa HSSFWorkbook reprezentuje plik excela
    this.workbook = new HSSFWorkbook(poiFileSystem);
    file.close();

    sheet = workbook.getSheet(SHEET_NAME);
  }

Wyświetlenie zawartości arkusza polega na iteracji po każdym wierszu z danymi. Następnie, w obrębie danego wiersza druga pętla przechodzi po konkretnych komórkach, wyświetlając ich zawartość.

• HSSFRow reprezentuje rząd (wiersz). Obiekty tego typu przechowywane są w obiektach klasy HSSFSheet.
• HSSFCell reprezentuje komórkę. Obiekty HSSFCell przechowywane są w obiektach klasy HSSFRow. Metody tej klasy pozwalają nam dobrać się m.in. do wartości komórki (get/setRichStringCellValue, get/setNumericCellValue …) czy jej formuły (get/setCellFormula).

Metody sheet.getFirstRowNum() i sheet.getLastRowNum() zwracają odpowiednio numer pierwszego i ostatniego wiersza w którym znajdują się jakiekolwiek dane. Metody row.getFirstCellNum() i row.getLastCellNum() zwracają odpowiednio numer pierwszej i ostatniej komórki danego wiersza w których znajdują się dane. Oczywiście może zdarzyć się taka sytuacja, że pomiędzy pierwszą i ostatnią komórką danego wiersza natrafi się komórka pusta, jak i pomiędzy pierwszym i ostatnim wierszem danego arkusza mogą wystąpić wiersze bez danych. W takiej sytuacji metody sheet.getRow(i) oraz row.getCell(j) zwrócą null. Metoda którą przedstawię poniżej nie posiada zabezpieczeń związanych z taką sytuacją.. ale Ty powinieneś(powinnaś) pamiętać, aby je zaimplementować. Do formatowania wyświetlanych danych użyłem dostępnej od Java 5.0 klasy Formatter. Mimo tego efekt działania metody i tak pozostawia wiele do życzenia ;) Jednak moim zadaniem w tym artykule jest raczej przedstawienie podstawowych możliwości HSSF, a nie języka Java i moich umiejętności posługiwania się nim ;)

Odczyt i zapis wartości komórek należy wykonywać przy pomocy odpowiednich metod get/set*CellValue() – w zależności od typu komórki. Typ sprawdzamy za pomocą metody getCellType() a następnie porównujemy go ze stałymi zdefiniowanymi w klasie HSSFCell (CELL_TYPE_NUMERIC, CELL_TYPE_FORMULA, …). Jeżeli w komórce przechowujemy tekst – nie korzystamy z klasy String, a z HSSFRichTextString. Obecnie istnieją metody obsługujące klasę String, jednak oznaczone są one jako deprecated.

  /**
   * Drukuje arkusz na standardowe wyjscie. Metoda daleka od doskonalosci ;)
   *
   */
  private void printWorksheet() {
    // pierwsza petla przechodzi po wierszach, w ktorych sa jakiekolwiek dane
    for (int i = sheet.getFirstRowNum(); i < sheet.getLastRowNum(); i++) {
      // druga petla przechodzi po komorkach w danym wierszu
      HSSFRow row = sheet.getRow(i + 1);
      for (short j = row.getFirstCellNum(); j < row.getLastCellNum(); j++) {
        StringBuilder stringBuilder = new StringBuilder();
        Formatter formatter = new Formatter(stringBuilder);
        HSSFCell cell = row.getCell(j);
        if (HSSFCell.CELL_TYPE_FORMULA == cell.getCellType() ||
               HSSFCell.CELL_TYPE_NUMERIC == cell.getCellType()) {
          formatter.format("%8.2f", cell.getNumericCellValue());
          System.out.print(stringBuilder.toString());
        } else {
          formatter.format("%15s", cell.getRichStringCellValue());
          System.out.print(stringBuilder.toString());
        }
      }
      System.out.println();
    }
  }

Metoda zmieniająca cenę piwa nie wprowadza do naszej aplikacji właściwie nic nowego. Iterujemy po kolumnie z nazwami produktów i kiedy znajdujemy odpowiedni wiersz, wprowadzamy nową cenę.

  /**
   * Zmiana ceny piwa ! ;)
   * @param newBeerPrice
   * @throws IOException
   */
  private void changeBeerPrice(double newBeerPrice) throws IOException {
    for (int i = sheet.getFirstRowNum(); i < sheet.getLastRowNum(); i++) {
      if (sheet.getRow(i) != null && "Piwo".equals(sheet.getRow(i)
            .getCell(NAME_COL_NUMBER).getRichStringCellValue().getString())) {
        sheet.getRow(i).getCell(PRICE_NET_COL_NUMBER).setCellValue(newBeerPrice);
        break;

      }
    }
  }

Jest jeden haczyk. Jeżeli po wywołaniu metody changeBeerPrice zechcemy wyświetlić zawartość arkusza, to zauważymy, że wartość brutto jak i suma cen brutto nie została przeliczona. Aby wymusić takie przeliczenie należy, według dokumentacji, posłużyć się klasą HSSFFormulaEvaluator. Jednak jak się okazało (i co potwierdzają liczne wpisy na forach internetowych) sposób ten raz działa.. a raz nie – w moim przypadku zdecydowanie obliczanie nie działało. Mimo wszystko poniżej przedstawiam potrzebny kod.

HSSFFormulaEvaluator evaluator = new HSSFFormulaEvaluator(sheet, workbook);
evaluator.evaluateInCell(cell);

Najwyższy już czas aby dodać zniżkę do naszej faktury. Powiedzmy 20% :) Tworzymy cztery komórki za pomocą metody row.createCell(). Dwie z tych komórek będą zawierały tylko opis: Rabat oraz Po rabacie. Kolejna komórka musi przyjmować wartość rabatu (w naszym przypadku 0.20), a ostatnia będzie zawierać formułę obliczającą rabat (suma_cen_brutto * (1 – rabat)). Metoda cell.setCellFormula jako argument przyjmuje String. Kod metody powinien być dość jasny po przebrnięciu przez wcześniejszą część artykułu.

/**
   * Dodaje znizke do naszej faktury
   *
   */
  private void discount() {
    // zapisujemy do arkusza wartosc rabatu
    int rowDicountLine = sheet.getLastRowNum();
    HSSFRow rowDicountValue = sheet.createRow(rowDicountLine + 2);

    HSSFCell cellDiscountValue = rowDicountValue.createCell(PRICE_COL_NUMBER,
                                      HSSFCell.CELL_TYPE_NUMERIC);
    cellDiscountValue.setCellValue(0.20);
    // dodajemy napis ktory informuje ze mamy rabat
    HSSFRichTextString discountString = new HSSFRichTextString("Rabat:");
    rowDicountValue.createCell((short) (PRICE_COL_NUMBER - 1))
                                 .setCellValue(discountString);

    // zapisujemy do arkusza formule obliczajaca wartosc faktury po rabacie
    HSSFRow rowDiscountSum = sheet.createRow(rowDicountLine + 4);
    HSSFCell cellDiscountSum = rowDiscountSum.createCell(PRICE_COL_NUMBER);
    cellDiscountSum.setCellFormula(SUM_CELL + " * " + "(1 - F" + (rowDicountLine + 3) + ")");
    //  dodajemy napis
    HSSFRichTextString afterDiscountString = new HSSFRichTextString("Po rabacie:");
    rowDiscountSum.createCell((short) (PRICE_COL_NUMBER - 1)).setCellValue(afterDiscountString);
  }

Na koniec zostało już tylko zapisanie danych w nowym pliku. Zadanie to wykonujemy poprzez przekazanie obiektu OutputStream do metody write() klasy HSSFWorkbook.

  /**
   * Zapisuje biezacy plik pod wskazana nazwa
   * @param filePath
   * @throws IOException
   */
  private void saveAs(String filePath) throws IOException {
    FileOutputStream fileOutputStream = new FileOutputStream(filePath);
    workbook.write(fileOutputStream);
    fileOutputStream.close();
  }

Rezultat działania naszej aplikacji można podziwiać na screenie poniżej ;)

Co jeszcze oferuje HSSF ?

• Niskopoziomowy dostęp do arkusza dla użytkowników z większymi wymaganiami (niż potrzeby tego artykułu)
• EventModel API dla efektywnego dostępu w trybie tylko do odczytu

O tych funkcjonalnościach wypadałoby napisać parę słów w przyszłości.. ale przed nami jak zwykle mało czasu, a ilość ciekawych tematów zatrważająca :)
Mam nadzieję, że ten krótki wstęp do Apache POI pomoże Wam w zmaganiach z formatem arkusza kalkulacyjnego Microsoftu.

Źródła aplikacji: poi-excel.zip

P.S.
W trakcie tworzenia szkieletu aplikacji za pomocą Maven otrzymałem taki oto komunikat błędu:

Embedded error: Archetype does not exist: Unable to determine the release version

Google zupełnie milczało na ten temat (0 trafień). Próbowałem wykonać kilka różnych zabiegów w celu poprawy sytuacji, ale dopiero skasowanie katalogu .m2 z mojego katalogu domowego i ponowne uruchomienie polecenia mvn:create zaowocowało komunikatem BUILD SUCCESSFUL.