java/10 : java.xml.bind/com/sun/xml/internal/bind/v2/runtime/IllegalAnnotationException.java

IllegalAnnotationException
https://openjdk.java.net/
GPLv2 + Classpath Exception
/*
 * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.xml.internal.bind.v2.runtime;

import java.lang.annotation.Annotation;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;

import com.sun.xml.internal.bind.v2.model.annotation.Locatable;

Signals an incorrect use of JAXB annotations.
Author: Kohsuke Kawaguchi (kk@kohsuke.org)
Since: JAXB 2.0 EA1/**
 * Signals an incorrect use of JAXB annotations.
 *
 * @author Kohsuke Kawaguchi (kk@kohsuke.org)
 * @since JAXB 2.0 EA1
 */
public class IllegalAnnotationException extends JAXBException {

    Read-only list of Locations. /**
     * Read-only list of {@link Location}s.
     */
    private final List<List<Location>> pos;

    private static final long serialVersionUID = 1L;

    public IllegalAnnotationException(String message, Locatable src) {
        super(message);
        pos = build(src);
    }

    public IllegalAnnotationException(String message, Annotation src) {
        this(message,cast(src));
    }

    public IllegalAnnotationException(String message, Locatable src1, Locatable src2) {
        super(message);
        pos = build(src1,src2);
    }

    public IllegalAnnotationException(String message, Annotation src1, Annotation src2) {
        this(message,cast(src1),cast(src2));
    }

    public IllegalAnnotationException(String message, Annotation src1, Locatable src2) {
        this(message,cast(src1),src2);
    }

    public IllegalAnnotationException(String message, Throwable cause, Locatable src) {
        super(message, cause);
        pos = build(src);
    }

    private static Locatable cast(Annotation a) {
        if(a instanceof Locatable)
            return (Locatable)a;
        else
            return null;
    }

    private List<List<Location>> build(Locatable... srcs) {
        List<List<Location>> r = new ArrayList<List<Location>>();
        for( Locatable l : srcs ) {
            if(l!=null) {
                List<Location> ll = convert(l);
                if(ll!=null && !ll.isEmpty())
                    r.add(ll);
            }
        }
        return Collections.unmodifiableList(r);
    }

    Builds a list of Locations out of a Locatable. /**
     * Builds a list of {@link Location}s out of a {@link Locatable}.
     */
    private List<Location> convert(Locatable src) {
        if(src==null)   return null;

        List<Location> r = new ArrayList<Location>();
        for( ; src!=null; src=src.getUpstream())
            r.add(src.getLocation());
        return Collections.unmodifiableList(r);
    }



    Returns a read-only list of Location that indicates where in the source code the problem has happened.  Normally, an annotation error happens on one particular annotation, in which case this method returns a list that contains another list, which in turn contains the location information that leads to the error location (IOW, [ [pos1,pos2,...,posN] ]) 
 Sometimes, an error could occur because of two or more conflicting annotations, in which case this method returns a list that contains many lists, where each list contains the location information that leads to each of the conflicting annotations (IOW, [ [pos11,pos12,...,pos1N],[pos21,pos22,...,pos2M], ... ]) 
 Yet some other time, the runtime can fail to provide any error location, in which case this method returns an empty list. (IOW, []). We do try hard to make sure this won't happen, so please let us know
if you see this behavior.
List of Location
 Each error location is identified not just by one Location object, but by a sequence of Locations that shows why the runtime is led to the place of the error. This list is sorted such that the most specific Location comes to the first in the list, sort of like a stack trace. 
 For example, suppose you specify class Foo to JAXBContext, Foo derives from Bar, Bar has a field pea that points to Zot, Zot contains a gum property, and this property has an errornous annotation. Then when this exception is thrown, the list of Locations will look something like [ "gum property", "Zot class", "pea property", "Bar class", "Foo class" ] 
Returns:  can be empty when no source position is available, but never null. The returned list will never contain null nor length-0 List./**
     * Returns a read-only list of {@link Location} that indicates
     * where in the source code the problem has happened.
     *
     * <p>
     * Normally, an annotation error happens on one particular
     * annotation, in which case this method returns a list that
     * contains another list, which in turn contains the location
     * information that leads to the error location
     * (IOW, {@code [ [pos1,pos2,...,posN] ]})
     *
     * <p>
     * Sometimes, an error could occur because of two or more conflicting
     * annotations, in which case this method returns a list
     * that contains many lists, where each list contains
     * the location information that leads to each of the conflicting
     * annotations
     * (IOW, {@code [ [pos11,pos12,...,pos1N],[pos21,pos22,...,pos2M], ... ]})
     *
     * <p>
     * Yet some other time, the runtime can fail to provide any
     * error location, in which case this method returns an empty list.
     * (IOW, {@code []}). We do try hard to make sure this won't happen,
     * so please <a href="http://jaxb.dev.java.net/">let us know</a>
     * if you see this behavior.
     *
     *
     * <h3>List of {@link Location}</h3>
     * <p>
     * Each error location is identified not just by one {@link Location}
     * object, but by a sequence of {@link Location}s that shows why
     * the runtime is led to the place of the error.
     * This list is sorted such that the most specific {@link Location} comes
     * to the first in the list, sort of like a stack trace.
     *
     * <p>
     * For example, suppose you specify class {@code Foo} to {@link JAXBContext},
     * {@code Foo} derives from {@code Bar}, {@code Bar} has a field {@code pea}
     * that points to {@code Zot}, {@code Zot} contains a {@code gum}
     * property, and this property has an errornous annotation.
     * Then when this exception is thrown, the list of {@link Location}s
     * will look something like
     * {@code [ "gum property", "Zot class", "pea property", "Bar class", "Foo class" ]}
     *
     *
     * @return
     *      can be empty when no source position is available,
     *      but never null. The returned list will never contain
     *      null nor length-0 {@link List}.
     */
    public List<List<Location>> getSourcePos() {
        return pos;
    }

    Returns the exception name, message, and related information
together in one string.
 Overriding this method (instead of JAXBException.printStackTrace allows this crucial detail to show up even when this exception is nested inside other exceptions. /**
     * Returns the exception name, message, and related information
     * together in one string.
     *
     * <p>
     * Overriding this method (instead of {@link #printStackTrace} allows
     * this crucial detail to show up even when this exception is nested
     * inside other exceptions.
     */
    public String toString() {
        StringBuilder sb = new StringBuilder(getMessage());

        for( List<Location> locs : pos ) {
            sb.append("\n\tthis problem is related to the following location:");
            for( Location loc : locs )
                sb.append("\n\t\tat ").append(loc.toString());
        }

        return sb.toString();
    }
}
/

java/ 10/ java.xml.bind/com/sun/xml/internal/bind/v2/runtime/IllegalAnnotationException.java

List of `Location`
