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