2 minute tutorial - tooltwist/xdata GitHub Wiki

(ok, maybe 5 minutes...)

XData ("Cross Data") allows:

• one part of a program to shovel whatever XML, JSON, etc, is has into a generic data object.
• another part of the program can access that data without caring about whether it's JSON, XML, etc.

Neither the data source nor the data consumer need to worry about APIs, interfaces, or object models.

Figure 1. Separation of Data Source and Data Consumer

The main benefit of this approach is re-use.

For example, a user interface component (e.g. a widget) that receives it's input as XData can accept information from a variety of data sources, without the hassle of compiled-in interfaces and APIs.

Similarly, a data source (such as a call to a Restful web service) that returns it's data as XData can be used by multiple user interface widgets.

The Java object used to implement XData is the class com.tooltwist.xdata.XD.

This object can be constructed using whatever supported data format you have at your disposal.

Creating from a JSON string:

String json = "{ \"data\" : { \"name\": \"Fred Smith\", \"favoriteColor\" : [ \"red\", \"puce\", \"olive\" ] } }";
XD data = new XD(json);

Creating from an XML string:

String xml =
    "<data>" +
    "  <name>Fred Smith</name>" +
    "  <favoriteColor>red<favoriteColor>" +
    "  <favoriteColor>puce<favoriteColor>" +
    "  <favoriteColor>olive<favoriteColor>" +
    "</data>";
XD data = new XD(xml);

Creating from a JSON file:

InputStream inputStream = new FileInputStream("mydata.json");
XD data = new XD(inputStream);

Creating from an XML file:

InputStream inputStream = new FileInputStream("mydata.xml");
XD data = new XD(inputStream);

Note that in these examples, that contents of the files are used to determine the data type, not the filename.

Some of the data types support creating an XData from a specific Java object.

Creating from a DOM XML object (supported by the "xml-dom" data type):

org.w3c.dom.Document document = ....;
XD data = new XD(document);

org.w3c.dom.Node node = ...;
XD data2 = new XD(node);

For details of these specific data types, look at the documentation for the specific data type.

Irrespective of the type of data used to create the XD object, the same API can be used to access the values in the data document. The first step is to get a "selector" object, which can then be used to select specific data values. For full details, see the documentation for XSelectable.

XSelectable selector = data.getSelector();
String name = selector.getString("/data/name");
System.out.println("Name is: " + name);

--> Name is: Fred Smith

XSelectable selector = data.getSelector();
for (XSelectable item : selector.foreach("/data/favoriteColor") {
    String color = selector.getString(".");
    System.out.println("Color: " + color);
}

--> Color: red
--> Color: puce
--> Color: olive

When selecting lists, a cutdown XPath-like syntax is used. This also supports wildcards:

XSelectable selector = data.getSelector();
for (XSelectable item : selector.foreach("/data/*") {
    String fieldname = selector.currentName();
    String value = selector.getString(".");
    System.out.println("Field " + fieldname + "= " + value);
}

--> Field name is Fred Smith
--> Field favoriteColor is red
--> Field favoriteColor is puce
--> Field favoriteColor is olive

By default the XD class will return one of the fast parsers, if one is available. If you wish to use a specific data type, you can ask for it.

XSelectable selector = data.getSelector("xml-dom");
DomXml mySelector = (DomXml) selector;
org.w3c.dom.Document document = mySelector.getDocument();

For details on datatype specific methods, look at the documentation for the data type.

The contents of an XD can be accessed at any time.

String myData = data.toString();

--