Coverage Report - org.simpleframework.xml.Path
 
Classes in this File Line Coverage Branch Coverage Complexity
Path
N/A
N/A
0
 
 1  
 /*
 2  
  * Path.java November 2010
 3  
  *
 4  
  * Copyright (C) 2010, Niall Gallagher <niallg@users.sf.net>
 5  
  *
 6  
  * Licensed under the Apache License, Version 2.0 (the "License");
 7  
  * you may not use this file except in compliance with the License.
 8  
  * You may obtain a copy of the License at
 9  
  *
 10  
  *     http://www.apache.org/licenses/LICENSE-2.0
 11  
  *
 12  
  * Unless required by applicable law or agreed to in writing, software
 13  
  * distributed under the License is distributed on an "AS IS" BASIS,
 14  
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
 15  
  * implied. See the License for the specific language governing 
 16  
  * permissions and limitations under the License.
 17  
  */
 18  
 
 19  
 package org.simpleframework.xml;
 20  
 
 21  
 import java.lang.annotation.Retention;
 22  
 import java.lang.annotation.RetentionPolicy;
 23  
 
 24  
 /**
 25  
  * The <code>Path</code> annotation is used to specify an XML path 
 26  
  * where an XML element or attribute is located. The format must be
 27  
  * in XPath format. When an XML structure does not map exactly to
 28  
  * an object model this annotation can be used to navigate the XML
 29  
  * document in order to map attributes and elements to an associated
 30  
  * field or method. For example, take the annotation shown below.
 31  
  * <pre>
 32  
  * 
 33  
  *    &#64;Element
 34  
  *    &#64;Path("contact-info/phone")
 35  
  *    private String number;
 36  
  * 
 37  
  * </pre>
 38  
  * For the above annotation the XPath expression locates the phone
 39  
  * number nested within several elements. Such a declaration can 
 40  
  * be used when a flat object structure is not suitable. The above
 41  
  * annotations will result in the below XML elements.
 42  
  * <pre>
 43  
  * 
 44  
  *    &lt;contact-info&gt;
 45  
  *       &lt;phone&gt;
 46  
  *          &lt;number&gt;1800123123&lt;/number&gt;
 47  
  *       &lt;/phone&gt;
 48  
  *    &lt;/contact-info&gt;
 49  
  *    
 50  
  * </pre>
 51  
  * As can be seen from this XML snippet a single field has been
 52  
  * mapped with several elements. These XPath expressions can be used
 53  
  * with either elements or attributes to convert an otherwise flat
 54  
  * object to XML structure in to something more complex. This is
 55  
  * useful when mapping objects to foreign XML formats.
 56  
  * <p>
 57  
  * In addition to providing wrappers for existing elements and
 58  
  * attributes the <code>Path</code> annotations can be used to 
 59  
  * provide an ordered set of elements. Order can be applied to the
 60  
  * elements created using an XPath index. For example.
 61  
  * <pre>
 62  
  * 
 63  
  *    &#64;Element
 64  
  *    &#64;Path("contact-info[1]/phone")
 65  
  *    private String home;
 66  
  *    
 67  
  *    &#64;Element
 68  
  *    &#64;Path("contact-info[2]/phone")
 69  
  *    private String office;   
 70  
  *    
 71  
  * </pre>
 72  
  * In the above example we have two element annotations within a
 73  
  * single class. However each one is given an element path with
 74  
  * an index. This tells the serialization process that it should
 75  
  * generate two wrapping elements, ordered by the index specified.
 76  
  * The above annotations will result in the following.
 77  
  * <pre>
 78  
  * 
 79  
  *    &lt;contact-info&gt;
 80  
  *       &lt;phone&gt;
 81  
  *          &lt;home&gt;1800123123&lt;/home&gt;
 82  
  *       &lt;/phone&gt;
 83  
  *    &lt;/contact-info&gt; 
 84  
  *    &lt;contact-info&gt;
 85  
  *       &lt;phone&gt;
 86  
  *          &lt;office&gt;1800123123&lt;/office&gt;
 87  
  *       &lt;/phone&gt;
 88  
  *    &lt;/contact-info&gt;      
 89  
  * 
 90  
  * </pre>
 91  
  * On deserialization the references to fields are known, and
 92  
  * can be read from the order of the wrapping path elements.
 93  
  * This is useful if you need to read specific fields or methods
 94  
  * from an XML document that maintains elements in sequence. If
 95  
  * such sequences contain similarly named child elements, then
 96  
  * the <code>ElementList</code> annotation provides a better
 97  
  * alternative to indexed XPath expressions.
 98  
  * 
 99  
  * @author Niall Gallagher
 100  
  */
 101  
 @Retention(RetentionPolicy.RUNTIME)
 102  
 public @interface Path {
 103  
    
 104  
    /**
 105  
     * This method is used to provide the XPath expression for the
 106  
     * annotation. Only a subset of expressions are supported. All
 107  
     * path formats can be parsed. However, if the path does not 
 108  
     * match the supported expressions an exception will be thrown.
 109  
     * Some examples of the formats supported are shown below.
 110  
     * <pre>
 111  
     * 
 112  
     *    ./example/path
 113  
     *    ./example/path/
 114  
     *    example/path
 115  
     *    example[2]/path
 116  
     *    
 117  
     * </pre>
 118  
     * There is no limit to the level of nesting supported. Also 
 119  
     * the <code>Order</code> annotation supports the above formats
 120  
     * so that nested elements can be order for serialization of
 121  
     * the fields and methods of the annotated types.
 122  
     * 
 123  
     * @return this returns an XPath expression for the location
 124  
     */
 125  
    String value();
 126  
 }