117 * <p> |
117 * <p> |
118 * Normally, an annotation error happens on one particular |
118 * Normally, an annotation error happens on one particular |
119 * annotation, in which case this method returns a list that |
119 * annotation, in which case this method returns a list that |
120 * contains another list, which in turn contains the location |
120 * contains another list, which in turn contains the location |
121 * information that leads to the error location |
121 * information that leads to the error location |
122 * (IOW, <tt>[ [pos1,pos2,...,posN] ]</tt>) |
122 * (IOW, {@code [ [pos1,pos2,...,posN] ]}) |
123 * |
123 * |
124 * <p> |
124 * <p> |
125 * Sometimes, an error could occur because of two or more conflicting |
125 * Sometimes, an error could occur because of two or more conflicting |
126 * annotations, in which case this method returns a list |
126 * annotations, in which case this method returns a list |
127 * that contains many lists, where each list contains |
127 * that contains many lists, where each list contains |
128 * the location information that leads to each of the conflicting |
128 * the location information that leads to each of the conflicting |
129 * annotations |
129 * annotations |
130 * (IOW, <tt>[ [pos11,pos12,...,pos1N],[pos21,pos22,...,pos2M], ... ]</tt>) |
130 * (IOW, {@code [ [pos11,pos12,...,pos1N],[pos21,pos22,...,pos2M], ... ]}) |
131 * |
131 * |
132 * <p> |
132 * <p> |
133 * Yet some other time, the runtime can fail to provide any |
133 * Yet some other time, the runtime can fail to provide any |
134 * error location, in which case this method returns an empty list. |
134 * error location, in which case this method returns an empty list. |
135 * (IOW, <tt>[]</tt>). We do try hard to make sure this won't happen, |
135 * (IOW, {@code []}). We do try hard to make sure this won't happen, |
136 * so please <a href="http://jaxb.dev.java.net/">let us know</a> |
136 * so please <a href="http://jaxb.dev.java.net/">let us know</a> |
137 * if you see this behavior. |
137 * if you see this behavior. |
138 * |
138 * |
139 * |
139 * |
140 * <h3>List of {@link Location}</h3> |
140 * <h3>List of {@link Location}</h3> |
144 * the runtime is led to the place of the error. |
144 * the runtime is led to the place of the error. |
145 * This list is sorted such that the most specific {@link Location} comes |
145 * This list is sorted such that the most specific {@link Location} comes |
146 * to the first in the list, sort of like a stack trace. |
146 * to the first in the list, sort of like a stack trace. |
147 * |
147 * |
148 * <p> |
148 * <p> |
149 * For example, suppose you specify class <tt>Foo</tt> to {@link JAXBContext}, |
149 * For example, suppose you specify class {@code Foo} to {@link JAXBContext}, |
150 * <tt>Foo</tt> derives from <tt>Bar</tt>, <tt>Bar</tt> has a field <tt>pea</tt> |
150 * {@code Foo} derives from {@code Bar}, {@code Bar} has a field {@code pea} |
151 * that points to <tt>Zot</tt>, <tt>Zot</tt> contains a <tt>gum</tt> |
151 * that points to {@code Zot}, {@code Zot} contains a {@code gum} |
152 * property, and this property has an errornous annotation. |
152 * property, and this property has an errornous annotation. |
153 * Then when this exception is thrown, the list of {@link Location}s |
153 * Then when this exception is thrown, the list of {@link Location}s |
154 * will look something like |
154 * will look something like |
155 * <tt>[ "gum property", "Zot class", "pea property", "Bar class", "Foo class" ]</tt> |
155 * {@code [ "gum property", "Zot class", "pea property", "Bar class", "Foo class" ]} |
156 * |
156 * |
157 * |
157 * |
158 * @return |
158 * @return |
159 * can be empty when no source position is available, |
159 * can be empty when no source position is available, |
160 * but never null. The returned list will never contain |
160 * but never null. The returned list will never contain |