001/*
002 * Path.java November 2010
003 *
004 * Copyright (C) 2010, Niall Gallagher <niallg@users.sf.net>
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
015 * implied. See the License for the specific language governing 
016 * permissions and limitations under the License.
017 */
018
019package org.simpleframework.xml;
020
021import java.lang.annotation.Retention;
022import java.lang.annotation.RetentionPolicy;
023
024/**
025 * The <code>Path</code> annotation is used to specify an XML path 
026 * where an XML element or attribute is located. The format must be
027 * in XPath format. When an XML structure does not map exactly to
028 * an object model this annotation can be used to navigate the XML
029 * document in order to map attributes and elements to an associated
030 * field or method. For example, take the annotation shown below.
031 * <pre>
032 * 
033 *    &#64;Element
034 *    &#64;Path("contact-info/phone")
035 *    private String number;
036 * 
037 * </pre>
038 * For the above annotation the XPath expression locates the phone
039 * number nested within several elements. Such a declaration can 
040 * be used when a flat object structure is not suitable. The above
041 * annotations will result in the below XML elements.
042 * <pre>
043 * 
044 *    &lt;contact-info&gt;
045 *       &lt;phone&gt;
046 *          &lt;number&gt;1800123123&lt;/number&gt;
047 *       &lt;/phone&gt;
048 *    &lt;/contact-info&gt;
049 *    
050 * </pre>
051 * As can be seen from this XML snippet a single field has been
052 * mapped with several elements. These XPath expressions can be used
053 * with either elements or attributes to convert an otherwise flat
054 * object to XML structure in to something more complex. This is
055 * useful when mapping objects to foreign XML formats.
056 * <p>
057 * In addition to providing wrappers for existing elements and
058 * attributes the <code>Path</code> annotations can be used to 
059 * provide an ordered set of elements. Order can be applied to the
060 * elements created using an XPath index. For example.
061 * <pre>
062 * 
063 *    &#64;Element
064 *    &#64;Path("contact-info[1]/phone")
065 *    private String home;
066 *    
067 *    &#64;Element
068 *    &#64;Path("contact-info[2]/phone")
069 *    private String office;   
070 *    
071 * </pre>
072 * In the above example we have two element annotations within a
073 * single class. However each one is given an element path with
074 * an index. This tells the serialization process that it should
075 * generate two wrapping elements, ordered by the index specified.
076 * The above annotations will result in the following.
077 * <pre>
078 * 
079 *    &lt;contact-info&gt;
080 *       &lt;phone&gt;
081 *          &lt;home&gt;1800123123&lt;/home&gt;
082 *       &lt;/phone&gt;
083 *    &lt;/contact-info&gt; 
084 *    &lt;contact-info&gt;
085 *       &lt;phone&gt;
086 *          &lt;office&gt;1800123123&lt;/office&gt;
087 *       &lt;/phone&gt;
088 *    &lt;/contact-info&gt;      
089 * 
090 * </pre>
091 * On deserialization the references to fields are known, and
092 * can be read from the order of the wrapping path elements.
093 * This is useful if you need to read specific fields or methods
094 * from an XML document that maintains elements in sequence. If
095 * such sequences contain similarly named child elements, then
096 * the <code>ElementList</code> annotation provides a better
097 * alternative to indexed XPath expressions.
098 * 
099 * @author Niall Gallagher
100 */
101@Retention(RetentionPolicy.RUNTIME)
102public @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}