Since Version 1.4.0 you can expect a null value returned if an element does not exist. The projector will determine the type of the XPath expression and invoke the evaluation accordingly whether it is a function, a node value or a node itself. If you want to avoid null checks, specify java.util.Optional as return type. If you want non existing nodes to be handled like existing empty ones, set the flag ABSENT_IS_EMPTY on projector creation.
Since Version 1.4.1 you can choose to let the projection method throw an exception if a value is absent. Just declare your method with the suffix "throws some exception type", with your own exception or use a standard JDK exception. It may be a checked or unchecked exception. If your getter method takes parameters and your exception has a constructor matching these parameters, this constructor will be used to create the exception. You won't get any exception if you choose the ABSENT_IS_EMPTY flag. You may not specify Optional as return type if you declare an exception to be thrown.
XPath expressions used in setters (methods with @XBWrite) are limited to absolute paths of non-ambiguous selectors. Functions are not allowed. The reason for this is to make a setter executable regardless of the current document structure, having a reproducible result. If you just need to change values in your DOM tree, use the @XBUpdate annotation on your method. This will allow full XPath syntax.
Example: "/element1/element2/@AttributeName" This works for any setter value that is not a projection nor a collection. The toString() method will be used to create the attribute value.
Example: "/element1/element2" This works for any setter value that is not a projection nor a collection. The toString() method will be used to create the attribute value.
Every projection is associated with a document, every sub projection with a DOM element. To access the DOM Node you may either:
You may change the DOM any time, projections will reflect the changes automatically.
You can easily implement your own toString() method which can access your projection getter methods. With Java 8, just define a default mehtod with the same signature as the Object.toString() signature in your projection interface, but a different name. For example you can choose "String asString()" or "String toString_()". Then add a @XBOverride annotation with the name of the method this default method should override.
For Java 6 & 7 you need to create a mixin:
And register it in your projector:
Caching is not a concern of this library. Implement your own cache to avoid unnecessary XPath overhead. The projector does not know anything about the purpose of the data it reads. To be able to circumvent unexpected caching side effects you need knowledge about the application context. The XPath expression however is cached, to avoid multiple compilations of the same expression.
There are three different ways to change the underlying XPath implementation. You should be able to get everything running that implements the javax.xml.xpath.XPath interface.