2016/04/10 - Apache Wookie has been retired.

For more information, please explore the Attic.

The code that Wookie uses to parse and unpack W3C Widgets can also be used in other applications and projects as a standalone library. The parser can be found as a sub-project within the "parser/java/" folder in the main Wookie source tree.

Using the parser in a Maven project

To use the parser with a Maven project, include the following dependency configuration in your project:

<dependency>
 <groupId>org.apache.wookie</groupId>
 <artifactId>wookie-parser</artifactId>
 <type>jar</type>
 <scope>compile</scope>
 <version>0.10.0-incubating</version>
</dependency>

Using the parser as a jar download

If you don't want to use Maven, you can download the jar from the Apache repository or use a copy that is distributed in the latest Wookie release. Just make sure you also include its dependencies (Jdom, icu4j, slf4j, commons-httpclient, commons-logging, commons-compress, commons-io and commons-lang).

Building the parser

To build the parser as a standalone .jar, run ant publish-local from within the parser folder; the jar will be saved in parser/dist. Dependencies are described in the ivy.xml file that can also be found in the parser/dist folder.

Using the parser

The parser is invoked using a W3CWidgetFactory object. This has a number of configuration properties that can be set, and these are described at the bottom of this page. While most of these are optional, to use the factory to parse .wgt files you MUST supply a valid output directory into which the W3CWidgetFactory will unpack the widget.

For example, a simple program to unpack a .wgt file, and write the name of the widget to the console looks like this:

public static void main(String[] args) {
    File out = new File("out");
    File zipFile = new File("in/butterfly.wgt");

    W3CWidgetFactory fac = new W3CWidgetFactory();
    fac.setOutputDirectory(out.getAbsolutePath());
    fac.setLocalPath("/out");
    try {
        W3CWidget widget = fac.parse(zipFile);
        System.out.println(widget.getLocalName("en"));
    } catch (BadWidgetZipFileException e) {
        e.printStackTrace();
    } catch (BadManifestException e) {
        e.printStackTrace();
    }
}

The W3CWidgetFactory can also download and install widgets directly from a URL as well as locally from the file system:

W3CWidget widget = fac.parse(new URL("http://foo.com/bar.wgt"));

Note that if the widget does not use the application/widget content-type, you should set "ignore content type" to true:

W3CWidget widget = fac.parse(new URL("http://foo.com/bar.wgt"), true);

Localized elements

Many of the elements of a W3CWidget object are localized; these elements all implement the ILocalizedElement interface. These elements can be processed using the LocalizationUtils class, which has methods to process these elements based on lists of preferred locales. E.g., to extract the single most preferred Name element for the "fr" locale:

 INameEntity[] names = widget.getNames().toArray(new INameEntity[widget.getNames().size()]);
 String[] locales = new String[]{"fr"};
 INameEntity name = (INameEntity)LocalizationUtils.getLocalizedElement(names, locales,widget.getDefaultLocale());

LocalizationUtils uses icu4j to process elements using appropriate fallback strategies based on language variants and extensions.

Outputter

As well as a parser, the parser library also has a WidgetOutputter class that can be used to export config.xml files that conform to the W3C Widgets: Packaging and Configuration specification.

To export a config.xml for a W3CWidget object as a String :

    W3CWidget widget = myWidget;
    WidgetOutputter outputter = new WidgetOutputter();
    outputter.setWidgetFolder("/widgets");
    String configXml = outputter.outputXMLString(widget);

To export a config.xml to an OutputStream use:

   W3CWidget widget = myWidget;
   WidgetOutputter outputter = new WidgetOutputter();
   outputter.setWidgetFolder("/widgets");   
   FileOutputStream out = new FileOutputStream(new File("config.xml"));
   outputter.outputXML(widget, out);

Factory properties reference

outputDirectory

The directory where the widget will be saved. The factory will expand the widget archive into this directory, using the widget's identifier to generate a directory name and structure in which to place it

startPageProcessor

An implementation of the IStartPageProcessor interface. Setting this property allows you to inject a class that can pre-process start pages for the widget; for example to inject javascript, tidy up HTML, insert template code etc. If this is not set, no pre-processing is done by the factory.

locales

The supported locales (as BCP47 language-tags) to be processed for the widget. This determines which start files, icons, and other localized elements will be processed and expanded. This is set to "en" by default

encodings

The supported encodings to be processed for the widget. This determines which custom encodings will be allowed for start files. This is set to UTF-8 by default.

localPath

The base URL from which unpacked widgets will be served, e.g. "/myapp/widgets". The URLs of start files will be appended to this base URL to create the widget URL. The default value of this property is "/widgets"

features

The features supported by the implementation; this should be supplied as IRIs e.g. "http://wave.google.com". The features are matched against features requested by the widget; if the widget requires features that are unsupported, an Exception will be thrown when parsing the widget package. The default value of this property is an empty String array.