detailed examples of what can be done and how to specify it.

Return Types

The following return types are recognized:

boolean
int
String
org.joda.time.DateTime
any interface (generally annotated with the @XPath annotation)
arrays of any recognized type
lists (java.util.List) of any recognized type => an ArrayList will be instantiated
maps, with keys/values of any recognized types => a HashMap will be instantiated

For instance you may declare this:

@XPath("/book") public interface Book {

    @XPath("@title") String getTitle();

    @XPath("publishedIn") int getPublishYear();

    @XPath("author/name") String[] getAuthorNames();

    @XPath("reference") MyBookReference[] getReferences();

    interface MyBookReference {

        @XPath("@lang") String getLang();

        @XPath("@lang = 'en'") boolean isLangEnglish();
    }

You can mix functions within your XPath expressions, see the XPath Expressions page.

Arrays and Lists

You can declare an array as a return type.

To declare a return type as List, you must specify its component type twice: Once for the Java compiler, and once for the avc-binding-dom API:

@XPath("/book") public interface Book {

    @XPath(value = "reference", collectionComponentType = Reference.class) 
    java.util.List<Reference> getReferences();

If you declare an XPath function for a Java method with a return type of array or List, it will be applied to each node of the collection.

For instance, this will fetch an array of normalized text values:

    @XPath(value = "author/name", function = "normalized-space()") 
    String[] getAuthorNames();

Maps

To declare a return type as a Map, you must specify its key/value types, but also the XPath expressions (and probably the XPath functions) to use for each.

For instance, consider the following XML document:

<books>
   <book title="Treasure Island" lang="en">
       <author> Robert    Louis Stevenson</author>
   </book>
   <book title="L'Île au trésor" lang="fr">
       <author> R. L.           Stevenson</author>
   </book>
</books>

You could map each book to its title in Java with the following annotations:

@XPath("/books") public interface Books {

    @XPath(value = "book",

        mapKeysXPath = "@title", mapKeysType = String.class,

        mapValuesXPath = ".", mapValuesType = Book.class
    ) 
    Map<String, Book> getBooks();

    interface Book {

        @XPath("@title")
        String getTitlte();

        @XPath(value = "author", function = "normalize-space()")
        String getAuthor(); 
    }
}

Then use the bound Java object:

    final Books books = ... // binding 

    final Map<String, Books.Book> map = books.getBooks();

    assertEquals("Treasure Island", map.get("Treasure Island").getTitle());

    assertEquals("R. L. Stevenson", map.get("L'Île au trésor").getAuthor());