001package Torello.Java.Additional;
002
003import javax.json.*;
004
005/**
006 * The parent class of all Json Binding Exceptions that are used for <B>{@link JsonArray}</B>
007 * element retrieval errors.  In order to hopefully continue to make easy-code actually look easy,
008 * the following keywords used in this exception's name are broken down below.
009 * 
010 * <BR /><BR /><B>NOTE:</B> This class is abstract, and cannot be instantiated.
011 * 
012 * <EMBED CLASS=globalDefs DATA-STRUCT=JsonArray DATA-TYPE=Array DATA-TYPE_ABBREV=Arr>
013 * <EMBED CLASS='external-html' DATA-FILE-ID=JE_FIELD_B_ARR>
014 */
015@Torello.HTML.Tools.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JE_B_UL")
016public abstract class JsonBindingArrException extends JsonBindingException
017{
018    /** <EMBED CLASS="external-html" DATA-FILE-ID="SVUIDEX">  */
019    public static final long serialVersionUID = 1;
020
021    /**
022     * <EMBED CLASS="external-html" DATA-FILE-ID="EXPF">
023     * 
024     * <BR /><BR />This is the array index into the source <B>{@code JsonArray}</B> which contained
025     * the element (or lack-there-of) that has caused this exception.
026     */
027    public final int index;
028
029    /**
030     * Constructs a {@code JsonBindingArrException} with no specified detail messsage,
031     * and the user-provided convenience-field values.
032     * 
033     * @param errorSourceJsonArray  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_ESJA>
034     * @param index                 <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_I>
035     * @param expectedJsonType      <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EJT>
036     * @param valueRetrieved        <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_VR>
037     * @param methodReturnJavaType  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_MRJT>
038     * @param endingNote            <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EN>
039     */
040    public JsonBindingArrException(
041            JsonArray           errorSourceJsonArray,
042            int                 index,
043            JsonValue.ValueType expectedJsonType,
044            JsonValue           valueRetrieved,
045            Class<?>            methodReturnJavaType,
046            String              endingNote
047        )
048    {
049        super(
050            BASE_MESSAGE_ARR(
051                errorSourceJsonArray, index, expectedJsonType, valueRetrieved,
052                methodReturnJavaType, endingNote
053            ),
054            errorSourceJsonArray, expectedJsonType, valueRetrieved,
055            methodReturnJavaType
056        );
057
058        this.index = index;
059    }
060
061    /**
062     * Constructs a {@code JsonBindingArrException} with the specified detail message, and
063     * user-provided convenience-field values.
064     * 
065     * @param message the detail message.
066     * @param errorSourceJsonArray  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_ESJA>
067     * @param index                 <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_I>
068     * @param expectedJsonType      <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EJT>
069     * @param valueRetrieved        <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_VR>
070     * @param methodReturnJavaType  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_MRJT>
071     */
072    public JsonBindingArrException(
073            String              message,
074            JsonArray           errorSourceJsonArray,
075            int                 index,
076            JsonValue.ValueType expectedJsonType,
077            JsonValue           valueRetrieved,
078            Class<?>            methodReturnJavaType
079        )
080    {
081        super(
082            message, errorSourceJsonArray, expectedJsonType, valueRetrieved,
083            methodReturnJavaType
084        );
085
086        this.index = index;
087    }
088
089    /**
090     * Constructs a new {@code JsonBindingArrException} with the specified detail message and cause
091     * 
092     * <BR /><BR /><B>NOTE:</B> The detail message associated with cause is not automatically
093     * incorporated in this exception's detail message.
094     * 
095     * @param message The detail message (which is saved for later retrieval by the
096     * {@code Throwable.getMessage()} method).
097     * 
098     * @param cause the cause (which is saved for later retrieval by the
099     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
100     * cause is nonexistent or unknown.)
101     * 
102     * @param errorSourceJsonArray  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_ESJA>
103     * @param index                 <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_I>
104     * @param expectedJsonType      <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EJT>
105     * @param valueRetrieved        <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_VR>
106     * @param methodReturnJavaType  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_MRJT>
107     */
108    public JsonBindingArrException(
109            String              message,
110            Throwable           cause,
111            JsonArray           errorSourceJsonArray,
112            int                 index,
113            JsonValue.ValueType expectedJsonType,
114            JsonValue           valueRetrieved,
115            Class<?>            methodReturnJavaType
116        )
117    {
118        super(
119            message, cause, errorSourceJsonArray, expectedJsonType, valueRetrieved,
120            methodReturnJavaType
121        );
122
123        this.index = index;
124    }
125
126    /**
127     * Constructs a new {@code JsonBindingArrException} with the specified cause and a detail
128     * message of {@code (cause==null ? null : cause.toString())} (which typically contains the
129     * class and detail message of cause).  This constructor is useful for exceptions that are
130     * little more than wrappers for other throwables.
131     * 
132     * @param cause The cause (which is saved for later retrieval by the
133     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
134     * cause is nonexistent or unknown.)
135     * 
136     * @param errorSourceJsonArray  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_ESJA>
137     * @param index                 <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_I>
138     * @param expectedJsonType      <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EJT>
139     * @param valueRetrieved        <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_VR>
140     * @param methodReturnJavaType  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_MRJT>
141     * @param endingNote            <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EN>
142     */
143    public JsonBindingArrException(
144            Throwable           cause,
145            JsonArray           errorSourceJsonArray,
146            int                 index,
147            JsonValue.ValueType expectedJsonType,
148            JsonValue           valueRetrieved,
149            Class<?>            methodReturnJavaType,
150            String              endingNote
151        )
152    {
153        super(
154            BASE_MESSAGE_ARR(
155                errorSourceJsonArray, index, expectedJsonType, valueRetrieved,
156                methodReturnJavaType, endingNote, cause
157            ),
158            cause, errorSourceJsonArray, expectedJsonType, valueRetrieved,
159            methodReturnJavaType
160        );
161
162        this.index = index;
163    }
164
165    /**
166     * A simple helper method for printing a consistent error messge using the input-data
167     * convenience fields of <B>{@code JsonArray's}</B>.
168     * 
169     * @param errorSourceJsonArray  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_ESJA>
170     * @param index                 <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_I>
171     * @param expectedJsonType      <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EJT>
172     * @param valueRetrieved        <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_VR>
173     * @param methodReturnJavaType  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_MRJT>
174     * @param endingNote            <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EN>
175     * @param causes                Optional Parameter.  At most 1 cause is printed.
176     * 
177     * @return The error message {@code String}.
178     */
179    protected static String BASE_MESSAGE_ARR(
180            JsonArray           errorSourceJsonArray,
181            int                 index,
182            JsonValue.ValueType expectedJsonType,
183            JsonValue           valueRetrieved,
184            Class<?>            methodReturnJavaType,
185            String              endingNote,
186            Throwable...        causes // This is an optional parameter
187        )
188    {
189        return 
190            ((endingNote != null) ? endingNote : "") +"\n" +
191            CAUSE_MESSAGE(causes) +
192            "\tFound In JsonArray:       " + ABBREV_STRUCT(errorSourceJsonArray) + "\n" +
193            "\tAt Index:                 " + index + "\n" +
194            "\tExpected Json-Type:       " + JT_STR(expectedJsonType) + "\n" +
195            "\tContained JsonValue:      " + ABBREV_VAL(valueRetrieved) + "\n" +
196            "\tHaving Actual Json-Type:  " + JT_STR((valueRetrieved != null)
197                    ? valueRetrieved.getValueType()
198                    : null
199                ) + "\n" +
200            "\tConverting To Java-Type:  " + ((methodReturnJavaType != null)
201                    ? methodReturnJavaType.getCanonicalName()
202                    : "Java-Type Unknown"
203                );
204    }
205}