Fork me on GitHub

FAQ / HowTo

How to determine if an element or attribute exists?

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. 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.

Previous answer (up to V1.3.0) Up to version 1.4 it was not possible to distinguish between empty values and non existing values. The cause is a limitation by XPath 1.0, which does not allow all expressions to be evaluated as nodes. Getting a string value from non existing elements or attributes returns an empty string. You will never get a null value from projections returning a string. It is even a common practice to omit empty elements in documents. There are two ways to determine if an element exists:

  • Project the element to an empty sub projection. This will return null if the element is not present. You may even reuse the sub projection interface for all elements to be examined.
  • Use a XPath function to create a boolean projection: "count(/path/element) > 0"

    Now it's easier to upgrade to version 1.4.x.

What's the syntax for writable XPath expressions?

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.

Changing attributes

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.

Changing element values

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.

Changing child elements

Example: "/element1/element2/*" This works for projections or collections of projections only. If your setter value is a projection, all existing elements with the same element name will be removed and a single element will be attached.

How to access the DOM behind a projection?

Every projection is associated with a document, every sub projection with a DOM element. To access the DOM Node you may either:

  • Let your projection extend the interface org.xmlbeam.dom.DOMAccess. You will inherit getter methods for the document and the current node.
  • Cast your projection directly to DOMAccess. The projector makes sure that every projection instance implements this interface.
  • Just declare org.w3c.dom.Node as a return type or a parameter on a projection method.

You may change the DOM any time, projections will reflect the changes automatically.

public interface Projection extends MixinOverridingToString {
    // Your projection methods here
}

How do I implement the toString() method for my projection?

With Java 8, just define a defautl mehtod in your projection interface. For Java 6 & 7 you want to create a mixin:

public interface MixinOverridingToString {
    @Override
    String toString();
}

And register it in your projector:

Object mixin = new Object() {
    private DOMAccess me;
    @Override
    public String toString() {
        return "I'm a "+ me.getProjectionInterface().getSimpleName();
    };
};       
projector.mixins().addProjectionMixin(Projection.class, mixin);

Why does the projector not cache values?

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.

How do I change the used XPath engine?

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.

  • If your XPath library keeps the contract of the standard API, it should be sufficient to just define the appropriate property for your URI as described here. This should work out of the box without any code change.
  • If you do not want your implementation be created by the original XPathFactory, you may change the way the projector creates this factory:
    XMLFactoriesConfig myConfig = new DefaultXMLFactoriesConfig() {
        {
            // We should change the behavior of the config to not
            // interfere with the name space handling of an
            // unknown XPath implementation.
            setNamespacePhilosophy(NamespacePhilosophy.AGNOSTIC);
        }
     
        /**
         * Override this method to inject your own factory.
         */
        @Override
        public XPathFactory createXPathFactory() {
            return new MyOwnXpathFactory();
        }
    };
     
    XBProjector projector = new XBProjector(myConfig);
  • If you do not want any XPathFactory involved, you even may bypass this:
    XMLFactoriesConfig myConfig = new DefaultXMLFactoriesConfig() {
        {
            // We should change the behavior of the config to not
            // interfere with the name space handling of an
            // unknown XPath implementation.
            setNamespacePhilosophy(NamespacePhilosophy.AGNOSTIC);
        }
     
        /**
         * Or override this to bypass the factory and create your own XPath implementation here.
         */
        @Override
        public XPath createXPath(Document... document) {
            return super.createXPath(document);
        }
    };
     
    XBProjector projector = new XBProjector(myConfig);