JDOM2 Feature Generics

rolfl edited this page Apr 1, 2012 · 2 revisions

'Generics' has been applied to all levels of JDOM, in too many places to list them all, but of significance are:

  • Element (and where applicable, Document) Content, Namespace and Attribute collection manipulation
  • XPath expressions
  • XSL Transform interfaces

Some of the major changes are described in more depth.

Generic Collections

All Collection-based values now have the correct generic typing, and, where it is not possible to guarantee a generic type through the JDOM API, the Filter class can be used to 'coerce' the data in to the correct type. In other words, the Filter class not only applies a Generic typing to the data, but it (silently) filters out any content that does not conform to the Filter's specification.

This makes the following types of code structures possible (using CDATA as an example):

List<CDATA> childcdata = rootelement.getContent(Filters.cdata());

Or, put a different way, it also makes nicely typed loops possible:

for (CDATA cdata : rootelement.getContent(Filters.cdata()) {

Co-Variant Return types

JDOM has always allowed the 'chaining' of JDOM method calls (where possible). For example:

    Element root = new Element("root");
    root.setAttribute("att","val").addContent(new Text("string"));

This functionality has been expanded where possible to other areas, using a common underlying API, but returning appropriate data types.

For example, JDOM has always had the public Content detach(); method on the Content types. Now in JDOM2 the actual Content's type is returned (which allows chaining of methods, and reduces the requirement for casting values):

    Element p = new Element("parent");
    Element c = new Element("child");
    c.detach().setAttribute("att", "val");

Methods impacted by this type of change are:

  • detach()
  • setParent()
  • clone()
  • CDATA.setText() now returns CDATA (not Text).
  • Parent.addContent(*)