Fork me on GitHub

Tutorial Examples

These tutorials guide you through real life examples, each demonstrating a couple of XMLBeam features. You will find these examples ready to run as JUnit tests in "src/test/java/tutorial". Each example works on real life XML Data and targets different aspects of data projections.

Have fun!

E01: Printing some weather data

This example should give you a first impression of the basic XMLBeam features:

  • Accessing XML attributes with automatic type conversion.
  • Sub projections grouping data

Start tutorial 1

E02: Reading previously unknown elements of a Jenkins Job Configuration.

In the last example we demonstrated a sub projection pretending a non existing element.

This time we like to define some model classes for a Jenkins job configuration and project existing elements to them. But there is one little hurdle: We can not know the exact XML structure, because Jenkins plugins contribute new elements with different names. Our model would have to include one class for each contributed element, but we like to keep the number of model classes low.

The solution to this shows:

  • Usage of XPath wildcards. Mapping of varying elements to one Java object.
  • Automatic conversion of sequences to lists and arrays utilizing Java generics to provide a static typed API.
  • Declarative document origins. Just add a source URL via annotation, let the framework get the document.
  • Inheritance in projection interface. Java interface inheritance is still supported in projection interfaces.

Instead of defining one model class for each element, we project all elements doing the same stuff to the same model object. This is done by using XPath wildcards that will simply select all elements in a defined subtree. Of course we define a getter method to give us the element name, so we can use our model to find out what which elements are really in there.

Start tutorial 2

E03: Use a dynamic projection to project parts of a Eclipse configuration file

Eclipse code formatter settings are stored in profiles. In this example we like to access the data of a certain profile. Features shown in this example:

  • Dynamic projections Getter methods may be declared with parameters. There parameters will fill placeholders in the XPath declaration to build up the final XPath expression. Syntax of this is the MessageFormat format syntax.

Start tutorial 3

E04: Reuse a subprojection to different Maven POM elements

A Maven project has a group id, artifact id and a version. So does a Maven dependency. Now we reuse the same sub projection for unrelated, but similar parts of the document. This is possible because the structure of our projection does not need to follow the structure of the document.

Second we define a simple setter in the projection interface to show how element values can be modified.

Start tutorial 4

E05: Filtering a RSS feed

This example is to demonstrate how to modify a XML document. The Slashdot RSS feed is projected to this interface and the stories will be accessible via a subprojection. This time there is a setter for a collection of Stories which will replace the existing sequence of rss items. Instead of just setting an elements value like in the last example, we now change a sequence of elements. Notice that there are name spaces in the source XML document and that we work with them intuitively.

Start tutorial 5

E06: Creating a XHTML document from scratch

Finally we go the other way around. We create a new document and fill the content via a projection. (Not that it would not be productive to create a website this way, just a demonstration.)

Start tutorial 6

E07: Using mixins to sort SVG elements

Demonstation of the concept of "projection mixins". While its not possible to let your own classes implements projection interfaces without losing the projection functionality, it is possible to define methods in a second interface called a mixin interface. If you let a projection extend a mixin interface, any object implementing the mixin interface can be registered to handle the method calls of the mixin interface. In this example the interface Comparable will be our mixin interface. (Of course you may choose your own interfaces.) Its possible to have a projection extending multiple mixin interfaces. Notice: Because the method call of a mixin method on a projection will not be executed by the projection instance itself but by your specified mixin implementation, we need a field to inject the current projection instance into. By convention this field must me named "me" (to resemble the keyword "this") and have the type of the projection. It may be private. (Yes, the result of this example could have been archived by specifying a Comparator when calling Collections.sort().)

Start tutorial 7

E08: Demonstrating API Mimicry

In this tutorial we make extensive use of XPath to mimicry an existing 3rd Party-API.

Start tutorial 8

E09 Bundling multiple documents to a virtual projection

This tutorial introduces the concept of "external projections". You may specify a document origin per projection method. This way a projection may project data of multiple documents into one Java object. As example we take the XML interfaces of a Dreambox. A Dreambox is a hard disk video recorder with a web based interface that works with XML data exchange from multiple URLs. This example is provided to show a real life use case for integration of multiple external documents to one Java interface. You are surly not able to run this example without access to specific version of this hard disk recorder. Therefore there is no example code provided which uses this interface.

Start tutorial 9

E10 Parsing HTML Documents

This tutorial demonstrates the expressiveness of XMLBeam projections. Four web pages about different programming languages will be fetched from Wikipedia and their creator will be extracted. * Shows a projection to HMTL Documents

Start tutorial 10

E11 Using XPath to split the input data

In this tutorial we will render a mindmap as formatted characters. Our algotithm will need the input data split into left and right sides. The task of splitting the mindmap will be done by the projection.

Start tutorial 11

E12 Creating 3D data using a document template

Instead of parsing existing data we will now create a new document by enriching a prepared document template with calculated values.

Start tutorial 12

E13 Creating subprojections with element templates

This tutorial demonstrates the creation of elements via template elements. This is achieved by reading template documents and using this projections as sub projections in other template projections. The transition from document projections to element sub projections works just as desired.

Start tutorial 13

E14 Using a custom type conversion to modify KML coordinates

This tutorial demonstrates the usage of a custom made type converter. We implement a new Java List "CoordinateList" which will handle our user defined type Coordinate. So far this is not related to data projection, it's just the scenario build up to show how easy user defined typed may be integrated. The actual configuration of the projector is basically just one line of code.

Start tutorial 14

E15 Reading a complex plist structure and deriving the XPath from method names

In this tutorial we address quite a few challenges in accessing the data in plist files. XML plists (XML Property Lists) files are key/value based data storages frequently used by OS X applications. The challenge is that the data is not stored in the key element, but besides. A key element is followed by an additional element holding the data. The name of the data containing element depends on the type of data. So we need some real XPath magic to cover this :) The second challenge is that we don't like to have XPath expressions specified for all data in the file. Instead we like to derive the key value of the expression from the method name. Last but not least we show how to switch the DTD validation of, in case your not on an OS X system.

Start tutorial 15

E16 Using an XML schema to define default values and validate the document

This example shows how to use a schema with your projections.

This time we read some data from xml files which use a defined schema. This way we can handle default values for attributes and honor restrictions.

The solution to this shows:

  • Usage of a schema for validation xml source.
  • Reading default values specified in a schema works as expected.

Start tutorial 16

E18 Using XMLBeam without a projection interface to resolve a postal code

This example demonstrates using XMLBeam without a projection interface.

  • Using direct evaluation API
  • Retrieve data from multiple address components without iterating manually through elements

Start tutorial 18