content: /*
   * Path.java November 2010
   *
   * Copyright (C) 2010, Niall Gallagher <niallg@users.sf.net>
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
   * implied. See the License for the specific language governing 
   * permissions and limitations under the License.
   */
  
  package com.aliyun.odps.simpleframework.xml;
  
  import java.lang.annotation.Retention;
  import java.lang.annotation.RetentionPolicy;
  
  /**
   * The <code>Path</code> 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.
   * <pre>
   * 
   *    &#64;Element
   *    &#64;Path("contact-info/phone")
   *    private String number;
   * 
   * </pre>
   * 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.
   * <pre>
   * 
   *    &lt;contact-info&gt;
   *       &lt;phone&gt;
   *          &lt;number&gt;1800123123&lt;/number&gt;
   *       &lt;/phone&gt;
   *    &lt;/contact-info&gt;
   *    
   * </pre>
   * 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.
   * <p>
   * In addition to providing wrappers for existing elements and
   * attributes the <code>Path</code> 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.
   * <pre>
   * 
   *    &#64;Element
   *    &#64;Path("contact-info[1]/phone")
   *    private String home;
   *    
   *    &#64;Element
   *    &#64;Path("contact-info[2]/phone")
   *    private String office;   
   *    
   * </pre>
   * 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.
   * <pre>
   * 
   *    &lt;contact-info&gt;
   *       &lt;phone&gt;
   *          &lt;home&gt;1800123123&lt;/home&gt;
   *       &lt;/phone&gt;
   *    &lt;/contact-info&gt; 
   *    &lt;contact-info&gt;
   *       &lt;phone&gt;
   *          &lt;office&gt;1800123123&lt;/office&gt;
   *       &lt;/phone&gt;
   *    &lt;/contact-info&gt;      
   * 
   * </pre>
   * 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 <code>ElementList</code> annotation provides a better
   * alternative to indexed XPath expressions.
   * 
   * @author Niall Gallagher
   */
  @Retention(RetentionPolicy.RUNTIME)
  public @interface Path {
     
     /**
      * 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.
      * <pre>
      * 
      *    ./example/path
      *    ./example/path/
      *    example/path
      *    example[2]/path
      *    
      * </pre>
      * There is no limit to the level of nesting supported. Also 
      * the <code>Order</code> annotation supports the above formats
      * so that nested elements can be order for serialization of
      * the fields and methods of the annotated types.
      * 
      * @return this returns an XPath expression for the location
      */
     String value();
  }
  