org.simpleframework.xml
Annotation Type Path

@Retention(value=RUNTIME)
public @interface Path

The Path annotation is used to specify an XML path where an XML element or attribute is located. The format must be in XPath format. When an XML structure does not map exactly to an object model this annotation can be used to navigate the XML document in order to map attributes and elements to an associated field or method. For example, take the annotation shown below.

 
    @Element
    @Path("contact-info/phone")
    private String number;
 
 

For the above annotation the XPath expression locates the phone number nested within several elements. Such a declaration can be used when a flat object structure is not suitable. The above annotations will result in the below XML elements.

 
    <contact-info>
       <phone>
          <number>1800123123</number>
       </phone>
    </contact-info>
    
 

As can be seen from this XML snippet a single field has been mapped with several elements. These XPath expressions can be used with either elements or attributes to convert an otherwise flat object to XML structure in to something more complex. This is useful when mapping objects to foreign XML formats.

In addition to providing wrappers for existing elements and attributes the Path annotations can be used to provide an ordered set of elements. Order can be applied to the elements created using an XPath index. For example.

 
    @Element
    @Path("contact-info[1]/phone")
    private String home;
    
    @Element
    @Path("contact-info[2]/phone")
    private String office;   
    
 

In the above example we have two element annotations within a single class. However each one is given an element path with an index. This tells the serialization process that it should generate two wrapping elements, ordered by the index specified. The above annotations will result in the following.

 
    <contact-info>
       <phone>
          <home>1800123123</home>
       </phone>
    </contact-info> 
    <contact-info>
       <phone>
          <office>1800123123</office>
       </phone>
    </contact-info>      
 
 

On deserialization the references to fields are known, and can be read from the order of the wrapping path elements. This is useful if you need to read specific fields or methods from an XML document that maintains elements in sequence. If such sequences contain similarly named child elements, then the ElementList annotation provides a better alternative to indexed XPath expressions.

Author:

Niall Gallagher

Required Element Summary

java.lang.String

value This method is used to provide the XPath expression for the annotation.

Element Detail

value

public abstract java.lang.String value

This method is used to provide the XPath expression for the annotation. Only a subset of expressions are supported. All path formats can be parsed. However, if the path does not match the supported expressions an exception will be thrown. Some examples of the formats supported are shown below.

 
    ./example/path
    ./example/path/
    example/path
    example[2]/path
    
 

There is no limit to the level of nesting supported. Also the Order annotation supports the above formats so that nested elements can be order for serialization of the fields and methods of the annotated types.

Returns:

this returns an XPath expression for the location